@bantay/cli 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bantay/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Write down the rules your system must never break. We enforce them on every PR.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -133,6 +133,12 @@ async function handleInit(args: string[]) {
       console.log("  Auth: Not detected");
     }
 
+    if (result.detection.payments) {
+      console.log(`  Payments: ${result.detection.payments.name} (${result.detection.payments.confidence} confidence)`);
+    } else {
+      console.log("  Payments: Not detected");
+    }
+
     console.log("");
 
     // Display warnings

package/src/detectors/authjs.ts

@@ -0,0 +1,92 @@
+import { readFile, access } from "fs/promises";
+import { join } from "path";
+import type { AuthDetection } from "./types";
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readPackageJson(projectPath: string): Promise<Record<string, unknown> | null> {
+  try {
+    const content = await readFile(join(projectPath, "package.json"), "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export async function detect(projectPath: string): Promise<AuthDetection | null> {
+  const pkg = await readPackageJson(projectPath);
+
+  let version: string | undefined;
+  let confidence: "high" | "medium" | "low" = "low";
+  let detected = false;
+  let authFunction: string | undefined;
+  let sessionFunction: string | undefined;
+
+  if (pkg) {
+    const deps = (pkg.dependencies ?? {}) as Record<string, string>;
+    const devDeps = (pkg.devDependencies ?? {}) as Record<string, string>;
+
+    // Check for next-auth (Auth.js v4)
+    if (deps["next-auth"]) {
+      version = deps["next-auth"];
+      confidence = "high";
+      detected = true;
+      authFunction = "getServerSession";
+      sessionFunction = "getServerSession(authOptions)";
+    }
+
+    // Check for @auth/nextjs (Auth.js v5)
+    if (deps["@auth/nextjs-auth"]) {
+      version = deps["@auth/nextjs-auth"];
+      confidence = "high";
+      detected = true;
+      authFunction = "auth";
+      sessionFunction = "auth()";
+    }
+
+    // Check for auth.js v5 with new package name
+    if (deps["next-auth"] && version?.startsWith("5")) {
+      authFunction = "auth";
+      sessionFunction = "auth()";
+    }
+  }
+
+  // Check for auth config files
+  const configFiles = [
+    "auth.ts",
+    "auth.config.ts",
+    "lib/auth.ts",
+    "src/auth.ts",
+    "src/lib/auth.ts",
+    "app/api/auth/[...nextauth]/route.ts",
+  ];
+
+  for (const configFile of configFiles) {
+    if (await fileExists(join(projectPath, configFile))) {
+      detected = true;
+      if (confidence === "low") {
+        confidence = "medium";
+      }
+      break;
+    }
+  }
+
+  if (!detected) {
+    return null;
+  }
+
+  return {
+    name: "authjs",
+    version,
+    confidence,
+    authFunction,
+    sessionFunction,
+  };
+}

package/src/detectors/clerk.ts

@@ -0,0 +1,88 @@
+import { readFile, access } from "fs/promises";
+import { join } from "path";
+import type { AuthDetection } from "./types";
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readPackageJson(projectPath: string): Promise<Record<string, unknown> | null> {
+  try {
+    const content = await readFile(join(projectPath, "package.json"), "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export async function detect(projectPath: string): Promise<AuthDetection | null> {
+  const pkg = await readPackageJson(projectPath);
+
+  let version: string | undefined;
+  let confidence: "high" | "medium" | "low" = "low";
+  let detected = false;
+
+  if (pkg) {
+    const deps = (pkg.dependencies ?? {}) as Record<string, string>;
+    const devDeps = (pkg.devDependencies ?? {}) as Record<string, string>;
+
+    // Check for @clerk/nextjs
+    if (deps["@clerk/nextjs"]) {
+      version = deps["@clerk/nextjs"];
+      confidence = "high";
+      detected = true;
+    } else if (devDeps["@clerk/nextjs"]) {
+      version = devDeps["@clerk/nextjs"];
+      confidence = "medium";
+      detected = true;
+    }
+
+    // Check for @clerk/clerk-sdk-node
+    if (deps["@clerk/clerk-sdk-node"] || devDeps["@clerk/clerk-sdk-node"]) {
+      detected = true;
+      if (confidence === "low") {
+        confidence = "high";
+      }
+    }
+  }
+
+  // Check for Clerk middleware
+  const middlewareFiles = [
+    "middleware.ts",
+    "middleware.js",
+    "src/middleware.ts",
+    "src/middleware.js",
+  ];
+
+  for (const middlewareFile of middlewareFiles) {
+    if (await fileExists(join(projectPath, middlewareFile))) {
+      try {
+        const content = await readFile(join(projectPath, middlewareFile), "utf-8");
+        if (content.includes("@clerk") || content.includes("clerkMiddleware") || content.includes("authMiddleware")) {
+          detected = true;
+          confidence = "high";
+          break;
+        }
+      } catch {
+        // Ignore read errors
+      }
+    }
+  }
+
+  if (!detected) {
+    return null;
+  }
+
+  return {
+    name: "clerk",
+    version,
+    confidence,
+    authFunction: "auth",
+    sessionFunction: "auth()",
+  };
+}

package/src/detectors/drizzle.ts

@@ -0,0 +1,105 @@
+import { readFile, access } from "fs/promises";
+import { join } from "path";
+import type { OrmDetection } from "./types";
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readPackageJson(projectPath: string): Promise<Record<string, unknown> | null> {
+  try {
+    const content = await readFile(join(projectPath, "package.json"), "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+async function findSchemaPath(projectPath: string): Promise<string | undefined> {
+  // Check common Drizzle schema locations
+  const paths = [
+    "drizzle/schema.ts",
+    "src/db/schema.ts",
+    "src/drizzle/schema.ts",
+    "lib/db/schema.ts",
+    "lib/drizzle/schema.ts",
+    "db/schema.ts",
+    "schema.ts",
+    "src/schema.ts",
+  ];
+
+  for (const path of paths) {
+    if (await fileExists(join(projectPath, path))) {
+      return path;
+    }
+  }
+
+  return undefined;
+}
+
+export async function detect(projectPath: string): Promise<OrmDetection | null> {
+  const pkg = await readPackageJson(projectPath);
+
+  let version: string | undefined;
+  let confidence: "high" | "medium" | "low" = "low";
+  let detected = false;
+
+  if (pkg) {
+    const deps = (pkg.dependencies ?? {}) as Record<string, string>;
+    const devDeps = (pkg.devDependencies ?? {}) as Record<string, string>;
+
+    // Check for drizzle-orm
+    if (deps["drizzle-orm"]) {
+      version = deps["drizzle-orm"];
+      confidence = "high";
+      detected = true;
+    } else if (devDeps["drizzle-orm"]) {
+      version = devDeps["drizzle-orm"];
+      confidence = "medium";
+      detected = true;
+    }
+
+    // Check for drizzle-kit (CLI tool)
+    if (deps["drizzle-kit"] || devDeps["drizzle-kit"]) {
+      detected = true;
+      if (confidence === "low") {
+        confidence = "high";
+      }
+    }
+  }
+
+  // Check for drizzle.config.ts
+  const configFiles = [
+    "drizzle.config.ts",
+    "drizzle.config.js",
+    "drizzle.config.json",
+  ];
+
+  for (const configFile of configFiles) {
+    if (await fileExists(join(projectPath, configFile))) {
+      detected = true;
+      if (confidence === "low") {
+        confidence = "high";
+      }
+      break;
+    }
+  }
+
+  if (!detected) {
+    return null;
+  }
+
+  const schemaPath = await findSchemaPath(projectPath);
+
+  return {
+    name: "drizzle",
+    version,
+    confidence,
+    schemaPath,
+  };
+}

package/src/detectors/index.ts

@@ -2,34 +2,48 @@ export type {
   FrameworkDetection,
   OrmDetection,
   AuthDetection,
+  PaymentsDetection,
   StackDetectionResult,
 } from "./types";
 
-import type { StackDetectionResult, FrameworkDetection, OrmDetection, AuthDetection } from "./types";
+import type { StackDetectionResult, FrameworkDetection, OrmDetection, AuthDetection, PaymentsDetection } from "./types";
 import { detect as detectNextjs } from "./nextjs";
 import { detect as detectPrisma } from "./prisma";
+import { detect as detectDrizzle } from "./drizzle";
+import { detect as detectAuthjs } from "./authjs";
+import { detect as detectClerk } from "./clerk";
+import { detect as detectStripe } from "./stripe";
 
 // Registry of framework detectors
-const frameworkDetectors: Array<() => typeof detectNextjs> = [
-  () => detectNextjs,
+const frameworkDetectors: Array<(projectPath: string) => Promise<FrameworkDetection | null>> = [
+  detectNextjs,
 ];
 
 // Registry of ORM detectors
-const ormDetectors: Array<() => typeof detectPrisma> = [
-  () => detectPrisma,
+const ormDetectors: Array<(projectPath: string) => Promise<OrmDetection | null>> = [
+  detectPrisma,
+  detectDrizzle,
 ];
 
-// Registry of auth detectors (none yet)
-const authDetectors: Array<() => (projectPath: string) => Promise<AuthDetection | null>> = [];
+// Registry of auth detectors
+const authDetectors: Array<(projectPath: string) => Promise<AuthDetection | null>> = [
+  detectClerk,  // Check Clerk first (more specific)
+  detectAuthjs,
+];
+
+// Registry of payments detectors
+const paymentsDetectors: Array<(projectPath: string) => Promise<PaymentsDetection | null>> = [
+  detectStripe,
+];
 
 export async function detectStack(projectPath: string): Promise<StackDetectionResult> {
   let framework: FrameworkDetection | null = null;
   let orm: OrmDetection | null = null;
   let auth: AuthDetection | null = null;
+  let payments: PaymentsDetection | null = null;
 
   // Run framework detectors
-  for (const getDetector of frameworkDetectors) {
-    const detector = getDetector();
+  for (const detector of frameworkDetectors) {
     const result = await detector(projectPath);
     if (result && (!framework || result.confidence === "high")) {
       framework = result;
@@ -38,8 +52,7 @@ export async function detectStack(projectPath: string): Promise<StackDetectionRe
   }
 
   // Run ORM detectors
-  for (const getDetector of ormDetectors) {
-    const detector = getDetector();
+  for (const detector of ormDetectors) {
     const result = await detector(projectPath);
     if (result && (!orm || result.confidence === "high")) {
       orm = result;
@@ -48,8 +61,7 @@ export async function detectStack(projectPath: string): Promise<StackDetectionRe
   }
 
   // Run auth detectors
-  for (const getDetector of authDetectors) {
-    const detector = getDetector();
+  for (const detector of authDetectors) {
     const result = await detector(projectPath);
     if (result && (!auth || result.confidence === "high")) {
       auth = result;
@@ -57,5 +69,14 @@ export async function detectStack(projectPath: string): Promise<StackDetectionRe
     }
   }
 
-  return { framework, orm, auth };
+  // Run payments detectors
+  for (const detector of paymentsDetectors) {
+    const result = await detector(projectPath);
+    if (result && (!payments || result.confidence === "high")) {
+      payments = result;
+      if (result.confidence === "high") break;
+    }
+  }
+
+  return { framework, orm, auth, payments };
 }

package/src/detectors/nextjs.ts

@@ -74,18 +74,27 @@ export async function detect(projectPath: string): Promise<FrameworkDetection |
     return null;
   }
 
-  // Detect router type
+  // Detect router type and determine route pattern
   let router: "app" | "pages" | undefined;
+  let routePattern: string | undefined;
 
   const hasAppDir = await dirExists(join(projectPath, "app"));
   const hasPagesDir = await dirExists(join(projectPath, "pages"));
   const hasSrcAppDir = await dirExists(join(projectPath, "src", "app"));
   const hasSrcPagesDir = await dirExists(join(projectPath, "src", "pages"));
 
-  if (hasAppDir || hasSrcAppDir) {
+  if (hasAppDir) {
     router = "app";
-  } else if (hasPagesDir || hasSrcPagesDir) {
+    routePattern = "app/api/**/route.ts";
+  } else if (hasSrcAppDir) {
+    router = "app";
+    routePattern = "src/app/api/**/route.ts";
+  } else if (hasPagesDir) {
+    router = "pages";
+    routePattern = "pages/api/**/*.ts";
+  } else if (hasSrcPagesDir) {
     router = "pages";
+    routePattern = "src/pages/api/**/*.ts";
   }
 
   return {
@@ -93,5 +102,6 @@ export async function detect(projectPath: string): Promise<FrameworkDetection |
     version,
     confidence,
     router,
+    routePattern,
   };
 }

package/src/detectors/stripe.ts

@@ -0,0 +1,88 @@
+import { readFile, access, readdir } from "fs/promises";
+import { join } from "path";
+import type { PaymentsDetection } from "./types";
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readPackageJson(projectPath: string): Promise<Record<string, unknown> | null> {
+  try {
+    const content = await readFile(join(projectPath, "package.json"), "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+async function findWebhookPattern(projectPath: string): Promise<string | undefined> {
+  // Check common webhook locations
+  const patterns = [
+    { path: "app/api/webhooks/stripe/route.ts", pattern: "app/api/webhooks/stripe/route.ts" },
+    { path: "app/api/webhook/stripe/route.ts", pattern: "app/api/webhook/stripe/route.ts" },
+    { path: "app/api/stripe/webhook/route.ts", pattern: "app/api/stripe/webhook/route.ts" },
+    { path: "app/webhooks/stripe/route.ts", pattern: "app/webhooks/stripe/route.ts" },
+    { path: "src/app/api/webhooks/stripe/route.ts", pattern: "src/app/api/webhooks/stripe/route.ts" },
+    { path: "pages/api/webhooks/stripe.ts", pattern: "pages/api/webhooks/stripe.ts" },
+    { path: "pages/api/webhook/stripe.ts", pattern: "pages/api/webhook/stripe.ts" },
+  ];
+
+  for (const { path, pattern } of patterns) {
+    if (await fileExists(join(projectPath, path))) {
+      return pattern;
+    }
+  }
+
+  return undefined;
+}
+
+export async function detect(projectPath: string): Promise<PaymentsDetection | null> {
+  const pkg = await readPackageJson(projectPath);
+
+  let version: string | undefined;
+  let confidence: "high" | "medium" | "low" = "low";
+  let detected = false;
+
+  // Check package.json for stripe dependency
+  if (pkg) {
+    const deps = (pkg.dependencies ?? {}) as Record<string, string>;
+    const devDeps = (pkg.devDependencies ?? {}) as Record<string, string>;
+
+    if (deps.stripe) {
+      version = deps.stripe;
+      confidence = "high";
+      detected = true;
+    } else if (devDeps.stripe) {
+      version = devDeps.stripe;
+      confidence = "medium";
+      detected = true;
+    }
+
+    // Also check for @stripe/stripe-js (client-side)
+    if (deps["@stripe/stripe-js"] || devDeps["@stripe/stripe-js"]) {
+      detected = true;
+      if (confidence === "low") {
+        confidence = "medium";
+      }
+    }
+  }
+
+  if (!detected) {
+    return null;
+  }
+
+  const webhookPattern = await findWebhookPattern(projectPath);
+
+  return {
+    name: "stripe",
+    version,
+    confidence,
+    webhookPattern,
+    secretEnvVar: "STRIPE_SECRET_KEY",
+  };
+}

package/src/detectors/types.ts

@@ -3,6 +3,7 @@ export interface FrameworkDetection {
   version?: string;
   confidence: "high" | "medium" | "low";
   router?: "app" | "pages";
+  routePattern?: string; // e.g., "app/api/**/route.ts" or "pages/api/**/*.ts"
 }
 
 export interface OrmDetection {
@@ -16,12 +17,23 @@ export interface AuthDetection {
   name: string;
   version?: string;
   confidence: "high" | "medium" | "low";
+  authFunction?: string; // e.g., "auth()" for Auth.js, "getAuth()" for Clerk
+  sessionFunction?: string; // e.g., "getServerSession()" or "currentUser()"
+}
+
+export interface PaymentsDetection {
+  name: string;
+  version?: string;
+  confidence: "high" | "medium" | "low";
+  webhookPattern?: string; // e.g., "app/api/webhooks/stripe/route.ts"
+  secretEnvVar?: string; // e.g., "STRIPE_SECRET_KEY"
 }
 
 export interface StackDetectionResult {
   framework: FrameworkDetection | null;
   orm: OrmDetection | null;
   auth: AuthDetection | null;
+  payments: PaymentsDetection | null;
 }
 
 export interface Detector<T> {

package/src/generators/invariants.ts

@@ -12,62 +12,159 @@ interface InvariantTemplate {
   statement: string;
 }
 
-// Universal invariants that apply to all projects
-const universalInvariants: InvariantTemplate[] = [
-  {
-    id: "INV-001",
-    category: "security",
-    statement: "No secrets or credentials committed to version control",
-  },
-  {
-    id: "INV-002",
-    category: "security",
-    statement: "All user input must be validated before processing",
-  },
-];
-
-// Next.js specific invariants
-const nextjsInvariants: InvariantTemplate[] = [
-  {
-    id: "INV-010",
-    category: "auth",
-    statement: "All API routes must check authentication before processing requests (auth-on-routes)",
-  },
-  {
-    id: "INV-011",
-    category: "auth",
-    statement: "Protected pages must redirect unauthenticated users",
-  },
-];
-
-// Prisma specific invariants
-const prismaInvariants: InvariantTemplate[] = [
-  {
-    id: "INV-020",
-    category: "schema",
-    statement: "All database tables must have createdAt and updatedAt timestamps (timestamps-on-tables)",
-  },
-  {
-    id: "INV-021",
-    category: "schema",
-    statement: "All database tables must use soft-delete pattern with deletedAt column (soft-delete)",
-  },
-  {
-    id: "INV-022",
-    category: "schema",
-    statement: "No raw SQL queries - use Prisma client methods only (no-raw-sql)",
-  },
-];
-
+/**
+ * Generate stack-specific invariants based on detected components.
+ * These are project-specific, checkable rules — not generic security posters.
+ */
 function collectInvariants(stack: StackDetectionResult): InvariantTemplate[] {
-  const invariants: InvariantTemplate[] = [...universalInvariants];
+  const invariants: InvariantTemplate[] = [];
 
-  if (stack.framework?.name === "nextjs") {
-    invariants.push(...nextjsInvariants);
+  // Next.js App Router invariants
+  if (stack.framework?.name === "nextjs" && stack.framework.router === "app") {
+    const routePattern = stack.framework.routePattern || "app/api/**/route.ts";
+
+    // Auth invariants depend on detected auth library
+    if (stack.auth?.name === "clerk") {
+      invariants.push({
+        id: "inv_route_auth",
+        category: "auth",
+        statement: `Every ${routePattern} calls auth() from @clerk/nextjs before processing the request`,
+      });
+      invariants.push({
+        id: "inv_server_action_auth",
+        category: "auth",
+        statement: `Every server action ("use server") calls auth() and checks userId before mutating data`,
+      });
+    } else if (stack.auth?.name === "authjs") {
+      const authFn = stack.auth.sessionFunction || "auth()";
+      invariants.push({
+        id: "inv_route_auth",
+        category: "auth",
+        statement: `Every ${routePattern} calls ${authFn} and checks session before processing the request`,
+      });
+      invariants.push({
+        id: "inv_server_action_auth",
+        category: "auth",
+        statement: `Every server action ("use server") calls ${authFn} and checks session.user before mutating data`,
+      });
+    } else {
+      // No auth detected, use generic but still specific pattern
+      invariants.push({
+        id: "inv_route_auth",
+        category: "auth",
+        statement: `Every ${routePattern} verifies authentication before processing the request`,
+      });
+    }
+
+    // Middleware invariant if auth detected
+    if (stack.auth) {
+      invariants.push({
+        id: "inv_middleware_matcher",
+        category: "auth",
+        statement: `middleware.ts config.matcher includes all protected routes — unmatched routes bypass auth`,
+      });
+    }
   }
 
+  // Next.js Pages Router invariants
+  if (stack.framework?.name === "nextjs" && stack.framework.router === "pages") {
+    const routePattern = stack.framework.routePattern || "pages/api/**/*.ts";
+
+    if (stack.auth?.name === "authjs") {
+      invariants.push({
+        id: "inv_route_auth",
+        category: "auth",
+        statement: `Every ${routePattern} calls getServerSession(req, res, authOptions) before processing`,
+      });
+    } else {
+      invariants.push({
+        id: "inv_route_auth",
+        category: "auth",
+        statement: `Every ${routePattern} verifies authentication before processing the request`,
+      });
+    }
+  }
+
+  // Prisma invariants
   if (stack.orm?.name === "prisma") {
-    invariants.push(...prismaInvariants);
+    const schemaPath = stack.orm.schemaPath || "prisma/schema.prisma";
+    invariants.push({
+      id: "inv_model_timestamps",
+      category: "schema",
+      statement: `Every model in ${schemaPath} has createdAt DateTime @default(now()) and updatedAt DateTime @updatedAt`,
+    });
+    invariants.push({
+      id: "inv_model_soft_delete",
+      category: "schema",
+      statement: `Every model in ${schemaPath} has deletedAt DateTime? for soft-delete support`,
+    });
+    invariants.push({
+      id: "inv_no_raw_sql",
+      category: "schema",
+      statement: `No $queryRaw or $executeRaw calls in source files — use Prisma client methods only`,
+    });
+  }
+
+  // Drizzle invariants
+  if (stack.orm?.name === "drizzle") {
+    const schemaPath = stack.orm.schemaPath || "src/db/schema.ts";
+    invariants.push({
+      id: "inv_table_timestamps",
+      category: "schema",
+      statement: `Every table in ${schemaPath} has createdAt: timestamp().defaultNow() and updatedAt: timestamp().defaultNow().$onUpdate(() => new Date())`,
+    });
+    invariants.push({
+      id: "inv_table_soft_delete",
+      category: "schema",
+      statement: `Every table in ${schemaPath} has deletedAt: timestamp() for soft-delete support`,
+    });
+  }
+
+  // Stripe invariants
+  if (stack.payments?.name === "stripe") {
+    const webhookPattern = stack.payments.webhookPattern || "app/api/webhooks/stripe/route.ts";
+    invariants.push({
+      id: "inv_stripe_webhook_verify",
+      category: "payments",
+      statement: `${webhookPattern} calls stripe.webhooks.constructEvent() with STRIPE_WEBHOOK_SECRET before processing any event`,
+    });
+    invariants.push({
+      id: "inv_stripe_secret_server",
+      category: "payments",
+      statement: `STRIPE_SECRET_KEY is only accessed in server-side code — never imported in files under app/**/page.tsx or components/`,
+    });
+    invariants.push({
+      id: "inv_stripe_idempotency",
+      category: "payments",
+      statement: `Every stripe.charges.create() and stripe.subscriptions.create() call includes idempotencyKey parameter`,
+    });
+  }
+
+  // Logging invariants (if any ORM detected, likely has user data)
+  if (stack.orm) {
+    invariants.push({
+      id: "inv_no_pii_logs",
+      category: "logging",
+      statement: `No console.log, logger.info, or logger.error call includes email, password, ssn, creditCard, or token fields`,
+    });
+  }
+
+  // Environment invariants
+  if (stack.framework?.name === "nextjs") {
+    invariants.push({
+      id: "inv_env_no_commit",
+      category: "security",
+      statement: `.env and .env.local are in .gitignore — only .env.example with placeholder values is committed`,
+    });
+  }
+
+  // If no stack detected, provide minimal but still specific invariants
+  if (invariants.length === 0) {
+    invariants.push({
+      id: "inv_env_no_commit",
+      category: "security",
+      statement: `.env files are in .gitignore — secrets never committed to version control`,
+    });
   }
 
   return invariants;
@@ -96,17 +193,36 @@ export async function generateInvariants(stack: StackDetectionResult): Promise<s
   const lines: string[] = [
     "# Project Invariants",
     "",
-    "This file defines the invariants that must hold for this project.",
-    "Each invariant is checked by `bantay check` on every PR.",
+    "Rules that must hold for this codebase. Checked by `bantay check` on every PR.",
     "",
   ];
 
+  // Add detected stack summary
+  const stackParts: string[] = [];
+  if (stack.framework) {
+    stackParts.push(`${stack.framework.name}${stack.framework.router ? ` (${stack.framework.router} router)` : ""}`);
+  }
+  if (stack.orm) {
+    stackParts.push(stack.orm.name);
+  }
+  if (stack.auth) {
+    stackParts.push(stack.auth.name);
+  }
+  if (stack.payments) {
+    stackParts.push(stack.payments.name);
+  }
+
+  if (stackParts.length > 0) {
+    lines.push(`**Detected stack:** ${stackParts.join(" + ")}`);
+    lines.push("");
+  }
+
   for (const [category, invs] of grouped) {
     lines.push(`## ${formatCategoryName(category)}`);
     lines.push("");
 
     for (const inv of invs) {
-      lines.push(`- [${inv.id}] ${inv.category} | ${inv.statement}`);
+      lines.push(`- [ ] **${inv.id}**: ${inv.statement}`);
     }
 
     lines.push("");