Stripe Integration Expert

#!/usr/bin/env python3
"""Stripe Checkout & Subscription Boilerplate Generator.

Generates production-ready Stripe Checkout integration code for different
frameworks. Includes checkout session creation, webhook handler, subscription
management, and customer portal setup.

Usage:
    python checkout_scaffolder.py --framework nextjs --features subscriptions,portal
    python checkout_scaffolder.py --framework express --features checkout,webhooks --json
    python checkout_scaffolder.py --list-frameworks
    python checkout_scaffolder.py --list-features
"""

import argparse
import json
import sys
import textwrap
from datetime import datetime

FRAMEWORKS = {
    "nextjs": "Next.js App Router (TypeScript)",
    "express": "Express.js (TypeScript)",
    "django": "Django (Python)",
}

FEATURES = {
    "checkout": "Checkout session creation endpoint",
    "webhooks": "Idempotent webhook handler with signature verification",
    "subscriptions": "Subscription management (upgrade, downgrade, cancel)",
    "portal": "Customer portal session endpoint",
    "usage": "Usage-based (metered) billing helpers",
}

# ---------------------------------------------------------------------------
# Code templates per framework per feature
# ---------------------------------------------------------------------------

TEMPLATES = {}

# ── Next.js ────────────────────────────────────────────────────────────────

TEMPLATES[("nextjs", "checkout")] = textwrap.dedent('''\
    // app/api/billing/checkout/route.ts
    import { NextResponse } from "next/server";
    import { stripe, PLANS, type PlanName, type BillingInterval } from "@/lib/stripe";
    import { getAuthUser } from "@/lib/auth";
    import { db } from "@/lib/db";

    export async function POST(req: Request) {
      const user = await getAuthUser();
      if (!user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });

      const { plan, interval = "monthly" } = (await req.json()) as {
        plan: PlanName;
        interval: BillingInterval;
      };

      if (!PLANS[plan]) {
        return NextResponse.json({ error: "Invalid plan" }, { status: 400 });
      }

      const priceId = PLANS[plan][interval];

      // Get or create Stripe customer (idempotent)
      let customerId = user.stripeCustomerId;
      if (!customerId) {
        const customer = await stripe.customers.create({
          email: user.email,
          metadata: { userId: user.id },
        });
        customerId = customer.id;
        await db.user.update({
          where: { id: user.id },
          data: { stripeCustomerId: customerId },
        });
      }

      const session = await stripe.checkout.sessions.create({
        customer: customerId,
        mode: "subscription",
        payment_method_types: ["card"],
        line_items: [{ price: priceId, quantity: 1 }],
        allow_promotion_codes: true,
        subscription_data: {
          trial_period_days: user.hasHadTrial ? undefined : 14,
          metadata: { userId: user.id, plan },
        },
        success_url: `${process.env.APP_URL}/dashboard?checkout=success&session_id={CHECKOUT_SESSION_ID}`,
        cancel_url: `${process.env.APP_URL}/pricing`,
        metadata: { userId: user.id },
      });

      return NextResponse.json({ url: session.url });
    }
''')

TEMPLATES[("nextjs", "webhooks")] = textwrap.dedent('''\
    // app/api/webhooks/stripe/route.ts
    import { NextResponse } from "next/server";
    import { headers } from "next/headers";
    import { stripe } from "@/lib/stripe";
    import { db } from "@/lib/db";
    import type Stripe from "stripe";

    async function isProcessed(eventId: string): Promise<boolean> {
      return !!(await db.stripeEvent.findUnique({ where: { id: eventId } }));
    }

    async function markProcessed(eventId: string, type: string) {
      await db.stripeEvent.create({ data: { id: eventId, type, processedAt: new Date() } });
    }

    export async function POST(req: Request) {
      const body = await req.text();
      const signature = headers().get("stripe-signature");
      if (!signature) return NextResponse.json({ error: "Missing signature" }, { status: 400 });

      let event: Stripe.Event;
      try {
        event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
      } catch (err) {
        console.error("Webhook signature verification failed:", err);
        return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
      }

      if (await isProcessed(event.id)) {
        return NextResponse.json({ received: true, deduplicated: true });
      }

      try {
        switch (event.type) {
          case "checkout.session.completed":
            await handleCheckoutCompleted(event.data.object as Stripe.Checkout.Session);
            break;
          case "customer.subscription.updated":
            await handleSubscriptionChange(event.data.object as Stripe.Subscription);
            break;
          case "customer.subscription.deleted":
            await handleSubscriptionDeleted(event.data.object as Stripe.Subscription);
            break;
          case "invoice.payment_succeeded":
            await handlePaymentSucceeded(event.data.object as Stripe.Invoice);
            break;
          case "invoice.payment_failed":
            await handlePaymentFailed(event.data.object as Stripe.Invoice);
            break;
          default:
            console.log(`Unhandled webhook: ${event.type}`);
        }

        await markProcessed(event.id, event.type);
        return NextResponse.json({ received: true });
      } catch (err) {
        console.error(`Webhook error [${event.type}]:`, err);
        return NextResponse.json({ error: "Processing failed" }, { status: 500 });
      }
    }

    // TODO: Implement handler functions (handleCheckoutCompleted, etc.)
    // See SKILL.md for full handler implementations.
''')

TEMPLATES[("nextjs", "subscriptions")] = textwrap.dedent('''\
    // lib/subscriptions.ts
    import { stripe } from "@/lib/stripe";

    export async function upgradeSubscription(subscriptionId: string, newPriceId: string) {
      const subscription = await stripe.subscriptions.retrieve(subscriptionId);
      return stripe.subscriptions.update(subscriptionId, {
        items: [{ id: subscription.items.data[0].id, price: newPriceId }],
        proration_behavior: "always_invoice",
        billing_cycle_anchor: "unchanged",
      });
    }

    export async function downgradeSubscription(subscriptionId: string, newPriceId: string) {
      const subscription = await stripe.subscriptions.retrieve(subscriptionId);
      return stripe.subscriptions.update(subscriptionId, {
        items: [{ id: subscription.items.data[0].id, price: newPriceId }],
        proration_behavior: "none",
        billing_cycle_anchor: "unchanged",
      });
    }

    export async function cancelSubscription(subscriptionId: string) {
      return stripe.subscriptions.update(subscriptionId, {
        cancel_at_period_end: true,
      });
    }

    export async function reactivateSubscription(subscriptionId: string) {
      return stripe.subscriptions.update(subscriptionId, {
        cancel_at_period_end: false,
      });
    }

    export async function previewProration(subscriptionId: string, newPriceId: string) {
      const subscription = await stripe.subscriptions.retrieve(subscriptionId);
      const invoice = await stripe.invoices.createPreview({
        customer: subscription.customer as string,
        subscription: subscriptionId,
        subscription_details: {
          items: [{ id: subscription.items.data[0].id, price: newPriceId }],
          proration_date: Math.floor(Date.now() / 1000),
        },
      });
      return {
        amountDue: invoice.amount_due,
        credit: invoice.total < 0 ? Math.abs(invoice.total) : 0,
        lineItems: invoice.lines.data.map((l) => ({ description: l.description, amount: l.amount })),
      };
    }
''')

