@bantay/cli 0.1.0

package/src/export/invariants.ts

@@ -0,0 +1,92 @@
+/**
+ * Export invariants.md from the aide tree
+ */
+
+import { readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { read as readAide } from "../aide";
+import { extractInvariants, groupBy } from "./aide-reader";
+import type { ExportOptions, ExportResult, ExtractedInvariant } from "./types";
+
+/**
+ * Generate invariants.md content from the aide tree
+ */
+export function generateInvariantsMd(invariants: ExtractedInvariant[]): string {
+  const lines: string[] = [];
+
+  lines.push("# Invariants");
+  lines.push("");
+  lines.push("Rules this project must never break. Generated from bantay.aide.");
+  lines.push("");
+
+  // Group by category
+  const byCategory = groupBy(invariants, (inv) => inv.category);
+
+  // Sort categories for consistent output
+  const sortedCategories = Array.from(byCategory.keys()).sort();
+
+  for (const category of sortedCategories) {
+    const categoryInvariants = byCategory.get(category) || [];
+
+    lines.push(`## ${formatCategoryTitle(category)}`);
+    lines.push("");
+
+    for (const inv of categoryInvariants) {
+      // Format: - [ ] ID: statement
+      const checkbox = inv.done ? "[x]" : "[ ]";
+      lines.push(`- ${checkbox} **${inv.id}**: ${inv.statement}`);
+
+      // Add threat signal as sub-item if present
+      if (inv.threatSignal) {
+        lines.push(`  - Threat: ${inv.threatSignal}`);
+      }
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format a category ID into a readable title
+ * e.g., "correctness" -> "Correctness"
+ */
+function formatCategoryTitle(category: string): string {
+  return category
+    .split("_")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+/**
+ * Export invariants.md from the aide file
+ */
+export async function exportInvariants(
+  projectPath: string,
+  options: ExportOptions = {}
+): Promise<ExportResult> {
+  const aidePath = options.aidePath || join(projectPath, "bantay.aide");
+  const outputPath = options.outputPath || join(projectPath, "invariants.md");
+
+  // Read the aide tree
+  const tree = await readAide(aidePath);
+
+  // Extract invariants
+  const invariants = extractInvariants(tree);
+
+  // Generate content
+  const content = generateInvariantsMd(invariants);
+
+  // Write unless dry run
+  if (!options.dryRun) {
+    await writeFile(outputPath, content, "utf-8");
+  }
+
+  return {
+    target: "invariants",
+    outputPath,
+    content,
+    bytesWritten: Buffer.byteLength(content, "utf-8"),
+  };
+}

package/src/export/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Export types for bantay export command
+ */
+
+/**
+ * An invariant extracted from the aide tree
+ */
+export interface ExtractedInvariant {
+  id: string;
+  statement: string;
+  category: string;
+  threatSignal?: string;
+  done?: boolean;
+}
+
+/**
+ * A constraint extracted from the aide tree
+ */
+export interface ExtractedConstraint {
+  id: string;
+  text: string;
+  domain: string;
+  rationale?: string;
+}
+
+/**
+ * A foundation extracted from the aide tree
+ */
+export interface ExtractedFoundation {
+  id: string;
+  text: string;
+}
+
+/**
+ * A wisdom entry extracted from the aide tree
+ */
+export interface ExtractedWisdom {
+  id: string;
+  text: string;
+}
+
+/**
+ * Export target types
+ */
+export type ExportTarget = "invariants" | "claude" | "cursor" | "codex";
+
+/**
+ * Options for export commands
+ */
+export interface ExportOptions {
+  aidePath?: string;
+  outputPath?: string;
+  dryRun?: boolean;
+}
+
+/**
+ * Result of an export operation
+ */
+export interface ExportResult {
+  target: ExportTarget;
+  outputPath: string;
+  content: string;
+  bytesWritten: number;
+}
+
+/**
+ * Section markers for agent context files
+ */
+export const SECTION_START = "<!-- bantay:start -->";
+export const SECTION_END = "<!-- bantay:end -->";

package/src/generators/config.ts

@@ -0,0 +1,170 @@
+import type { StackDetectionResult } from "../detectors";
+
+export interface BantayConfig {
+  source: {
+    include: string[];
+    exclude?: string[];
+  };
+  schema?: {
+    prisma?: string;
+  };
+  routes?: {
+    include: string[];
+  };
+}
+
+export async function generateConfig(
+  stack: StackDetectionResult,
+  _projectPath: string
+): Promise<BantayConfig> {
+  const config: BantayConfig = {
+    source: {
+      include: ["src/**/*"],
+      exclude: ["node_modules/**", "dist/**", ".next/**", "build/**"],
+    },
+  };
+
+  // Add app directory for Next.js app router
+  if (stack.framework?.name === "nextjs") {
+    if (stack.framework.router === "app") {
+      config.source.include.push("app/**/*");
+      config.routes = {
+        include: ["app/**/route.ts", "app/**/route.js"],
+      };
+    } else if (stack.framework.router === "pages") {
+      config.source.include.push("pages/**/*");
+      config.routes = {
+        include: ["pages/api/**/*.ts", "pages/api/**/*.js"],
+      };
+    }
+  }
+
+  // Add Prisma schema path
+  if (stack.orm?.name === "prisma" && stack.orm.schemaPath) {
+    config.schema = {
+      prisma: stack.orm.schemaPath,
+    };
+  }
+
+  return config;
+}
+
+export function configToYaml(config: BantayConfig): string {
+  const lines: string[] = [
+    "# Bantay configuration",
+    "# Edit this file to customize invariant checking",
+    "",
+  ];
+
+  // Source section
+  lines.push("source:");
+  lines.push("  include:");
+  for (const pattern of config.source.include) {
+    lines.push(`    - ${pattern}`);
+  }
+
+  if (config.source.exclude && config.source.exclude.length > 0) {
+    lines.push("  exclude:");
+    for (const pattern of config.source.exclude) {
+      lines.push(`    - ${pattern}`);
+    }
+  }
+
+  // Schema section
+  if (config.schema) {
+    lines.push("");
+    lines.push("schema:");
+    if (config.schema.prisma) {
+      lines.push(`  prisma: ${config.schema.prisma}`);
+    }
+  }
+
+  // Routes section
+  if (config.routes) {
+    lines.push("");
+    lines.push("routes:");
+    lines.push("  include:");
+    for (const pattern of config.routes.include) {
+      lines.push(`    - ${pattern}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export function parseConfig(yaml: string): BantayConfig {
+  const config: BantayConfig = {
+    source: {
+      include: [],
+    },
+  };
+
+  const lines = yaml.split("\n");
+  let currentSection: string | null = null;
+  let currentSubsection: string | null = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip comments and empty lines
+    if (trimmed.startsWith("#") || trimmed === "") {
+      continue;
+    }
+
+    // Check for top-level sections
+    if (!line.startsWith(" ") && !line.startsWith("\t")) {
+      if (trimmed.startsWith("source:")) {
+        currentSection = "source";
+        currentSubsection = null;
+      } else if (trimmed.startsWith("schema:")) {
+        currentSection = "schema";
+        currentSubsection = null;
+      } else if (trimmed.startsWith("routes:")) {
+        currentSection = "routes";
+        currentSubsection = null;
+      }
+      continue;
+    }
+
+    // Check for subsections
+    if (trimmed.startsWith("include:")) {
+      currentSubsection = "include";
+      continue;
+    } else if (trimmed.startsWith("exclude:")) {
+      currentSubsection = "exclude";
+      continue;
+    }
+
+    // Handle list items
+    if (trimmed.startsWith("- ")) {
+      const value = trimmed.slice(2);
+
+      if (currentSection === "source" && currentSubsection === "include") {
+        config.source.include.push(value);
+      } else if (currentSection === "source" && currentSubsection === "exclude") {
+        config.source.exclude = config.source.exclude ?? [];
+        config.source.exclude.push(value);
+      } else if (currentSection === "routes" && currentSubsection === "include") {
+        config.routes = config.routes ?? { include: [] };
+        config.routes.include.push(value);
+      }
+      continue;
+    }
+
+    // Handle key-value pairs
+    if (trimmed.includes(":")) {
+      const [key, ...rest] = trimmed.split(":");
+      const value = rest.join(":").trim();
+
+      if (currentSection === "schema") {
+        if (key.trim() === "prisma") {
+          config.schema = config.schema ?? {};
+          config.schema.prisma = value;
+        }
+      }
+    }
+  }
+
+  return config;
+}

package/src/generators/invariants.ts

@@ -0,0 +1,161 @@
+import type { StackDetectionResult } from "../detectors";
+
+export interface Invariant {
+  id: string;
+  category: string;
+  statement: string;
+}
+
+interface InvariantTemplate {
+  id: string;
+  category: string;
+  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)",
+  },
+];
+
+function collectInvariants(stack: StackDetectionResult): InvariantTemplate[] {
+  const invariants: InvariantTemplate[] = [...universalInvariants];
+
+  if (stack.framework?.name === "nextjs") {
+    invariants.push(...nextjsInvariants);
+  }
+
+  if (stack.orm?.name === "prisma") {
+    invariants.push(...prismaInvariants);
+  }
+
+  return invariants;
+}
+
+function groupByCategory(invariants: InvariantTemplate[]): Map<string, InvariantTemplate[]> {
+  const grouped = new Map<string, InvariantTemplate[]>();
+
+  for (const inv of invariants) {
+    const existing = grouped.get(inv.category) ?? [];
+    existing.push(inv);
+    grouped.set(inv.category, existing);
+  }
+
+  return grouped;
+}
+
+function formatCategoryName(category: string): string {
+  return category.charAt(0).toUpperCase() + category.slice(1);
+}
+
+export async function generateInvariants(stack: StackDetectionResult): Promise<string> {
+  const invariants = collectInvariants(stack);
+  const grouped = groupByCategory(invariants);
+
+  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.",
+    "",
+  ];
+
+  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("");
+  }
+
+  return lines.join("\n");
+}
+
+export function parseInvariants(markdown: string): Invariant[] {
+  const invariants: Invariant[] = [];
+
+  // Pattern 1: Old format - [INV-XXX] category | statement
+  const oldRegex = /^-\s*\[([A-Z]+-\d{3})\]\s*(\w+)\s*\|\s*(.+)$/gm;
+
+  // Pattern 2: Aide-generated format - [ ] **inv_id**: statement
+  // Category is determined by the preceding ## Header
+  const lines = markdown.split("\n");
+  let currentCategory = "uncategorized";
+
+  for (const line of lines) {
+    // Check for category header (## Category Name)
+    const headerMatch = line.match(/^##\s+(.+)$/);
+    if (headerMatch) {
+      // Convert "Auditability" to "auditability"
+      currentCategory = headerMatch[1].trim().toLowerCase().replace(/\s+/g, "_");
+      continue;
+    }
+
+    // Check for old format
+    const oldMatch = line.match(/^-\s*\[([A-Z]+-\d{3})\]\s*(\w+)\s*\|\s*(.+)$/);
+    if (oldMatch) {
+      invariants.push({
+        id: oldMatch[1],
+        category: oldMatch[2],
+        statement: oldMatch[3].trim(),
+      });
+      continue;
+    }
+
+    // Check for aide-generated format: - [ ] **inv_id**: statement or - [x] **inv_id**: statement
+    const aideMatch = line.match(/^-\s*\[[x ]\]\s*\*\*([^*]+)\*\*:\s*(.+)$/);
+    if (aideMatch) {
+      invariants.push({
+        id: aideMatch[1],
+        category: currentCategory,
+        statement: aideMatch[2].trim(),
+      });
+    }
+  }
+
+  return invariants;
+}

package/src/prerequisites.ts

@@ -0,0 +1,33 @@
+export interface PrerequisiteResult {
+  available: boolean;
+  version?: string;
+  error?: string;
+}
+
+export async function checkBunRuntime(): Promise<PrerequisiteResult> {
+  // Check if we're running in Bun by checking for Bun global
+  if (typeof Bun !== "undefined" && Bun.version) {
+    return {
+      available: true,
+      version: Bun.version,
+    };
+  }
+
+  return {
+    available: false,
+    error: "Bun runtime not found. Install from https://bun.sh",
+  };
+}
+
+export async function checkAllPrerequisites(): Promise<{
+  passed: boolean;
+  results: { name: string; result: PrerequisiteResult }[];
+}> {
+  const bunResult = await checkBunRuntime();
+
+  const results = [{ name: "Bun Runtime", result: bunResult }];
+
+  const passed = results.every((r) => r.result.available);
+
+  return { passed, results };
+}