@bantay/cli 0.2.0 → 0.3.1

package/src/commands/diff.ts

@@ -0,0 +1,387 @@
+/**
+ * diff.ts — bantay diff command
+ *
+ * Wraps bantay aide diff with entity type classification based on parent chain.
+ * bantay aide diff stays unchanged (raw structural output).
+ * bantay diff adds classification for human-readable output.
+ *
+ * @scenario sc_diff_classified
+ */
+
+import { existsSync } from "fs";
+import { readFile, readdir } from "fs/promises";
+import { read, type AideTree } from "../aide";
+
+/**
+ * Container parents that define entity types
+ */
+const PARENT_TYPE_MAP: Record<string, string> = {
+  cujs: "scenario",
+  invariants: "invariant",
+  constraints: "constraint",
+  foundations: "foundation",
+  wisdom: "wisdom",
+};
+
+const CUJ_PREFIX = "cuj_";
+
+/**
+ * Classified change entry
+ */
+export interface ClassifiedChange {
+  action: "ADDED" | "MODIFIED" | "REMOVED";
+  type: string;
+  entity_id: string;
+  parent?: string;
+  from?: string;
+  to?: string;
+  relationship_type?: string;
+}
+
+/**
+ * Result from diff command
+ */
+export interface DiffResult {
+  hasChanges: boolean;
+  changes: ClassifiedChange[];
+}
+
+/**
+ * Discover aide file in directory
+ */
+async function discoverAideFile(cwd: string): Promise<string | null> {
+  try {
+    const files = await readdir(cwd);
+    const aideFiles = files.filter((f) => f.endsWith(".aide"));
+    if (aideFiles.length === 1) {
+      return `${cwd}/${aideFiles[0]}`;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get entity type by walking parent chain
+ */
+function getEntityTypeByParent(id: string, parent: string | undefined, tree: AideTree): string {
+  if (!parent) {
+    return "entity";
+  }
+
+  // Direct mapping
+  if (parent in PARENT_TYPE_MAP) {
+    return PARENT_TYPE_MAP[parent];
+  }
+
+  // If parent starts with cuj_, child is a scenario
+  if (parent.startsWith(CUJ_PREFIX)) {
+    return "scenario";
+  }
+
+  // Walk up the parent chain
+  const parentEntity = tree.entities[parent];
+  if (parentEntity && parentEntity.parent) {
+    return getEntityTypeByParent(id, parentEntity.parent, tree);
+  }
+
+  return "entity";
+}
+
+/**
+ * Get entity type from parent ID (for removed entities)
+ */
+function getEntityTypeFromParentId(parentId: string): string {
+  if (parentId in PARENT_TYPE_MAP) {
+    return PARENT_TYPE_MAP[parentId];
+  }
+  if (parentId.startsWith(CUJ_PREFIX)) {
+    return "scenario";
+  }
+  return "entity";
+}
+
+/**
+ * Fallback: get entity type from ID prefix
+ */
+function getEntityTypeByIdPrefix(id: string): string {
+  const prefixes: Record<string, string> = {
+    cuj_: "cuj",
+    sc_: "scenario",
+    inv_: "invariant",
+    con_: "constraint",
+    found_: "foundation",
+    wis_: "wisdom",
+  };
+  for (const [prefix, type] of Object.entries(prefixes)) {
+    if (id.startsWith(prefix)) {
+      return type;
+    }
+  }
+  return "entity";
+}
+
+/**
+ * Lock file entity with parent info
+ */
+interface LockFileEntity {
+  hash: string;
+  parent?: string;
+}
+
+interface LockFile {
+  entities: Record<string, LockFileEntity>;
+  relationships: string[];
+}
+
+/**
+ * Parse lock file content
+ */
+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();
+
+    if (trimmed.startsWith("#") || trimmed === "") {
+      continue;
+    }
+
+    if (trimmed === "entities:") {
+      section = "entities";
+      continue;
+    }
+    if (trimmed === "relationships:") {
+      section = "relationships";
+      continue;
+    }
+
+    if (section === "entities") {
+      const matchWithParent = trimmed.match(/^(\w+):\s*(\w+)\s+parent:(\w+)$/);
+      if (matchWithParent) {
+        result.entities[matchWithParent[1]] = {
+          hash: matchWithParent[2],
+          parent: matchWithParent[3],
+        };
+      } else {
+        const match = trimmed.match(/^(\w+):\s*(\w+)$/);
+        if (match) {
+          result.entities[match[1]] = {
+            hash: match[2],
+          };
+        }
+      }
+    } else if (section === "relationships") {
+      const match = trimmed.match(/^-\s*(\w+):(\w+):(\w+):\s*\w+$/);
+      if (match) {
+        result.relationships.push(`${match[1]}:${match[2]}:${match[3]}`);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Compute entity hash (same as aide.ts)
+ */
+function computeEntityHash(
+  id: string,
+  entity: { display?: string; parent?: string; props?: Record<string, unknown> }
+): string {
+  const str = JSON.stringify({ id, ...entity });
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(16).padStart(8, "0");
+}
+
+/**
+ * Run diff and classify changes
+ */
+export async function runDiff(projectPath: string): Promise<DiffResult> {
+  const aidePath = await discoverAideFile(projectPath);
+
+  if (!aidePath) {
+    throw new Error("No .aide file found. Run 'bantay aide init' to create one.");
+  }
+
+  const lockPath = `${aidePath}.lock`;
+
+  if (!existsSync(lockPath)) {
+    throw new Error(`Lock file not found: ${lockPath}. Run 'bantay aide lock' first.`);
+  }
+
+  // Read current aide tree
+  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 relationships
+  const currentRelationships = new Set<string>();
+  for (const rel of tree.relationships) {
+    currentRelationships.add(`${rel.from}:${rel.to}:${rel.type}`);
+  }
+
+  const lockRelationships = new Set<string>(lock.relationships);
+
+  // Build classified changes
+  const changes: ClassifiedChange[] = [];
+
+  // Added entities
+  for (const id of Object.keys(currentHashes)) {
+    if (!(id in lock.entities)) {
+      const entity = tree.entities[id];
+      const parent = entity.parent;
+      const entityType = getEntityTypeByParent(id, parent, tree);
+      changes.push({
+        action: "ADDED",
+        type: entityType,
+        entity_id: id,
+        parent,
+      });
+    } else if (lock.entities[id].hash !== currentHashes[id]) {
+      const entity = tree.entities[id];
+      const parent = entity.parent;
+      const entityType = getEntityTypeByParent(id, parent, tree);
+      changes.push({
+        action: "MODIFIED",
+        type: entityType,
+        entity_id: id,
+        parent,
+      });
+    }
+  }
+
+  // Removed entities
+  for (const id of Object.keys(lock.entities)) {
+    if (!(id in currentHashes)) {
+      const lockEntity = lock.entities[id];
+      let entityType: string;
+      if (lockEntity.parent) {
+        entityType = getEntityTypeFromParentId(lockEntity.parent);
+      } else {
+        entityType = getEntityTypeByIdPrefix(id);
+      }
+      changes.push({
+        action: "REMOVED",
+        type: entityType,
+        entity_id: id,
+        parent: lockEntity.parent,
+      });
+    }
+  }
+
+  // Added relationships
+  for (const rel of currentRelationships) {
+    if (!lockRelationships.has(rel)) {
+      const [from, to, relType] = rel.split(":");
+      changes.push({
+        action: "ADDED",
+        type: "relationship",
+        entity_id: `${from}:${to}`,
+        from,
+        to,
+        relationship_type: relType,
+      });
+    }
+  }
+
+  // Removed relationships
+  for (const rel of lockRelationships) {
+    if (!currentRelationships.has(rel)) {
+      const [from, to, relType] = rel.split(":");
+      changes.push({
+        action: "REMOVED",
+        type: "relationship",
+        entity_id: `${from}:${to}`,
+        from,
+        to,
+        relationship_type: relType,
+      });
+    }
+  }
+
+  return {
+    hasChanges: changes.length > 0,
+    changes,
+  };
+}
+
+/**
+ * Format diff result as human-readable output
+ */
+export function formatDiff(result: DiffResult): string {
+  if (!result.hasChanges) {
+    return "No changes since last lock.";
+  }
+
+  const lines: string[] = [];
+
+  // Sort by action then by entity_id
+  const sorted = [...result.changes].sort((a, b) => {
+    const actionOrder = { ADDED: 0, MODIFIED: 1, REMOVED: 2 };
+    const actionDiff = actionOrder[a.action] - actionOrder[b.action];
+    if (actionDiff !== 0) return actionDiff;
+    return a.entity_id.localeCompare(b.entity_id);
+  });
+
+  for (const change of sorted) {
+    if (change.type === "relationship") {
+      lines.push(`${change.action} relationship: ${change.from} → ${change.to}`);
+    } else {
+      const parentStr = change.parent ? ` (parent: ${change.parent})` : "";
+      lines.push(`${change.action} ${change.type}: ${change.entity_id}${parentStr}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format diff result as JSON
+ */
+export function formatDiffJson(result: DiffResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+/**
+ * Handle bantay diff command
+ */
+export async function handleDiff(args: string[]): Promise<void> {
+  const projectPath = process.cwd();
+  const jsonOutput = args.includes("--json");
+
+  try {
+    const result = await runDiff(projectPath);
+
+    if (jsonOutput) {
+      console.log(formatDiffJson(result));
+    } else {
+      console.log(formatDiff(result));
+    }
+
+    process.exit(result.hasChanges ? 1 : 0);
+  } catch (error) {
+    console.error(`Error: ${error instanceof Error ? error.message : error}`);
+    process.exit(1);
+  }
+}

package/src/commands/init.ts

@@ -1,11 +1,18 @@
-import { writeFile, access } from "fs/promises";
+import { writeFile, access, mkdir } from "fs/promises";
 import { join } from "path";
 import { detectStack, type StackDetectionResult } from "../detectors";
 import { generateInvariants } from "../generators/invariants";
 import { generateConfig, configToYaml } from "../generators/config";
+import {
+  generateInterviewCommand,
+  generateStatusCommand,
+  generateCheckCommand,
+  generateOrchestrateCommand,
+} from "../generators/claude-commands";
 
 export interface InitOptions {
   regenerateConfig?: boolean;
+  force?: boolean;
 }
 
 export interface InitResult {
@@ -66,6 +73,36 @@ export async function runInit(
     filesCreated.push("bantay.config.yml");
   }
 
+  // Generate Claude Code slash commands
+  const claudeCommandsDir = join(projectPath, ".claude", "commands");
+  await mkdir(claudeCommandsDir, { recursive: true });
+
+  const interviewPath = join(claudeCommandsDir, "bantay-interview.md");
+  const statusPath = join(claudeCommandsDir, "bantay-status.md");
+  const checkPath = join(claudeCommandsDir, "bantay-check.md");
+  const orchestratePath = join(claudeCommandsDir, "bantay-orchestrate.md");
+
+  // Only create if they don't exist (don't overwrite user customizations) unless --force
+  if (options?.force || !(await fileExists(interviewPath))) {
+    await writeFile(interviewPath, generateInterviewCommand());
+    filesCreated.push(".claude/commands/bantay-interview.md");
+  }
+
+  if (options?.force || !(await fileExists(statusPath))) {
+    await writeFile(statusPath, generateStatusCommand());
+    filesCreated.push(".claude/commands/bantay-status.md");
+  }
+
+  if (options?.force || !(await fileExists(checkPath))) {
+    await writeFile(checkPath, generateCheckCommand());
+    filesCreated.push(".claude/commands/bantay-check.md");
+  }
+
+  if (options?.force || !(await fileExists(orchestratePath))) {
+    await writeFile(orchestratePath, generateOrchestrateCommand());
+    filesCreated.push(".claude/commands/bantay-orchestrate.md");
+  }
+
   return {
     success: true,
     filesCreated,

package/src/commands/status.ts

@@ -1,6 +1,7 @@
 import { readFile, readdir, access } from "fs/promises";
 import { join, relative } from "path";
 import * as yaml from "js-yaml";
+import { tryResolveAidePath } from "../aide";
 
 export interface StatusOptions {
   json?: boolean;
@@ -146,17 +147,18 @@ export async function runStatus(
   projectPath: string,
   options?: StatusOptions
 ): Promise<StatusResult> {
-  const aidePath = join(projectPath, "bantay.aide");
-
-  // Check if aide file exists
-  if (!(await fileExists(aidePath))) {
+  // Discover aide file
+  const resolved = await tryResolveAidePath(projectPath);
+  if (!resolved) {
     return {
       scenarios: [],
       summary: { total: 0, implemented: 0, missing: 0 },
-      error: "bantay.aide not found",
+      error: "No .aide file found. Run 'bantay aide init' to create one.",
     };
   }
 
+  const aidePath = resolved.path;
+
   // Parse aide file
   let aideContent: AideFile;
   try {
@@ -166,7 +168,7 @@ export async function runStatus(
     return {
       scenarios: [],
       summary: { total: 0, implemented: 0, missing: 0 },
-      error: `Failed to parse bantay.aide: ${e instanceof Error ? e.message : String(e)}`,
+      error: `Failed to parse ${resolved.filename}: ${e instanceof Error ? e.message : String(e)}`,
     };
   }
 
@@ -174,7 +176,7 @@ export async function runStatus(
     return {
       scenarios: [],
       summary: { total: 0, implemented: 0, missing: 0 },
-      error: "bantay.aide has no entities",
+      error: `${resolved.filename} has no entities`,
     };
   }
 

package/src/commands/tasks.ts

@@ -0,0 +1,220 @@
+import { readFile, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import * as yaml from "js-yaml";
+import { resolveAidePath } from "../aide/discovery";
+
+interface Entity {
+  id: string;
+  parent?: string;
+  display?: string;
+  props?: Record<string, string>;
+}
+
+interface Relationship {
+  from: string;
+  to: string;
+  type: string;
+  cardinality?: string;
+}
+
+interface AideData {
+  entities: Record<string, Entity>;
+  relationships: Relationship[];
+}
+
+interface CUJ {
+  id: string;
+  feature: string;
+  tier?: string;
+  area?: string;
+  scenarios: Scenario[];
+  dependsOn: string[];
+}
+
+interface Scenario {
+  id: string;
+  name: string;
+  given?: string;
+  when?: string;
+  then?: string;
+}
+
+interface TasksOptions {
+  all?: boolean;
+  aide?: string;
+}
+
+export async function runTasks(
+  projectPath: string,
+  options: TasksOptions = {}
+): Promise<{ outputPath: string; cujs: CUJ[] }> {
+  // Resolve aide file path
+  const { path: aidePath, filename } = await resolveAidePath(
+    projectPath,
+    options.aide
+  );
+
+  if (!existsSync(aidePath)) {
+    throw new Error("No .aide file found. Run 'bantay aide init' to create one.");
+  }
+
+  // Parse the aide file
+  const aideContent = await readFile(aidePath, "utf-8");
+  const aideData = yaml.load(aideContent) as AideData;
+
+  // Get CUJs to process
+  let cujsToProcess: string[];
+
+  if (options.all) {
+    // All CUJs
+    cujsToProcess = Object.keys(aideData.entities).filter((id) =>
+      id.startsWith("cuj_")
+    );
+  } else {
+    // Diff mode - only added/modified CUJs
+    const lockPath = aidePath + ".lock";
+    if (!existsSync(lockPath)) {
+      throw new Error(
+        "No lock file found. Run 'bantay aide lock' first, or use --all for full generation."
+      );
+    }
+
+    const lockContent = await readFile(lockPath, "utf-8");
+    const lockData = yaml.load(lockContent) as { entities: Record<string, string> };
+
+    // Find CUJs that are new or modified
+    cujsToProcess = Object.keys(aideData.entities).filter((id) => {
+      if (!id.startsWith("cuj_")) return false;
+      // CUJ is new if not in lock file
+      if (!lockData.entities[id]) return true;
+      // CUJ is modified if hash differs (we'd need to compute hash, but for now check existence)
+      return false;
+    });
+  }
+
+  // Build CUJ objects with scenarios and dependencies
+  const cujs: CUJ[] = cujsToProcess.map((id) => {
+    const entity = aideData.entities[id];
+    const props = entity.props || {};
+
+    // Find scenarios that are children of this CUJ
+    const scenarios: Scenario[] = Object.entries(aideData.entities)
+      .filter(([scId, scEntity]) =>
+        scId.startsWith("sc_") && scEntity.parent === id
+      )
+      .map(([scId, scEntity]) => ({
+        id: scId,
+        name: scEntity.props?.name || scId,
+        given: scEntity.props?.given,
+        when: scEntity.props?.when,
+        then: scEntity.props?.then,
+      }));
+
+    // Find dependencies (depends_on relationships where this CUJ is the 'from')
+    const dependsOn: string[] = aideData.relationships
+      .filter((rel) => rel.from === id && rel.type === "depends_on")
+      .map((rel) => rel.to);
+
+    return {
+      id,
+      feature: props.feature || id,
+      tier: props.tier,
+      area: props.area,
+      scenarios,
+      dependsOn,
+    };
+  });
+
+  // Order CUJs into phases using topological sort
+  const phases = topologicalSort(cujs);
+
+  // Generate tasks.md content
+  const content = generateTasksMarkdown(phases);
+
+  // Write to tasks.md
+  const outputPath = join(projectPath, "tasks.md");
+  await writeFile(outputPath, content, "utf-8");
+
+  return { outputPath, cujs };
+}
+
+function topologicalSort(cujs: CUJ[]): CUJ[][] {
+  const cujMap = new Map(cujs.map((c) => [c.id, c]));
+  const phases: CUJ[][] = [];
+  const processed = new Set<string>();
+
+  // Keep going until all CUJs are processed
+  while (processed.size < cujs.length) {
+    const phase: CUJ[] = [];
+
+    for (const cuj of cujs) {
+      if (processed.has(cuj.id)) continue;
+
+      // Check if all dependencies are already processed
+      const allDepsProcessed = cuj.dependsOn.every(
+        (dep) => !cujMap.has(dep) || processed.has(dep)
+      );
+
+      if (allDepsProcessed) {
+        phase.push(cuj);
+      }
+    }
+
+    if (phase.length === 0 && processed.size < cujs.length) {
+      // Circular dependency - just add remaining
+      for (const cuj of cujs) {
+        if (!processed.has(cuj.id)) {
+          phase.push(cuj);
+        }
+      }
+    }
+
+    for (const cuj of phase) {
+      processed.add(cuj.id);
+    }
+
+    if (phase.length > 0) {
+      phases.push(phase);
+    }
+  }
+
+  return phases;
+}
+
+function generateTasksMarkdown(phases: CUJ[][]): string {
+  const lines: string[] = ["# Tasks", ""];
+
+  for (let i = 0; i < phases.length; i++) {
+    const phase = phases[i];
+    lines.push(`## Phase ${i + 1}`);
+    lines.push("");
+
+    for (const cuj of phase) {
+      lines.push(`### ${cuj.id}: ${cuj.feature}`);
+      lines.push("");
+      lines.push(`- [ ] Implement ${cuj.feature}`);
+      lines.push("");
+
+      if (cuj.scenarios.length > 0) {
+        lines.push("**Acceptance Criteria:**");
+        lines.push("");
+        for (const sc of cuj.scenarios) {
+          lines.push(`- [ ] ${sc.name}`);
+          if (sc.given || sc.when || sc.then) {
+            if (sc.given) lines.push(`  - Given: ${sc.given}`);
+            if (sc.when) lines.push(`  - When: ${sc.when}`);
+            if (sc.then) lines.push(`  - Then: ${sc.then}`);
+          }
+        }
+        lines.push("");
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function formatTasks(result: { outputPath: string; cujs: CUJ[] }): string {
+  return `Generated ${result.outputPath} with ${result.cujs.length} tasks`;
+}