TEMPLATES[("nextjs", "portal")] = textwrap.dedent('''\
    // app/api/billing/portal/route.ts
    import { NextResponse } from "next/server";
    import { stripe } from "@/lib/stripe";
    import { getAuthUser } from "@/lib/auth";

    export async function POST() {
      const user = await getAuthUser();
      if (!user?.stripeCustomerId) {
        return NextResponse.json({ error: "No billing account" }, { status: 400 });
      }

      const session = await stripe.billingPortal.sessions.create({
        customer: user.stripeCustomerId,
        return_url: `${process.env.APP_URL}/settings/billing`,
      });

      return NextResponse.json({ url: session.url });
    }
''')

TEMPLATES[("nextjs", "usage")] = textwrap.dedent('''\
    // lib/usage-billing.ts
    import { stripe } from "@/lib/stripe";
    import { db } from "@/lib/db";

    export async function reportUsage(subscriptionItemId: string, quantity: number, idempotencyKey?: string) {
      return stripe.subscriptionItems.createUsageRecord(
        subscriptionItemId,
        { quantity, timestamp: Math.floor(Date.now() / 1000), action: "increment" },
        { idempotencyKey },
      );
    }

    export async function trackApiUsage(userId: string) {
      const user = await db.user.findUnique({ where: { id: userId } });
      if (!user?.stripeSubscriptionId) return;

      const subscription = await stripe.subscriptions.retrieve(user.stripeSubscriptionId);
      const meteredItem = subscription.items.data.find(
        (item) => item.price.recurring?.usage_type === "metered",
      );

      if (meteredItem) {
        await reportUsage(meteredItem.id, 1, `${userId}-${Date.now()}`);
      }
    }
''')

# ── Express ────────────────────────────────────────────────────────────────

TEMPLATES[("express", "checkout")] = textwrap.dedent('''\
    // routes/billing.ts
    import { Router, Request, Response } from "express";
    import { stripe, PLANS } from "../lib/stripe";
    import { requireAuth } from "../middleware/auth";
    import { db } from "../lib/db";

    const router = Router();

    router.post("/checkout", requireAuth, async (req: Request, res: Response) => {
      const { plan, interval = "monthly" } = req.body;
      const user = req.user!;

      if (!PLANS[plan]) return res.status(400).json({ error: "Invalid plan" });

      let customerId = user.stripeCustomerId;
      if (!customerId) {
        const customer = await stripe.customers.create({
          email: user.email,
          metadata: { userId: user.id },
        });
        customerId = customer.id;
        await db.user.update({ where: { id: user.id }, data: { stripeCustomerId: customerId } });
      }

      const session = await stripe.checkout.sessions.create({
        customer: customerId,
        mode: "subscription",
        line_items: [{ price: PLANS[plan][interval], quantity: 1 }],
        subscription_data: { metadata: { userId: user.id, plan } },
        success_url: `${process.env.APP_URL}/dashboard?checkout=success`,
        cancel_url: `${process.env.APP_URL}/pricing`,
        metadata: { userId: user.id },
      });

      res.json({ url: session.url });
    });

    export default router;
''')

TEMPLATES[("express", "webhooks")] = textwrap.dedent('''\
    // routes/webhooks.ts
    import { Router, Request, Response } from "express";
    import { stripe } from "../lib/stripe";
    import { db } from "../lib/db";
    import type Stripe from "stripe";

    const router = Router();

    // IMPORTANT: Use express.raw() middleware for this route, not express.json()
    router.post(
      "/stripe",
      async (req: Request, res: Response) => {
        const sig = req.headers["stripe-signature"] as string;
        if (!sig) return res.status(400).json({ error: "Missing signature" });

        let event: Stripe.Event;
        try {
          event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
        } catch (err) {
          console.error("Webhook signature failed:", err);
          return res.status(400).json({ error: "Invalid signature" });
        }

        // Idempotency check
        const existing = await db.stripeEvent.findUnique({ where: { id: event.id } });
        if (existing) return res.json({ received: true, deduplicated: true });

        try {
          // Handle event types here (see SKILL.md for full handlers)
          switch (event.type) {
            case "checkout.session.completed":
            case "customer.subscription.updated":
            case "customer.subscription.deleted":
            case "invoice.payment_succeeded":
            case "invoice.payment_failed":
              console.log(`Processing: ${event.type}`);
              // TODO: Implement handlers
              break;
            default:
              console.log(`Unhandled: ${event.type}`);
          }

          await db.stripeEvent.create({ data: { id: event.id, type: event.type } });
          res.json({ received: true });
        } catch (err) {
          console.error(`Webhook error [${event.type}]:`, err);
          res.status(500).json({ error: "Processing failed" });
        }
      },
    );

    export default router;
''')

TEMPLATES[("express", "subscriptions")] = TEMPLATES[("nextjs", "subscriptions")]
TEMPLATES[("express", "portal")] = textwrap.dedent('''\
    // routes/portal.ts (add to billing router)
    import { Router, Request, Response } from "express";
    import { stripe } from "../lib/stripe";
    import { requireAuth } from "../middleware/auth";

    const router = Router();

    router.post("/portal", requireAuth, async (req: Request, res: Response) => {
      const user = req.user!;
      if (!user.stripeCustomerId) return res.status(400).json({ error: "No billing account" });

      const session = await stripe.billingPortal.sessions.create({
        customer: user.stripeCustomerId,
        return_url: `${process.env.APP_URL}/settings/billing`,
      });

      res.json({ url: session.url });
    });

    export default router;
''')

