@bantay/cli 0.1.1 → 0.3.0

package/src/commands/status.ts

@@ -0,0 +1,311 @@
+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;
+}
+
+export interface ScenarioStatus {
+  id: string;
+  name: string;
+  parentCuj: string;
+  status: "implemented" | "missing";
+  testFile?: string;
+  line?: number;
+}
+
+export interface StatusSummary {
+  total: number;
+  implemented: number;
+  missing: number;
+}
+
+export interface StatusResult {
+  scenarios: ScenarioStatus[];
+  summary: StatusSummary;
+  cujs?: Record<string, string>;
+  error?: string;
+}
+
+interface AideEntity {
+  parent?: string;
+  props?: {
+    name?: string;
+    feature?: string;
+    [key: string]: unknown;
+  };
+}
+
+interface AideFile {
+  entities: Record<string, AideEntity>;
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findTestFiles(testsDir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await walk(fullPath);
+        } else if (entry.name.endsWith(".test.ts") || entry.name.endsWith(".test.js")) {
+          files.push(fullPath);
+        }
+      }
+    } catch {
+      // Directory doesn't exist or isn't readable
+    }
+  }
+
+  await walk(testsDir);
+  return files;
+}
+
+async function searchTestFileForScenario(
+  testFilePath: string,
+  scenarioId: string
+): Promise<{ found: boolean; line?: number }> {
+  try {
+    const content = await readFile(testFilePath, "utf-8");
+    const lines = content.split("\n");
+
+    // Priority 1: Look for explicit scenario marker (highest priority)
+    // Formats: @scenario sc_xxx, // sc_xxx:, // sc_xxx, * @scenario sc_xxx
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (
+        line.includes(`@scenario ${scenarioId}`) ||
+        line.includes(`@scenario: ${scenarioId}`) ||
+        line.includes(`// ${scenarioId}:`) ||
+        line.includes(`// ${scenarioId} `) ||
+        line.match(new RegExp(`\\*\\s*@scenario\\s+${scenarioId}\\b`))
+      ) {
+        return { found: true, line: i + 1 };
+      }
+    }
+
+    // Priority 2: Look for describe/test block containing exact scenario ID
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      // Match scenario ID in describe block or test name
+      const isDescribeOrTest = /^\s*(describe|test|it)\s*\(/.test(line);
+      if (isDescribeOrTest && (line.includes(`"${scenarioId}"`) || line.includes(`'${scenarioId}'`))) {
+        return { found: true, line: i + 1 };
+      }
+    }
+
+    return { found: false };
+  } catch {
+    return { found: false };
+  }
+}
+
+function scenarioIdToTestFileName(scenarioId: string): string[] {
+  // Convert sc_init_prerequisites to possible test file names
+  // sc_init_prerequisites -> [prerequisites, init-prerequisites, init]
+  const withoutPrefix = scenarioId.replace(/^sc_/, "");
+  const parts = withoutPrefix.split("_");
+
+  const candidates: string[] = [];
+
+  // Full name with dashes: init-prerequisites
+  candidates.push(parts.join("-"));
+
+  // Last part only: prerequisites
+  if (parts.length > 1) {
+    candidates.push(parts[parts.length - 1]);
+    candidates.push(parts.slice(1).join("-"));
+  }
+
+  // First part only: init
+  candidates.push(parts[0]);
+
+  return candidates;
+}
+
+function testFileMatchesScenario(testFileName: string, scenarioId: string): boolean {
+  const baseName = testFileName.replace(/\.test\.(ts|js)$/, "");
+  const candidates = scenarioIdToTestFileName(scenarioId);
+
+  return candidates.some(candidate => baseName === candidate);
+}
+
+export async function runStatus(
+  projectPath: string,
+  options?: StatusOptions
+): Promise<StatusResult> {
+  // Discover aide file
+  const resolved = await tryResolveAidePath(projectPath);
+  if (!resolved) {
+    return {
+      scenarios: [],
+      summary: { total: 0, implemented: 0, missing: 0 },
+      error: "No .aide file found. Run 'bantay aide init' to create one.",
+    };
+  }
+
+  const aidePath = resolved.path;
+
+  // Parse aide file
+  let aideContent: AideFile;
+  try {
+    const rawContent = await readFile(aidePath, "utf-8");
+    aideContent = yaml.load(rawContent) as AideFile;
+  } catch (e) {
+    return {
+      scenarios: [],
+      summary: { total: 0, implemented: 0, missing: 0 },
+      error: `Failed to parse ${resolved.filename}: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+
+  if (!aideContent?.entities) {
+    return {
+      scenarios: [],
+      summary: { total: 0, implemented: 0, missing: 0 },
+      error: `${resolved.filename} has no entities`,
+    };
+  }
+
+  // Extract CUJ information
+  const cujs: Record<string, string> = {};
+  for (const [id, entity] of Object.entries(aideContent.entities)) {
+    if (id.startsWith("cuj_") && entity.props?.feature) {
+      cujs[id] = entity.props.feature;
+    }
+  }
+
+  // Extract all sc_* entities
+  const scenarios: ScenarioStatus[] = [];
+  for (const [id, entity] of Object.entries(aideContent.entities)) {
+    if (id.startsWith("sc_")) {
+      scenarios.push({
+        id,
+        name: entity.props?.name || id,
+        parentCuj: entity.parent || "unknown",
+        status: "missing",
+      });
+    }
+  }
+
+  // Find test files
+  const testsDir = join(projectPath, "tests");
+  const testFiles = await findTestFiles(testsDir);
+
+  // Match scenarios to test files
+  for (const scenario of scenarios) {
+    // Priority 1: Explicit scenario ID in test file
+    for (const testFile of testFiles) {
+      // Skip status-command.test.ts as it's a meta test that contains scenario IDs as test data
+      if (testFile.includes("status-command.test.ts")) {
+        continue;
+      }
+
+      const result = await searchTestFileForScenario(testFile, scenario.id);
+      if (result.found) {
+        scenario.status = "implemented";
+        scenario.testFile = relative(projectPath, testFile);
+        scenario.line = result.line;
+        break;
+      }
+    }
+
+    // Priority 2: Test file name matches scenario (if not already matched)
+    if (scenario.status === "missing") {
+      for (const testFile of testFiles) {
+        if (testFile.includes("status-command.test.ts")) {
+          continue;
+        }
+
+        const fileName = testFile.split("/").pop() || "";
+        if (testFileMatchesScenario(fileName, scenario.id)) {
+          // Found a file that matches by name, but verify it has relevant tests
+          try {
+            const content = await readFile(testFile, "utf-8");
+            // Ensure it's not an empty or stub test file
+            if (content.includes("describe(") || content.includes("test(")) {
+              scenario.status = "implemented";
+              scenario.testFile = relative(projectPath, testFile);
+              scenario.line = 1; // Start of file when matched by name
+              break;
+            }
+          } catch {
+            // Skip if can't read file
+          }
+        }
+      }
+    }
+  }
+
+  // Calculate summary
+  const implemented = scenarios.filter((s) => s.status === "implemented").length;
+  const missing = scenarios.filter((s) => s.status === "missing").length;
+
+  return {
+    scenarios,
+    summary: {
+      total: scenarios.length,
+      implemented,
+      missing,
+    },
+    cujs,
+  };
+}
+
+export function formatStatus(result: StatusResult): string {
+  if (result.error) {
+    return `Error: ${result.error}\n`;
+  }
+
+  const lines: string[] = [];
+  lines.push("# Scenario Implementation Status\n");
+
+  // Group scenarios by CUJ
+  const byParent: Record<string, ScenarioStatus[]> = {};
+  for (const scenario of result.scenarios) {
+    if (!byParent[scenario.parentCuj]) {
+      byParent[scenario.parentCuj] = [];
+    }
+    byParent[scenario.parentCuj].push(scenario);
+  }
+
+  // Output by CUJ
+  for (const [cuj, scenarios] of Object.entries(byParent)) {
+    const cujName = result.cujs?.[cuj] || cuj;
+    lines.push(`\n## ${cujName}\n`);
+
+    for (const scenario of scenarios) {
+      const icon = scenario.status === "implemented" ? "✓" : "○";
+      const location = scenario.testFile
+        ? `${scenario.testFile}${scenario.line ? `:${scenario.line}` : ""}`
+        : "";
+
+      lines.push(`${icon} ${scenario.id}: ${scenario.name}`);
+      if (location) {
+        lines.push(`  → ${location}`);
+      }
+    }
+  }
+
+  // Summary
+  lines.push(`\n---`);
+  lines.push(
+    `Implemented: ${result.summary.implemented}/${result.summary.total} (${Math.round((result.summary.implemented / result.summary.total) * 100)}%)`
+  );
+  lines.push(`Missing: ${result.summary.missing}`);
+
+  return lines.join("\n");
+}

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`;
+}

package/src/export/all.ts

@@ -5,10 +5,11 @@
 import { exportInvariants } from "./invariants";
 import { exportClaude } from "./claude";
 import { exportCursor } from "./cursor";
+import { exportCodex } from "./codex";
 import type { ExportOptions, ExportResult } from "./types";
 
 /**
- * Export all targets: invariants.md, CLAUDE.md, .cursorrules
+ * Export all targets: invariants.md, CLAUDE.md, .cursorrules, AGENTS.md
  */
 export async function exportAll(
   projectPath: string,
@@ -25,5 +26,8 @@ export async function exportAll(
   // Export .cursorrules
   results.push(await exportCursor(projectPath, options));
 
+  // Export AGENTS.md
+  results.push(await exportCodex(projectPath, options));
+
   return results;
 }

package/src/export/claude.ts

@@ -4,7 +4,7 @@
 
 import { readFile, writeFile, access } from "fs/promises";
 import { join } from "path";
-import { read as readAide } from "../aide";
+import { read as readAide, resolveAidePath } from "../aide";
 import {
   extractConstraints,
   extractFoundations,
@@ -27,7 +27,8 @@ import {
 export function generateClaudeSection(
   constraints: ExtractedConstraint[],
   foundations: ExtractedFoundation[],
-  invariants: ExtractedInvariant[]
+  invariants: ExtractedInvariant[],
+  aideFilename: string = "*.aide"
 ): string {
   const lines: string[] = [];
 
@@ -35,7 +36,7 @@ export function generateClaudeSection(
   lines.push("");
   lines.push("## Bantay Project Rules");
   lines.push("");
-  lines.push("*Auto-generated from bantay.aide. Do not edit manually.*");
+  lines.push(`*Auto-generated from ${aideFilename}. Do not edit manually.*`);
   lines.push("");
 
   // Foundations as principles
@@ -184,7 +185,9 @@ export async function exportClaude(
   projectPath: string,
   options: ExportOptions = {}
 ): Promise<ExportResult> {
-  const aidePath = options.aidePath || join(projectPath, "bantay.aide");
+  // Discover aide file if not explicitly provided
+  const resolved = await resolveAidePath(projectPath, options.aidePath);
+  const aidePath = resolved.path;
   const outputPath = options.outputPath || join(projectPath, "CLAUDE.md");
 
   // Read the aide tree
@@ -196,7 +199,7 @@ export async function exportClaude(
   const invariants = extractInvariants(tree);
 
   // Generate section content
-  const section = generateClaudeSection(constraints, foundations, invariants);
+  const section = generateClaudeSection(constraints, foundations, invariants, resolved.filename);
 
   // Read existing file if it exists
   let existingContent = "";

package/src/export/codex.ts

@@ -0,0 +1,72 @@
+/**
+ * Export to AGENTS.md with section markers
+ * Works for Codex, Copilot, and any agent that reads AGENTS.md
+ */
+
+import { readFile, writeFile, access } from "fs/promises";
+import { join } from "path";
+import { read as readAide, resolveAidePath } from "../aide";
+import {
+  extractConstraints,
+  extractFoundations,
+  extractInvariants,
+} from "./aide-reader";
+import { generateClaudeSection, insertSection } from "./claude";
+import type { ExportOptions, ExportResult } from "./types";
+
+/**
+ * Check if a file exists
+ */
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Export to AGENTS.md
+ */
+export async function exportCodex(
+  projectPath: string,
+  options: ExportOptions = {}
+): Promise<ExportResult> {
+  // Discover aide file if not explicitly provided
+  const resolved = await resolveAidePath(projectPath, options.aidePath);
+  const aidePath = resolved.path;
+  const outputPath = options.outputPath || join(projectPath, "AGENTS.md");
+
+  // Read the aide tree
+  const tree = await readAide(aidePath);
+
+  // Extract entities
+  const constraints = extractConstraints(tree);
+  const foundations = extractFoundations(tree);
+  const invariants = extractInvariants(tree);
+
+  // Generate section content (same format as claude)
+  const section = generateClaudeSection(constraints, foundations, invariants, resolved.filename);
+
+  // Read existing file if it exists
+  let existingContent = "";
+  if (await fileExists(outputPath)) {
+    existingContent = await readFile(outputPath, "utf-8");
+  }
+
+  // Insert or replace section
+  const content = insertSection(existingContent, section);
+
+  // Write unless dry run
+  if (!options.dryRun) {
+    await writeFile(outputPath, content, "utf-8");
+  }
+
+  return {
+    target: "codex",
+    outputPath,
+    content,
+    bytesWritten: Buffer.byteLength(content, "utf-8"),
+  };
+}

package/src/export/cursor.ts

@@ -4,7 +4,7 @@
 
 import { readFile, writeFile, access } from "fs/promises";
 import { join } from "path";
-import { read as readAide } from "../aide";
+import { read as readAide, resolveAidePath } from "../aide";
 import {
   extractConstraints,
   extractFoundations,
@@ -32,7 +32,9 @@ export async function exportCursor(
   projectPath: string,
   options: ExportOptions = {}
 ): Promise<ExportResult> {
-  const aidePath = options.aidePath || join(projectPath, "bantay.aide");
+  // Discover aide file if not explicitly provided
+  const resolved = await resolveAidePath(projectPath, options.aidePath);
+  const aidePath = resolved.path;
   const outputPath = options.outputPath || join(projectPath, ".cursorrules");
 
   // Read the aide tree
@@ -44,7 +46,7 @@ export async function exportCursor(
   const invariants = extractInvariants(tree);
 
   // Generate section content (same format as claude)
-  const section = generateClaudeSection(constraints, foundations, invariants);
+  const section = generateClaudeSection(constraints, foundations, invariants, resolved.filename);
 
   // Read existing file if it exists
   let existingContent = "";

package/src/export/index.ts

@@ -5,6 +5,7 @@
 export { exportInvariants, generateInvariantsMd } from "./invariants";
 export { exportClaude, generateClaudeSection, insertSection } from "./claude";
 export { exportCursor } from "./cursor";
+export { exportCodex } from "./codex";
 export { exportAll } from "./all";
 
 export type {