@bantay/cli 0.2.0 → 0.3.0

package/src/commands/aide.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "fs";
-import { readFile, writeFile } from "fs/promises";
+import { readFile, writeFile, readdir } from "fs/promises";
+import { basename } from "path";
 import {
   read,
   write,
@@ -11,7 +12,37 @@ import {
 } from "../aide";
 import type { RelationshipType, Cardinality } from "../aide/types";
 
-const DEFAULT_AIDE_PATH = "bantay.aide";
+/**
+ * Entity type classification based on ID prefix
+ */
+const ENTITY_TYPE_PREFIXES: Record<string, string> = {
+  "cuj_": "cuj",
+  "sc_": "scenario",
+  "inv_": "invariant",
+  "con_": "constraint",
+  "found_": "foundation",
+  "wis_": "wisdom",
+};
+
+/**
+ * Get entity type from ID prefix
+ */
+function getEntityType(id: string): string {
+  for (const [prefix, type] of Object.entries(ENTITY_TYPE_PREFIXES)) {
+    if (id.startsWith(prefix)) {
+      return type;
+    }
+  }
+  return "entity";
+}
+
+/**
+ * Parsed lock file structure
+ */
+interface LockFile {
+  entities: Record<string, string>;
+  relationships: string[];
+}
 
 /**
  * Parse command-line arguments for the aide commands
@@ -36,10 +67,161 @@ function parseOptions(args: string[]): { options: AideCommandOptions; rest: stri
 }
 
 /**
- * Get the aide file path, defaulting to bantay.aide in cwd
+ * Discover .aide files in the current directory
+ * Returns: { found: string[], error?: string }
+ */
+async function discoverAideFiles(cwd: string): Promise<{ found: string[]; error?: string }> {
+  try {
+    const files = await readdir(cwd);
+    const aideFiles = files.filter((f) => f.endsWith(".aide"));
+    return { found: aideFiles };
+  } catch (error) {
+    return { found: [], error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * Get the aide file path with auto-discovery
+ * - If --aide flag is provided, use that
+ * - Otherwise, glob for *.aide in cwd
+ * - If exactly one found, use it
+ * - If multiple found, error
+ * - If none found, error
+ */
+async function getAidePath(options: AideCommandOptions): Promise<string> {
+  const cwd = process.cwd();
+
+  // If explicit path provided, use it (resolve relative to cwd)
+  if (options.aidePath) {
+    if (options.aidePath.startsWith("/")) {
+      return options.aidePath;
+    }
+    return `${cwd}/${options.aidePath}`;
+  }
+
+  // Auto-discover
+  const { found, error } = await discoverAideFiles(cwd);
+
+  if (error) {
+    console.error(`Error discovering aide files: ${error}`);
+    process.exit(1);
+  }
+
+  if (found.length === 0) {
+    console.error("No .aide file found. Run 'bantay aide init' to create one.");
+    process.exit(1);
+  }
+
+  if (found.length > 1) {
+    console.error("Multiple .aide files found. Specify one with --aide <path>");
+    console.error("Found:");
+    for (const f of found) {
+      console.error(`  - ${f}`);
+    }
+    process.exit(1);
+  }
+
+  return `${cwd}/${found[0]}`;
+}
+
+/**
+ * Generate skeleton aide file content
  */
-function getAidePath(options: AideCommandOptions): string {
-  return options.aidePath || `${process.cwd()}/${DEFAULT_AIDE_PATH}`;
+function generateAideSkeleton(projectName: string): string {
+  return `entities:
+  ${projectName}:
+    display: page
+    props:
+      title: ${projectName}
+      description: Project description
+      version: "0.1"
+  cujs:
+    display: table
+    parent: ${projectName}
+    props:
+      title: Critical User Journeys
+      _pattern: roster
+      _group_by: area
+      _sort_by: tier
+      _sort_order: asc
+  invariants:
+    display: checklist
+    parent: ${projectName}
+    props:
+      title: Invariants
+      _pattern: roster
+      _group_by: category
+  constraints:
+    display: list
+    parent: ${projectName}
+    props:
+      title: Architectural Constraints
+      _pattern: flat_list
+      _group_by: domain
+  foundations:
+    display: list
+    parent: ${projectName}
+    props:
+      title: Design Foundations
+      _pattern: flat_list
+  wisdom:
+    display: list
+    parent: ${projectName}
+    props:
+      title: Project Wisdom
+      _pattern: flat_list
+relationships: []
+`;
+}
+
+/**
+ * Handle bantay aide init
+ * Usage: bantay aide init [--name <name>]
+ * Creates a new .aide file with skeleton structure
+ */
+export async function handleAideInit(args: string[]): Promise<void> {
+  const cwd = process.cwd();
+  const dirName = basename(cwd);
+
+  // Parse --name option
+  let name: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--name" || args[i] === "-n") {
+      name = args[++i];
+    }
+  }
+
+  // Determine the aide filename
+  const aideName = name || dirName;
+  const aideFilename = `${aideName}.aide`;
+  const aidePath = `${cwd}/${aideFilename}`;
+
+  // Check if any .aide file already exists
+  const { found } = await discoverAideFiles(cwd);
+
+  if (found.length > 0) {
+    // Check if the specific file we want to create exists
+    if (found.includes(aideFilename)) {
+      console.error(`Error: ${aideFilename} already exists.`);
+      console.error("Use a different name with --name <name> or delete the existing file.");
+      process.exit(1);
+    }
+
+    // If we're trying to create a new aide file but others exist, warn
+    console.error(`Error: .aide file already exists: ${found[0]}`);
+    console.error("Use --name <name> to create a differently named file, or use the existing one.");
+    process.exit(1);
+  }
+
+  // Generate and write the skeleton
+  const content = generateAideSkeleton(aideName);
+  await writeFile(aidePath, content, "utf-8");
+
+  console.log(`Created ${aideFilename}`);
+  console.log(`\nNext steps:`);
+  console.log(`  1. Edit ${aideFilename} to add your project's CUJs, invariants, and constraints`);
+  console.log(`  2. Run 'bantay aide validate' to check the file`);
+  console.log(`  3. Run 'bantay export all' to generate invariants.md and agent context files`);
 }
 
 /**
@@ -48,13 +230,7 @@ function getAidePath(options: AideCommandOptions): string {
  */
 export async function handleAideAdd(args: string[]): Promise<void> {
   const { options, rest } = parseOptions(args);
-  const aidePath = getAidePath(options);
-
-  if (!existsSync(aidePath)) {
-    console.error(`Error: Aide file not found: ${aidePath}`);
-    console.error("Run 'bantay init' to create a project first.");
-    process.exit(1);
-  }
+  const aidePath = await getAidePath(options);
 
   // Parse add-specific options
   let id: string | undefined;
@@ -101,12 +277,7 @@ export async function handleAideAdd(args: string[]): Promise<void> {
  */
 export async function handleAideRemove(args: string[]): Promise<void> {
   const { options, rest } = parseOptions(args);
-  const aidePath = getAidePath(options);
-
-  if (!existsSync(aidePath)) {
-    console.error(`Error: Aide file not found: ${aidePath}`);
-    process.exit(1);
-  }
+  const aidePath = await getAidePath(options);
 
   const id = rest.find((arg) => !arg.startsWith("-"));
   const force = rest.includes("--force") || rest.includes("-f");
@@ -135,12 +306,7 @@ export async function handleAideRemove(args: string[]): Promise<void> {
  */
 export async function handleAideLink(args: string[]): Promise<void> {
   const { options, rest } = parseOptions(args);
-  const aidePath = getAidePath(options);
-
-  if (!existsSync(aidePath)) {
-    console.error(`Error: Aide file not found: ${aidePath}`);
-    process.exit(1);
-  }
+  const aidePath = await getAidePath(options);
 
   let from: string | undefined;
   let to: string | undefined;
@@ -192,12 +358,7 @@ export async function handleAideLink(args: string[]): Promise<void> {
  */
 export async function handleAideShow(args: string[]): Promise<void> {
   const { options, rest } = parseOptions(args);
-  const aidePath = getAidePath(options);
-
-  if (!existsSync(aidePath)) {
-    console.error(`Error: Aide file not found: ${aidePath}`);
-    process.exit(1);
-  }
+  const aidePath = await getAidePath(options);
 
   let entityId: string | undefined;
   let format = "tree";
@@ -245,12 +406,7 @@ export async function handleAideShow(args: string[]): Promise<void> {
  */
 export async function handleAideValidate(args: string[]): Promise<void> {
   const { options } = parseOptions(args);
-  const aidePath = getAidePath(options);
-
-  if (!existsSync(aidePath)) {
-    console.error(`Error: Aide file not found: ${aidePath}`);
-    process.exit(1);
-  }
+  const aidePath = await getAidePath(options);
 
   try {
     const tree = await read(aidePath);
@@ -282,14 +438,9 @@ export async function handleAideValidate(args: string[]): Promise<void> {
  */
 export async function handleAideLock(args: string[]): Promise<void> {
   const { options } = parseOptions(args);
-  const aidePath = getAidePath(options);
+  const aidePath = await getAidePath(options);
   const lockPath = `${aidePath}.lock`;
 
-  if (!existsSync(aidePath)) {
-    console.error(`Error: Aide file not found: ${aidePath}`);
-    process.exit(1);
-  }
-
   try {
     const tree = await read(aidePath);
     const errors = validate(tree);
@@ -321,12 +472,7 @@ export async function handleAideLock(args: string[]): Promise<void> {
  */
 export async function handleAideUpdate(args: string[]): Promise<void> {
   const { options, rest } = parseOptions(args);
-  const aidePath = getAidePath(options);
-
-  if (!existsSync(aidePath)) {
-    console.error(`Error: Aide file not found: ${aidePath}`);
-    process.exit(1);
-  }
+  const aidePath = await getAidePath(options);
 
   let id: string | undefined;
   const propsToSet: Record<string, unknown> = {};
@@ -512,6 +658,234 @@ function computeRelationshipHash(rel: { from: string; to: string; type: string;
   return Math.abs(hash).toString(16).padStart(8, "0");
 }
 
+/**
+ * Handle bantay aide diff
+ * Usage: bantay aide diff [--json]
+ * Compare bantay.aide against bantay.aide.lock and show changes
+ */
+export async function handleAideDiff(args: string[]): Promise<void> {
+  const { options } = parseOptions(args);
+  const aidePath = await getAidePath(options);
+  const lockPath = `${aidePath}.lock`;
+  const jsonOutput = args.includes("--json");
+
+  // Check that lock file exists
+  if (!existsSync(lockPath)) {
+    console.error(`Error: Lock file not found: ${lockPath}`);
+    console.error("Run 'bantay aide lock' to create a lock file first.");
+    process.exit(1);
+  }
+
+  try {
+    // Read and parse current aide file
+    const tree = await read(aidePath);
+
+    // Read and parse lock file
+    const lockContent = await readFile(lockPath, "utf-8");
+    const lock = parseLockFile(lockContent);
+
+    // Compute current hashes
+    const currentHashes: Record<string, string> = {};
+    for (const [id, entity] of Object.entries(tree.entities)) {
+      currentHashes[id] = computeEntityHash(id, entity);
+    }
+
+    // Compute current relationship keys
+    const currentRelationships = new Set<string>();
+    for (const rel of tree.relationships) {
+      currentRelationships.add(`${rel.from}:${rel.to}:${rel.type}`);
+    }
+
+    // Parse lock relationships into set
+    const lockRelationships = new Set<string>(lock.relationships);
+
+    // Find differences
+    const added: string[] = [];
+    const removed: string[] = [];
+    const modified: string[] = [];
+
+    // Find added and modified entities
+    for (const id of Object.keys(currentHashes)) {
+      if (!(id in lock.entities)) {
+        added.push(id);
+      } else if (lock.entities[id] !== currentHashes[id]) {
+        modified.push(id);
+      }
+    }
+
+    // Find removed entities
+    for (const id of Object.keys(lock.entities)) {
+      if (!(id in currentHashes)) {
+        removed.push(id);
+      }
+    }
+
+    // Find relationship changes
+    const addedRelationships: string[] = [];
+    const removedRelationships: string[] = [];
+
+    for (const rel of currentRelationships) {
+      if (!lockRelationships.has(rel)) {
+        addedRelationships.push(rel);
+      }
+    }
+
+    for (const rel of lockRelationships) {
+      if (!currentRelationships.has(rel)) {
+        removedRelationships.push(rel);
+      }
+    }
+
+    // Check if there are any changes
+    const hasChanges =
+      added.length > 0 ||
+      removed.length > 0 ||
+      modified.length > 0 ||
+      addedRelationships.length > 0 ||
+      removedRelationships.length > 0;
+
+    if (jsonOutput) {
+      // JSON output
+      const result = {
+        hasChanges,
+        added: added.map((id) => ({ id, type: getEntityType(id) })),
+        removed: removed.map((id) => ({ id, type: getEntityType(id) })),
+        modified: modified.map((id) => ({ id, type: getEntityType(id) })),
+        relationships: {
+          added: addedRelationships.map((r) => {
+            const [from, to, type] = r.split(":");
+            return { from, to, type };
+          }),
+          removed: removedRelationships.map((r) => {
+            const [from, to, type] = r.split(":");
+            return { from, to, type };
+          }),
+        },
+        summary: {
+          entitiesAdded: added.length,
+          entitiesRemoved: removed.length,
+          entitiesModified: modified.length,
+          relationshipsAdded: addedRelationships.length,
+          relationshipsRemoved: removedRelationships.length,
+        },
+      };
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      // Human-readable output
+      if (!hasChanges) {
+        console.log("No changes since last lock.");
+        process.exit(0);
+      }
+
+      console.log("Changes since last lock:\n");
+
+      if (added.length > 0) {
+        console.log("ADDED");
+        for (const id of added.sort()) {
+          console.log(`  + ${id} (${getEntityType(id)})`);
+        }
+        console.log("");
+      }
+
+      if (modified.length > 0) {
+        console.log("MODIFIED");
+        for (const id of modified.sort()) {
+          console.log(`  ~ ${id} (${getEntityType(id)})`);
+        }
+        console.log("");
+      }
+
+      if (removed.length > 0) {
+        console.log("REMOVED");
+        for (const id of removed.sort()) {
+          console.log(`  - ${id} (${getEntityType(id)})`);
+        }
+        console.log("");
+      }
+
+      if (addedRelationships.length > 0 || removedRelationships.length > 0) {
+        console.log("RELATIONSHIPS");
+        for (const rel of addedRelationships) {
+          const [from, to, type] = rel.split(":");
+          console.log(`  + ${from} --[${type}]--> ${to}`);
+        }
+        for (const rel of removedRelationships) {
+          const [from, to, type] = rel.split(":");
+          console.log(`  - ${from} --[${type}]--> ${to}`);
+        }
+        console.log("");
+      }
+
+      // Summary
+      console.log("Summary:");
+      const parts: string[] = [];
+      if (added.length > 0) parts.push(`${added.length} added`);
+      if (modified.length > 0) parts.push(`${modified.length} modified`);
+      if (removed.length > 0) parts.push(`${removed.length} removed`);
+      if (addedRelationships.length > 0)
+        parts.push(`${addedRelationships.length} relationship(s) added`);
+      if (removedRelationships.length > 0)
+        parts.push(`${removedRelationships.length} relationship(s) removed`);
+      console.log(`  ${parts.join(", ")}`);
+    }
+
+    // Exit with code 1 if changes exist
+    process.exit(hasChanges ? 1 : 0);
+  } catch (error) {
+    console.error(`Error comparing aide files: ${error instanceof Error ? error.message : error}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Parse lock file content into structured format
+ */
+function parseLockFile(content: string): LockFile {
+  const result: LockFile = {
+    entities: {},
+    relationships: [],
+  };
+
+  let section = "";
+  const lines = content.split("\n");
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip comments and empty lines
+    if (trimmed.startsWith("#") || trimmed === "") {
+      continue;
+    }
+
+    // Section headers
+    if (trimmed === "entities:") {
+      section = "entities";
+      continue;
+    }
+    if (trimmed === "relationships:") {
+      section = "relationships";
+      continue;
+    }
+
+    // Parse content based on section
+    if (section === "entities") {
+      // Format: "  entity_id: hash"
+      const match = trimmed.match(/^(\w+):\s*(\w+)$/);
+      if (match) {
+        result.entities[match[1]] = match[2];
+      }
+    } else if (section === "relationships") {
+      // Format: "  - from:to:type: hash"
+      const match = trimmed.match(/^-\s*(\w+):(\w+):(\w+):\s*\w+$/);
+      if (match) {
+        result.relationships.push(`${match[1]}:${match[2]}:${match[3]}`);
+      }
+    }
+  }
+
+  return result;
+}
+
 /**
  * Print help for aide subcommands
  */
@@ -522,6 +896,7 @@ bantay aide - Manage the aide entity tree
 Usage: bantay aide <subcommand> [options]
 
 Subcommands:
+  init      Create a new .aide file with skeleton structure
   add       Add an entity to the tree
   update    Update an entity's properties
   remove    Remove an entity from the tree
@@ -529,6 +904,10 @@ Subcommands:
   show      Display the entity tree or a specific entity
   validate  Validate the aide file
   lock      Generate a lock file
+  diff      Compare aide against lock file
+
+Init Options:
+  --name, -n    Name for the aide file (default: current directory name)
 
 Add Options:
   <id>              Entity ID (optional, auto-generated if parent provided)
@@ -556,6 +935,9 @@ Show Options:
   [id]              Specific entity to show (optional)
   --format, -f      Output format: tree (default) or json
 
+Diff Options:
+  --json            Output as JSON
+
 Global Options:
   --aide, -a        Path to aide file (default: bantay.aide)
 
@@ -567,5 +949,7 @@ Examples:
   bantay aide show invariants
   bantay aide validate
   bantay aide lock
+  bantay aide diff
+  bantay aide diff --json
 `);
 }

package/src/commands/check.ts

@@ -6,7 +6,7 @@ import { runChecker, hasChecker } from "../checkers/registry";
 import { loadConfig } from "../config";
 import { getGitDiff, shouldCheckInvariant } from "../diff";
 import type { CheckResult, CheckerContext } from "../checkers/types";
-import { read as readAide } from "../aide";
+import { read as readAide, tryResolveAidePath } from "../aide";
 
 export interface CheckOptions {
   id?: string;
@@ -44,16 +44,21 @@ interface InvariantEnforcementInfo {
 }
 
 /**
- * Load checker and test paths from bantay.aide for each invariant
+ * Load checker and test paths from .aide file for each invariant
  */
 async function getEnforcementInfo(
   projectPath: string
 ): Promise<Map<string, InvariantEnforcementInfo>> {
   const info = new Map<string, InvariantEnforcementInfo>();
-  const aidePath = join(projectPath, "bantay.aide");
+
+  // Try to discover the aide file
+  const resolved = await tryResolveAidePath(projectPath);
+  if (!resolved) {
+    return info; // No aide file found, return empty map
+  }
 
   try {
-    const tree = await readAide(aidePath);
+    const tree = await readAide(resolved.path);
     for (const [id, entity] of Object.entries(tree.entities)) {
       if (id.startsWith("inv_")) {
         const enforcement: InvariantEnforcementInfo = {};