TEMPLATES[("express", "usage")] = TEMPLATES[("nextjs", "usage")]

# ── Django ─────────────────────────────────────────────────────────────────

TEMPLATES[("django", "checkout")] = textwrap.dedent('''\
    # billing/views.py
    import json
    import stripe
    from django.conf import settings
    from django.http import JsonResponse
    from django.views.decorators.http import require_POST
    from django.contrib.auth.decorators import login_required
    from .models import UserProfile

    stripe.api_key = settings.STRIPE_SECRET_KEY

    PLANS = {
        "starter": {"monthly": settings.STRIPE_STARTER_MONTHLY, "yearly": settings.STRIPE_STARTER_YEARLY},
        "pro": {"monthly": settings.STRIPE_PRO_MONTHLY, "yearly": settings.STRIPE_PRO_YEARLY},
    }

    @require_POST
    @login_required
    def create_checkout(request):
        data = json.loads(request.body)
        plan = data.get("plan")
        interval = data.get("interval", "monthly")

        if plan not in PLANS:
            return JsonResponse({"error": "Invalid plan"}, status=400)

        profile = request.user.profile
        if not profile.stripe_customer_id:
            customer = stripe.Customer.create(
                email=request.user.email,
                metadata={"userId": str(request.user.id)},
            )
            profile.stripe_customer_id = customer.id
            profile.save()

        session = stripe.checkout.Session.create(
            customer=profile.stripe_customer_id,
            mode="subscription",
            line_items=[{"price": PLANS[plan][interval], "quantity": 1}],
            subscription_data={"metadata": {"userId": str(request.user.id), "plan": plan}},
            success_url=f"{settings.APP_URL}/dashboard/?checkout=success&session_id={{CHECKOUT_SESSION_ID}}",
            cancel_url=f"{settings.APP_URL}/pricing/",
            metadata={"userId": str(request.user.id)},
        )

        return JsonResponse({"url": session.url})
''')

TEMPLATES[("django", "webhooks")] = textwrap.dedent('''\
    # billing/webhooks.py
    import stripe
    from django.conf import settings
    from django.http import JsonResponse
    from django.views.decorators.csrf import csrf_exempt
    from django.views.decorators.http import require_POST
    from .models import StripeEvent, UserProfile

    stripe.api_key = settings.STRIPE_SECRET_KEY

    @csrf_exempt
    @require_POST
    def stripe_webhook(request):
        payload = request.body
        sig_header = request.META.get("HTTP_STRIPE_SIGNATURE")

        if not sig_header:
            return JsonResponse({"error": "Missing signature"}, status=400)

        try:
            event = stripe.Webhook.construct_event(payload, sig_header, settings.STRIPE_WEBHOOK_SECRET)
        except (ValueError, stripe.error.SignatureVerificationError) as e:
            return JsonResponse({"error": "Invalid signature"}, status=400)

        # Idempotency check
        if StripeEvent.objects.filter(event_id=event["id"]).exists():
            return JsonResponse({"received": True, "deduplicated": True})

        try:
            event_type = event["type"]
            # TODO: Implement handlers for each event type
            if event_type == "checkout.session.completed":
                pass  # handle checkout
            elif event_type == "customer.subscription.updated":
                pass  # handle subscription change
            elif event_type == "customer.subscription.deleted":
                pass  # handle cancellation
            elif event_type == "invoice.payment_failed":
                pass  # handle payment failure

            StripeEvent.objects.create(event_id=event["id"], event_type=event_type)
            return JsonResponse({"received": True})
        except Exception as e:
            return JsonResponse({"error": "Processing failed"}, status=500)
''')

TEMPLATES[("django", "subscriptions")] = textwrap.dedent('''\
    # billing/subscriptions.py
    import stripe
    from django.conf import settings

    stripe.api_key = settings.STRIPE_SECRET_KEY

    def upgrade_subscription(subscription_id: str, new_price_id: str):
        subscription = stripe.Subscription.retrieve(subscription_id)
        return stripe.Subscription.modify(
            subscription_id,
            items=[{"id": subscription["items"]["data"][0]["id"], "price": new_price_id}],
            proration_behavior="always_invoice",
            billing_cycle_anchor="unchanged",
        )

    def downgrade_subscription(subscription_id: str, new_price_id: str):
        subscription = stripe.Subscription.retrieve(subscription_id)
        return stripe.Subscription.modify(
            subscription_id,
            items=[{"id": subscription["items"]["data"][0]["id"], "price": new_price_id}],
            proration_behavior="none",
        )

    def cancel_subscription(subscription_id: str):
        return stripe.Subscription.modify(subscription_id, cancel_at_period_end=True)

    def reactivate_subscription(subscription_id: str):
        return stripe.Subscription.modify(subscription_id, cancel_at_period_end=False)
''')

TEMPLATES[("django", "portal")] = textwrap.dedent('''\
    # billing/views.py (add to existing views)
    @require_POST
    @login_required
    def customer_portal(request):
        profile = request.user.profile
        if not profile.stripe_customer_id:
            return JsonResponse({"error": "No billing account"}, status=400)

        session = stripe.billing_portal.Session.create(
            customer=profile.stripe_customer_id,
            return_url=f"{settings.APP_URL}/settings/billing/",
        )

        return JsonResponse({"url": session.url})
''')

TEMPLATES[("django", "usage")] = textwrap.dedent('''\
    # billing/usage.py
    import time
    import stripe
    from django.conf import settings

    stripe.api_key = settings.STRIPE_SECRET_KEY

    def report_usage(subscription_item_id: str, quantity: int, idempotency_key: str = None):
        return stripe.SubscriptionItem.create_usage_record(
            subscription_item_id,
            quantity=quantity,
            timestamp=int(time.time()),
            action="increment",
            idempotency_key=idempotency_key,
        )
''')


def generate_scaffold(framework, features):
    """Generate code scaffold for the given framework and features."""
    output = {
        "framework": framework,
        "framework_name": FRAMEWORKS[framework],
        "features": features,
        "generated_at": datetime.now().isoformat(),
        "files": [],
    }

    for feature in features:
        key = (framework, feature)
        if key not in TEMPLATES:
            output["files"].append({
                "feature": feature,
                "error": f"No template available for {framework}/{feature}",
            })
            continue

        code = TEMPLATES[key]
        # Extract filename from first comment line
        first_line = code.strip().splitlines()[0]
        filename = first_line.strip("/ #").strip()

        output["files"].append({
            "feature": feature,
            "filename": filename,
            "code": code,
        })

    return output


def format_human(output):
    """Format scaffold output for human-readable display."""
    lines = []
    lines.append("=" * 64)
    lines.append(f"  Stripe Checkout Scaffolder - {output['framework_name']}")
    lines.append("=" * 64)
    lines.append(f"\nFeatures: {', '.join(output['features'])}")
    lines.append(f"Generated: {output['generated_at']}")

    for file_info in output["files"]:
        lines.append(f"\n{'─' * 64}")
        if "error" in file_info:
            lines.append(f"[ERROR] {file_info['feature']}: {file_info['error']}")
            continue

        lines.append(f"Feature: {file_info['feature']}")
        lines.append(f"File: {file_info['filename']}")
        lines.append(f"{'─' * 64}")
        lines.append(file_info["code"])

    lines.append("=" * 64)
    lines.append("\nNext steps:")
    lines.append("  1. Copy generated files into your project")
    lines.append("  2. Set environment variables: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, APP_URL")
    lines.append("  3. Configure price IDs in environment for each plan")
    lines.append("  4. Set up webhook endpoint in Stripe Dashboard")
    lines.append("  5. Test with: stripe listen --forward-to localhost:3000/api/webhooks/stripe")
    lines.append("=" * 64)

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Generate Stripe Checkout and subscription boilerplate code for different frameworks.",
        epilog="Example: %(prog)s --framework nextjs --features checkout,webhooks,subscriptions",
    )
    parser.add_argument(
        "--framework", "-f",
        choices=list(FRAMEWORKS.keys()),
        help="Target framework for code generation",
    )
    parser.add_argument(
        "--features",
        help="Comma-separated list of features to generate (checkout,webhooks,subscriptions,portal,usage)",
    )
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON")
    parser.add_argument("--list-frameworks", action="store_true", help="List available frameworks")
    parser.add_argument("--list-features", action="store_true", help="List available features")
    parser.add_argument("--all", action="store_true", help="Generate all features for the selected framework")

    args = parser.parse_args()

    if args.list_frameworks:
        if args.json_output:
            print(json.dumps(FRAMEWORKS, indent=2))
        else:
            print("Available frameworks:")
            for key, name in FRAMEWORKS.items():
                print(f"  {key:12s} - {name}")
        sys.exit(0)

    if args.list_features:
        if args.json_output:
            print(json.dumps(FEATURES, indent=2))
        else:
            print("Available features:")
            for key, desc in FEATURES.items():
                print(f"  {key:16s} - {desc}")
        sys.exit(0)

    if not args.framework:
        parser.error("--framework is required (use --list-frameworks to see options)")

    if args.all:
        features = list(FEATURES.keys())
    elif not args.features:
        parser.error("--features is required (use --list-features to see options, or --all for everything)")
    else:
        features = [f.strip() for f in args.features.split(",")]
        invalid = [f for f in features if f not in FEATURES]
        if invalid:
            parser.error(f"Unknown feature(s): {', '.join(invalid)}. Use --list-features to see options.")

    output = generate_scaffold(args.framework, features)

    if args.json_output:
        print(json.dumps(output, indent=2))
    else:
        print(format_human(output))

    sys.exit(0)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Stripe Integration Code Auditor.

Scans a project for common Stripe integration anti-patterns: hardcoded API keys,
missing idempotency keys, unhandled webhook events, unpinned API versions,
insecure key handling, and missing error handling around Stripe API calls.

Usage:
    python integration_auditor.py /path/to/project
    python integration_auditor.py /path/to/project --json
    python integration_auditor.py /path/to/project --severity critical
"""

import argparse
import json
import os
import re
import sys
from pathlib import Path

CODE_EXTENSIONS = {".ts", ".tsx", ".js", ".jsx", ".py", ".rb", ".go", ".java", ".php"}
SKIP_DIRS = {"node_modules", ".git", "__pycache__", "dist", "build", ".next", "venv", ".venv", "vendor"}


def collect_source_files(project_dir):
    """Walk the project and collect source files with their contents."""
    files = {}
    for root, dirs, filenames in os.walk(project_dir):
        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
        for fname in filenames:
            ext = os.path.splitext(fname)[1]
            if ext not in CODE_EXTENSIONS:
                continue
            fpath = os.path.join(root, fname)
            try:
                with open(fpath, "r", encoding="utf-8", errors="replace") as f:
                    files[fpath] = f.read()
            except (OSError, IOError):
                continue
    return files


def relative_path(fpath, project_dir):
    """Return path relative to the project directory."""
    try:
        return str(Path(fpath).relative_to(project_dir))
    except ValueError:
        return fpath


def audit_hardcoded_keys(files, project_dir):
    """Detect hardcoded Stripe API keys in source code."""
    findings = []
    patterns = [
        (r'sk_live_[a-zA-Z0-9]{20,}', "Live secret key hardcoded in source. This is a critical security risk."),
        (r'sk_test_[a-zA-Z0-9]{20,}', "Test secret key hardcoded in source. Move to environment variable."),
        (r'pk_live_[a-zA-Z0-9]{20,}', "Live publishable key hardcoded. Consider using environment variable for flexibility."),
        (r'whsec_[a-zA-Z0-9]{20,}', "Webhook signing secret hardcoded in source."),
        (r'rk_live_[a-zA-Z0-9]{20,}', "Live restricted key hardcoded in source."),
    ]

    for fpath, content in files.items():
        rel = relative_path(fpath, project_dir)
        for line_no, line in enumerate(content.splitlines(), 1):
            for pattern, message in patterns:
                if re.search(pattern, line):
                    severity = "critical" if "live" in pattern else "warning"
                    findings.append({
                        "severity": severity,
                        "rule": "KEY-001",
                        "message": message,
                        "file": rel,
                        "line": line_no,
                        "fix": "Use environment variables: process.env.STRIPE_SECRET_KEY or os.environ['STRIPE_SECRET_KEY'].",
                    })
    return findings


def audit_api_version_pinning(files, project_dir):
    """Check if Stripe API version is pinned in client initialization."""
    findings = []
    has_stripe_init = False
    has_version_pin = False

    for fpath, content in files.items():
        # Detect Stripe client initialization
        if re.search(r'new\s+Stripe\s*\(', content) or re.search(r'stripe\s*=\s*stripe\.', content, re.IGNORECASE):
            has_stripe_init = True
            if re.search(r'apiVersion\s*[=:]\s*["\']', content) or re.search(r'api_version\s*[=:]\s*["\']', content):
                has_version_pin = True

    if has_stripe_init and not has_version_pin:
        findings.append({
            "severity": "warning",
            "rule": "VER-001",
            "message": "Stripe client initialized without pinning apiVersion. Breaking changes may occur on Stripe updates.",
            "fix": "Pin apiVersion in the Stripe constructor: new Stripe(key, { apiVersion: '2024-12-18.acacia' }).",
        })
    elif has_stripe_init and has_version_pin:
        findings.append({
            "severity": "pass",
            "rule": "VER-001",
            "message": "Stripe API version is pinned.",
        })
    return findings


def audit_idempotency_keys(files, project_dir):
    """Check for idempotency key usage on mutating Stripe API calls."""
    findings = []
    mutating_calls = [
        r"\.create\s*\(",
        r"\.update\s*\(",
        r"\.del\s*\(",
        r"\.cancel\s*\(",
    ]
    idempotency_pattern = r"idempotencyKey|idempotency_key"

    for fpath, content in files.items():
        rel = relative_path(fpath, project_dir)
        # Only check files that reference Stripe
        if not re.search(r"stripe", content, re.IGNORECASE):
            continue

        has_mutating = False
        has_idempotency = bool(re.search(idempotency_pattern, content, re.IGNORECASE))

        for pattern in mutating_calls:
            if re.search(pattern, content):
                has_mutating = True
                break

        if has_mutating and not has_idempotency:
            findings.append({
                "severity": "warning",
                "rule": "IDEM-001",
                "message": f"Stripe mutating API calls found without idempotency keys: {rel}",
                "file": rel,
                "fix": "Pass idempotencyKey to .create() calls to prevent duplicate charges on retries.",
            })

    return findings


def audit_error_handling(files, project_dir):
    """Check for proper error handling around Stripe API calls."""
    findings = []

    for fpath, content in files.items():
        rel = relative_path(fpath, project_dir)
        if not re.search(r"stripe", content, re.IGNORECASE):
            continue

        lines = content.splitlines()
        for i, line in enumerate(lines):
            # Look for await stripe.X calls outside of try blocks
            if re.search(r"await\s+stripe\.", line) or re.search(r"stripe\.\w+\.\w+\(", line):
                # Check if we are inside a try block (simple heuristic: look back 10 lines for "try")
                context_start = max(0, i - 10)
                context = "\n".join(lines[context_start:i])
                if "try" not in context and "catch" not in context and ".then(" not in line:
                    findings.append({
                        "severity": "info",
                        "rule": "ERR-001",
                        "message": f"Stripe API call may lack error handling: {rel}:{i + 1}",
                        "file": rel,
                        "line": i + 1,
                        "fix": "Wrap Stripe API calls in try/catch to handle network errors and API failures gracefully.",
                    })
    return findings


def audit_price_id_handling(files, project_dir):
    """Check for hardcoded Stripe price IDs instead of environment variables."""
    findings = []
    price_pattern = r'["\']price_[a-zA-Z0-9]{10,}["\']'

    for fpath, content in files.items():
        rel = relative_path(fpath, project_dir)
        for line_no, line in enumerate(content.splitlines(), 1):
            if re.search(price_pattern, line):
                # Ignore comments and test files
                stripped = line.strip()
                if stripped.startswith("//") or stripped.startswith("#") or stripped.startswith("*"):
                    continue
                if "test" in fpath.lower() or "spec" in fpath.lower() or "mock" in fpath.lower():
                    continue
                findings.append({
                    "severity": "warning",
                    "rule": "PRICE-001",
                    "message": f"Hardcoded price ID found: {rel}:{line_no}",
                    "file": rel,
                    "line": line_no,
                    "fix": "Move price IDs to environment variables for test/production parity.",
                })
    return findings


def audit_metadata_on_checkout(files, project_dir):
    """Check that checkout sessions include user metadata for webhook linking."""
    findings = []

    for fpath, content in files.items():
        rel = relative_path(fpath, project_dir)
        # Look for checkout session creation
        if re.search(r"checkout\.sessions\.create", content, re.IGNORECASE):
            # Check for metadata in the surrounding code block
            if not re.search(r"metadata\s*[=:{]", content):
                findings.append({
                    "severity": "critical",
                    "rule": "META-001",
                    "message": f"Checkout session created without metadata in {rel}. Cannot link subscription to user in webhooks.",
                    "file": rel,
                    "fix": "Add metadata: { userId: user.id } to checkout session creation.",
                })

    return findings


def audit_webhook_endpoint_security(files, project_dir):
    """Check for common webhook endpoint security issues."""
    findings = []

    for fpath, content in files.items():
        rel = relative_path(fpath, project_dir)
        if "webhook" not in fpath.lower():
            continue

        # Check for JSON body parsing before signature verification
        lines = content.splitlines()
        json_parse_line = None
        sig_verify_line = None

        for i, line in enumerate(lines):
            if re.search(r"json\.parse|JSON\.parse|\.json\(\)", line, re.IGNORECASE) and json_parse_line is None:
                json_parse_line = i
            if re.search(r"constructEvent|construct_event|verify_header", line, re.IGNORECASE) and sig_verify_line is None:
                sig_verify_line = i

        if json_parse_line is not None and sig_verify_line is not None:
            if json_parse_line < sig_verify_line:
                findings.append({
                    "severity": "warning",
                    "rule": "SEC-002",
                    "message": f"JSON parsing occurs before signature verification in {rel}. This can break signature checks.",
                    "file": rel,
                    "fix": "Read the raw request body first for signature verification, then parse JSON.",
                })

    return findings


def audit_env_file_exposure(project_dir):
    """Check that .env files with Stripe keys are gitignored."""
    findings = []
    gitignore_path = os.path.join(project_dir, ".gitignore")
    gitignore_content = ""
    if os.path.isfile(gitignore_path):
        try:
            with open(gitignore_path, "r") as f:
                gitignore_content = f.read()
        except (OSError, IOError):
            pass

    has_env_in_gitignore = bool(re.search(r"\.env", gitignore_content))

    # Check for .env files with Stripe keys
    for fname in os.listdir(project_dir):
        if fname.startswith(".env") and os.path.isfile(os.path.join(project_dir, fname)):
            try:
                with open(os.path.join(project_dir, fname), "r") as f:
                    env_content = f.read()
                if re.search(r"STRIPE_SECRET_KEY|sk_live_|sk_test_", env_content):
                    if not has_env_in_gitignore:
                        findings.append({
                            "severity": "critical",
                            "rule": "ENV-001",
                            "message": f"{fname} contains Stripe keys but .env is not in .gitignore.",
                            "fix": "Add .env* to your .gitignore immediately to prevent key exposure.",
                        })
            except (OSError, IOError):
                continue
    return findings


def run_audit(project_dir, min_severity="info"):
    """Run all audit checks and return results."""
    severity_order = {"critical": 0, "warning": 1, "info": 2, "pass": 3}
    min_level = severity_order.get(min_severity, 2)

    files = collect_source_files(project_dir)
    results = {
        "project": str(project_dir),
        "files_scanned": len(files),
        "findings": [],
        "summary": {"critical": 0, "warning": 0, "info": 0, "pass": 0},
    }

    if not files:
        results["findings"].append({
            "severity": "warning",
            "rule": "SCAN-001",
            "message": "No source files found to audit.",
        })
        results["summary"]["warning"] = 1
        return results

    # Run all audit checks
    all_findings = []
    all_findings.extend(audit_hardcoded_keys(files, project_dir))
    all_findings.extend(audit_api_version_pinning(files, project_dir))
    all_findings.extend(audit_idempotency_keys(files, project_dir))
    all_findings.extend(audit_error_handling(files, project_dir))
    all_findings.extend(audit_price_id_handling(files, project_dir))
    all_findings.extend(audit_metadata_on_checkout(files, project_dir))
    all_findings.extend(audit_webhook_endpoint_security(files, project_dir))
    all_findings.extend(audit_env_file_exposure(project_dir))

    # Filter by minimum severity
    for finding in all_findings:
        sev = finding.get("severity", "info")
        if severity_order.get(sev, 2) <= min_level:
            results["findings"].append(finding)
            if sev in results["summary"]:
                results["summary"][sev] += 1

    # Overall status
    results["status"] = "FAIL" if results["summary"]["critical"] > 0 else "PASS"
    return results


def format_human(results):
    """Format results for human-readable terminal output."""
    lines = []
    lines.append("=" * 64)
    lines.append("  Stripe Integration Auditor")
    lines.append("=" * 64)
    lines.append(f"\nProject: {results['project']}")
    lines.append(f"Files scanned: {results['files_scanned']}")

    severity_icons = {
        "critical": "[CRITICAL]",
        "warning":  "[WARNING] ",
        "info":     "[INFO]    ",
        "pass":     "[PASS]    ",
    }

    lines.append(f"\n{'─' * 64}")
    lines.append("FINDINGS:")
    lines.append(f"{'─' * 64}")

    # Group by severity
    for sev in ("critical", "warning", "info", "pass"):
        sev_findings = [f for f in results["findings"] if f.get("severity") == sev]
        if not sev_findings:
            continue
        for finding in sev_findings:
            icon = severity_icons.get(sev, "[?]")
            loc = ""
            if "file" in finding:
                loc = f" ({finding['file']}"
                if "line" in finding:
                    loc += f":{finding['line']}"
                loc += ")"
            lines.append(f"\n  {icon} {finding['rule']}: {finding['message']}{loc}")
            if "fix" in finding:
                lines.append(f"    Fix: {finding['fix']}")

    lines.append(f"\n{'─' * 64}")
    s = results["summary"]
    lines.append(f"Summary: {s['critical']} critical, {s['warning']} warnings, {s['info']} info, {s['pass']} passed")
    lines.append(f"Status: {results['status']}")
    lines.append("=" * 64)

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Audit Stripe integration code for common issues: hardcoded keys, missing idempotency, unhandled events.",
        epilog="Example: %(prog)s /path/to/project --severity warning --json",
    )
    parser.add_argument("project_dir", help="Path to the project directory to audit")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output results as JSON")
    parser.add_argument(
        "--severity",
        choices=["critical", "warning", "info"],
        default="info",
        help="Minimum severity level to report (default: info)",
    )

    args = parser.parse_args()

    project_dir = Path(args.project_dir).resolve()
    if not project_dir.is_dir():
        print(f"Error: '{project_dir}' is not a valid directory.", file=sys.stderr)
        sys.exit(2)

    results = run_audit(project_dir, min_severity=args.severity)

    if args.json_output:
        print(json.dumps(results, indent=2))
    else:
        print(format_human(results))

    sys.exit(0 if results["status"] == "PASS" else 1)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Stripe Webhook Endpoint Configuration Validator.

Validates webhook endpoint configurations, signature verification setup,
and event handling completeness. Scans project files for common webhook
misconfigurations that cause silent billing failures in production.

Usage:
    python webhook_validator.py /path/to/project
    python webhook_validator.py /path/to/project --json
    python webhook_validator.py /path/to/project --strict
"""

import argparse
import json
import os
import re
import sys
from pathlib import Path


# Critical webhook events that every SaaS billing integration must handle
CRITICAL_EVENTS = [
    "checkout.session.completed",
    "customer.subscription.created",
    "customer.subscription.updated",
    "customer.subscription.deleted",
    "invoice.payment_succeeded",
    "invoice.payment_failed",
]

# Recommended events for a production-quality integration
RECOMMENDED_EVENTS = [
    "customer.subscription.trial_will_end",
    "invoice.payment_action_required",
    "customer.updated",
    "payment_intent.payment_failed",
    "charge.dispute.created",
]

# File extensions to scan
CODE_EXTENSIONS = {".ts", ".tsx", ".js", ".jsx", ".py", ".rb", ".go", ".java", ".php"}

# Patterns that indicate webhook handling code
WEBHOOK_FILE_PATTERNS = [
    r"webhook",
    r"stripe.*route",
    r"stripe.*handler",
    r"stripe.*endpoint",
]


def find_webhook_files(project_dir):
    """Locate files likely containing webhook handler code."""
    matches = []
    for root, _dirs, files in os.walk(project_dir):
        # Skip common non-source directories
        basename = os.path.basename(root)
        if basename in ("node_modules", ".git", "__pycache__", "dist", "build", ".next", "venv"):
            continue
        for fname in files:
            ext = os.path.splitext(fname)[1]
            if ext not in CODE_EXTENSIONS:
                continue
            fpath = os.path.join(root, fname)
            name_lower = fname.lower()
            if any(re.search(p, name_lower) for p in WEBHOOK_FILE_PATTERNS):
                matches.append(fpath)
    return matches


def read_file_safe(fpath):
    """Read file contents, returning empty string on failure."""
    try:
        with open(fpath, "r", encoding="utf-8", errors="replace") as f:
            return f.read()
    except (OSError, IOError):
        return ""


def scan_all_source_files(project_dir):
    """Collect all source file contents for broad pattern matching."""
    contents = {}
    for root, _dirs, files in os.walk(project_dir):
        basename = os.path.basename(root)
        if basename in ("node_modules", ".git", "__pycache__", "dist", "build", ".next", "venv"):
            continue
        for fname in files:
            ext = os.path.splitext(fname)[1]
            if ext not in CODE_EXTENSIONS:
                continue
            fpath = os.path.join(root, fname)
            contents[fpath] = read_file_safe(fpath)
    return contents


def check_signature_verification(webhook_files, all_contents):
    """Check that webhook signature verification is implemented."""
    findings = []
    sig_patterns = [
        r"constructEvent",               # stripe.webhooks.constructEvent (Node)
        r"Webhook\.construct_event",      # stripe.Webhook.construct_event (Python)
        r"webhook\.ConstructEvent",       # Go
        r"Stripe::Webhook\.construct",    # Ruby
        r"verify_header",                 # Alternative pattern
        r"stripe-signature",             # Reading the header
    ]

    has_verification = False
    for fpath in webhook_files:
        content = all_contents.get(fpath, "")
        for pattern in sig_patterns:
            if re.search(pattern, content, re.IGNORECASE):
                has_verification = True
                break

    if not has_verification:
        findings.append({
            "severity": "critical",
            "rule": "SIG-001",
            "message": "No webhook signature verification detected. Webhooks are vulnerable to forgery.",
            "fix": "Use stripe.webhooks.constructEvent(body, sig, secret) to verify signatures before processing.",
        })
    else:
        findings.append({
            "severity": "pass",
            "rule": "SIG-001",
            "message": "Webhook signature verification detected.",
        })

    # Check for raw body parsing (required for signature verification)
    raw_body_patterns = [
        r"req\.text\(\)",           # Next.js App Router
        r"raw\s*[:(]",             # express.raw() or bodyParser.raw()
        r"getRawBody",             # raw-body package
        r"bodyParser\.raw",        # Express
        r"request\.body",          # Django/Flask raw
    ]
    has_raw_body = False
    for fpath in webhook_files:
        content = all_contents.get(fpath, "")
        for pattern in raw_body_patterns:
            if re.search(pattern, content):
                has_raw_body = True
                break

    if has_verification and not has_raw_body:
        findings.append({
            "severity": "warning",
            "rule": "SIG-002",
            "message": "Signature verification found but raw body parsing not detected. JSON-parsed bodies will fail verification.",
            "fix": "Ensure the request body is read as raw text/buffer before passing to constructEvent.",
        })

    return findings


def check_event_handling(webhook_files, all_contents):
    """Check which Stripe events are handled."""
    findings = []
    handled_events = set()
    all_webhook_content = ""

    for fpath in webhook_files:
        content = all_contents.get(fpath, "")
        all_webhook_content += content
        # Match event type strings in code
        event_matches = re.findall(r'["\']([a-z]+\.[a-z_.]+)["\']', content)
        for ev in event_matches:
            if ev.count(".") >= 1 and any(
                ev.startswith(prefix)
                for prefix in ("checkout.", "customer.", "invoice.", "payment_intent.", "charge.", "subscription_schedule.")
            ):
                handled_events.add(ev)

    # Check critical events
    missing_critical = []
    for event in CRITICAL_EVENTS:
        if event not in handled_events:
            missing_critical.append(event)

    if missing_critical:
        findings.append({
            "severity": "critical",
            "rule": "EVT-001",
            "message": f"Missing {len(missing_critical)} critical webhook event(s): {', '.join(missing_critical)}",
            "fix": "Add handlers for all critical billing events to prevent silent payment failures.",
            "missing_events": missing_critical,
        })
    else:
        findings.append({
            "severity": "pass",
            "rule": "EVT-001",
            "message": f"All {len(CRITICAL_EVENTS)} critical webhook events are handled.",
        })

    # Check recommended events
    missing_recommended = []
    for event in RECOMMENDED_EVENTS:
        if event not in handled_events:
            missing_recommended.append(event)

    if missing_recommended:
        findings.append({
            "severity": "info",
            "rule": "EVT-002",
            "message": f"Missing {len(missing_recommended)} recommended event(s): {', '.join(missing_recommended)}",
            "fix": "Consider handling these events for a more robust integration.",
            "missing_events": missing_recommended,
        })

    return findings, handled_events


def check_idempotency(webhook_files, all_contents):
    """Check for idempotent webhook processing."""
    findings = []
    idempotency_patterns = [
        r"isProcessed|already.?processed|event.?id.*find|findUnique.*event",
        r"markProcessed|mark.?as.?processed|stripeEvent.*create",
        r"idempoten",
        r"dedup|de.?dup|deduplicate",
        r"processed.?event",
    ]

    has_idempotency = False
    for fpath in webhook_files:
        content = all_contents.get(fpath, "")
        for pattern in idempotency_patterns:
            if re.search(pattern, content, re.IGNORECASE):
                has_idempotency = True
                break

    if not has_idempotency:
        findings.append({
            "severity": "critical",
            "rule": "IDEM-001",
            "message": "No idempotency mechanism detected in webhook handlers. Stripe retries will cause duplicate processing.",
            "fix": "Track processed event IDs in a database table and skip already-handled events.",
        })
    else:
        findings.append({
            "severity": "pass",
            "rule": "IDEM-001",
            "message": "Webhook idempotency mechanism detected.",
        })

    return findings


def check_error_handling(webhook_files, all_contents):
    """Check for proper error handling and retry behavior."""
    findings = []

    for fpath in webhook_files:
        content = all_contents.get(fpath, "")
        # Check for catch blocks that always return 200
        if re.search(r"catch.*\{[^}]*200[^}]*\}", content, re.DOTALL):
            findings.append({
                "severity": "warning",
                "rule": "ERR-001",
                "message": f"Webhook handler may return 200 on errors, preventing Stripe retries: {os.path.basename(fpath)}",
                "fix": "Return 500 on processing errors so Stripe retries the webhook delivery.",
                "file": fpath,
            })

    # Check for try/catch around event processing
    has_try_catch = False
    for fpath in webhook_files:
        content = all_contents.get(fpath, "")
        if re.search(r"try\s*\{", content) or re.search(r"try:", content):
            has_try_catch = True
            break

    if not has_try_catch and webhook_files:
        findings.append({
            "severity": "warning",
            "rule": "ERR-002",
            "message": "No try/catch blocks found in webhook handlers. Unhandled errors may crash the endpoint.",
            "fix": "Wrap event processing in try/catch and return appropriate HTTP status codes.",
        })

    return findings


def check_webhook_secret_config(all_contents):
    """Check that webhook secret is loaded from environment, not hardcoded."""
    findings = []

    for fpath, content in all_contents.items():
        # Look for hardcoded webhook secrets
        if re.search(r'whsec_[a-zA-Z0-9]{20,}', content):
            findings.append({
                "severity": "critical",
                "rule": "SEC-001",
                "message": f"Hardcoded webhook signing secret found in {os.path.basename(fpath)}",
                "fix": "Move webhook secrets to environment variables (STRIPE_WEBHOOK_SECRET).",
                "file": fpath,
            })

    # Check for env var usage
    has_env_secret = False
    for content in all_contents.values():
        if re.search(r"STRIPE_WEBHOOK_SECRET|webhook.?secret", content, re.IGNORECASE):
            has_env_secret = True
            break

    if not has_env_secret:
        findings.append({
            "severity": "warning",
            "rule": "SEC-002",
            "message": "No STRIPE_WEBHOOK_SECRET environment variable reference found.",
            "fix": "Define STRIPE_WEBHOOK_SECRET in your environment and reference it in webhook verification.",
        })

    return findings


def run_validation(project_dir, strict=False):
    """Run all webhook validation checks."""
    results = {
        "project": str(project_dir),
        "webhook_files": [],
        "findings": [],
        "summary": {"critical": 0, "warning": 0, "info": 0, "pass": 0},
    }

    # Find webhook files
    webhook_files = find_webhook_files(project_dir)
    results["webhook_files"] = [str(f) for f in webhook_files]

    if not webhook_files:
        results["findings"].append({
            "severity": "critical",
            "rule": "SETUP-001",
            "message": "No webhook handler files found in the project.",
            "fix": "Create a webhook endpoint (e.g., /api/webhooks/stripe) to handle Stripe events.",
        })
        results["summary"]["critical"] = 1
        return results

    # Scan all source files
    all_contents = scan_all_source_files(project_dir)

    # Run all checks
    checks = [
        check_signature_verification(webhook_files, all_contents),
        check_idempotency(webhook_files, all_contents),
        check_error_handling(webhook_files, all_contents),
        check_webhook_secret_config(all_contents),
    ]

    for check_findings in checks:
        results["findings"].extend(check_findings)

    # Event handling check returns extra data
    event_findings, handled_events = check_event_handling(webhook_files, all_contents)
    results["findings"].extend(event_findings)
    results["handled_events"] = sorted(handled_events)

    # Tally summary
    for finding in results["findings"]:
        sev = finding.get("severity", "info")
        if sev in results["summary"]:
            results["summary"][sev] += 1

    # Determine overall status
    if results["summary"]["critical"] > 0:
        results["status"] = "FAIL"
    elif strict and results["summary"]["warning"] > 0:
        results["status"] = "FAIL"
    else:
        results["status"] = "PASS"

    return results


def format_human(results):
    """Format results for human-readable terminal output."""
    lines = []
    lines.append("=" * 60)
    lines.append("  Stripe Webhook Validator")
    lines.append("=" * 60)
    lines.append(f"\nProject: {results['project']}")
    lines.append(f"Webhook files found: {len(results['webhook_files'])}")
    for wf in results["webhook_files"]:
        lines.append(f"  - {wf}")

    if results.get("handled_events"):
        lines.append(f"\nHandled events ({len(results['handled_events'])}):")
        for ev in results["handled_events"]:
            lines.append(f"  - {ev}")

    lines.append(f"\n{'─' * 60}")
    lines.append("FINDINGS:")
    lines.append(f"{'─' * 60}")

    severity_icons = {"critical": "[CRITICAL]", "warning": "[WARNING]", "info": "[INFO]", "pass": "[PASS]"}

    for finding in results["findings"]:
        sev = finding.get("severity", "info")
        icon = severity_icons.get(sev, "[?]")
        lines.append(f"\n  {icon} {finding['rule']}: {finding['message']}")
        if "fix" in finding:
            lines.append(f"    Fix: {finding['fix']}")

    lines.append(f"\n{'─' * 60}")
    s = results["summary"]
    lines.append(f"Summary: {s['critical']} critical, {s['warning']} warnings, {s['info']} info, {s['pass']} passed")
    lines.append(f"Status: {results['status']}")
    lines.append("=" * 60)

    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Validate Stripe webhook endpoint configurations and signature verification setup.",
        epilog="Example: %(prog)s /path/to/project --strict --json",
    )
    parser.add_argument("project_dir", help="Path to the project directory to scan")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output results as JSON")
    parser.add_argument("--strict", action="store_true", help="Treat warnings as failures (non-zero exit code)")

    args = parser.parse_args()

    project_dir = Path(args.project_dir).resolve()
    if not project_dir.is_dir():
        print(f"Error: '{project_dir}' is not a valid directory.", file=sys.stderr)
        sys.exit(2)

    results = run_validation(project_dir, strict=args.strict)

    if args.json_output:
        print(json.dumps(results, indent=2))
    else:
        print(format_human(results))

    sys.exit(0 if results["status"] == "PASS" else 1)


if __name__ == "__main__":
    main()