@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/extensions/kata/tests/worktree.test.ts

@@ -0,0 +1,222 @@
+import {
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import {
+  autoCommitCurrentBranch,
+  ensureSliceBranch,
+  getActiveSliceBranch,
+  getCurrentBranch,
+  getSliceBranchName,
+  mergeSliceToMain,
+  switchToMain,
+} from "../worktree.ts";
+import { deriveState } from "../state.ts";
+import { indexWorkspace } from "../workspace-index.ts";
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition: boolean, message: string): void {
+  if (condition) passed++;
+  else {
+    failed++;
+    console.error(`  FAIL: ${message}`);
+  }
+}
+
+function assertEq<T>(actual: T, expected: T, message: string): void {
+  if (JSON.stringify(actual) === JSON.stringify(expected)) passed++;
+  else {
+    failed++;
+    console.error(
+      `  FAIL: ${message} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,
+    );
+  }
+}
+
+function run(command: string, cwd: string): string {
+  return execSync(command, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}
+
+const base = mkdtempSync(join(tmpdir(), "kata-branch-test-"));
+run("git init -b main", base);
+run("git config user.name 'Pi Test'", base);
+run("git config user.email 'pi@example.com'", base);
+mkdirSync(join(base, ".kata", "milestones", "M001", "slices", "S01", "tasks"), {
+  recursive: true,
+});
+writeFileSync(join(base, "README.md"), "hello\n", "utf-8");
+writeFileSync(
+  join(base, ".kata", "milestones", "M001", "M001-ROADMAP.md"),
+  `# M001: Demo\n\n## Slices\n- [ ] **S01: Slice One** \`risk:low\` \`depends:[]\`\n  > After this: demo works\n`,
+  "utf-8",
+);
+writeFileSync(
+  join(base, ".kata", "milestones", "M001", "slices", "S01", "S01-PLAN.md"),
+  `# S01: Slice One\n\n**Goal:** Demo\n**Demo:** Demo\n\n## Must-Haves\n- done\n\n## Tasks\n- [ ] **T01: Implement** \`est:10m\`\n  do it\n`,
+  "utf-8",
+);
+run("git add .", base);
+run("git commit -m 'chore: init'", base);
+
+async function main(): Promise<void> {
+  console.log("\n=== ensureSliceBranch ===");
+  const created = ensureSliceBranch(base, "M001", "S01");
+  assert(created, "branch created on first ensure");
+  assertEq(getCurrentBranch(base), "kata/M001/S01", "switched to slice branch");
+
+  console.log("\n=== idempotent ensure ===");
+  const secondCreate = ensureSliceBranch(base, "M001", "S01");
+  assertEq(secondCreate, false, "branch not recreated on second ensure");
+  assertEq(getCurrentBranch(base), "kata/M001/S01", "still on slice branch");
+
+  console.log("\n=== getActiveSliceBranch ===");
+  assertEq(
+    getActiveSliceBranch(base),
+    "kata/M001/S01",
+    "getActiveSliceBranch returns current slice branch",
+  );
+
+  console.log("\n=== state surfaces active branch ===");
+  const state = await deriveState(base);
+  assertEq(state.activeBranch, "kata/M001/S01", "state exposes active branch");
+
+  console.log("\n=== workspace index surfaces branch ===");
+  const index = await indexWorkspace(base);
+  const slice = index.milestones[0]?.slices[0];
+  assertEq(slice?.branch, "kata/M001/S01", "workspace index exposes branch");
+
+  console.log("\n=== autoCommitCurrentBranch ===");
+  // Clean — should return null
+  const cleanResult = autoCommitCurrentBranch(
+    base,
+    "execute-task",
+    "M001/S01/T01",
+  );
+  assertEq(cleanResult, null, "returns null for clean repo");
+
+  // Make dirty
+  writeFileSync(join(base, "dirty.txt"), "uncommitted\n", "utf-8");
+  const dirtyResult = autoCommitCurrentBranch(
+    base,
+    "execute-task",
+    "M001/S01/T01",
+  );
+  assert(dirtyResult !== null, "returns commit message for dirty repo");
+  assert(
+    dirtyResult!.includes("M001/S01/T01"),
+    "commit message includes unit id",
+  );
+  assertEq(
+    run("git status --short", base),
+    "",
+    "repo is clean after auto-commit",
+  );
+
+  console.log("\n=== switchToMain ===");
+  switchToMain(base);
+  assertEq(getCurrentBranch(base), "main", "switched back to main");
+  assertEq(
+    getActiveSliceBranch(base),
+    null,
+    "getActiveSliceBranch returns null on main",
+  );
+
+  console.log("\n=== mergeSliceToMain ===");
+  // Switch back to slice, make a change, switch to main, merge
+  ensureSliceBranch(base, "M001", "S01");
+  writeFileSync(join(base, "README.md"), "hello from slice\n", "utf-8");
+  run("git add README.md", base);
+  run("git commit -m 'feat: slice change'", base);
+  switchToMain(base);
+
+  const merge = mergeSliceToMain(base, "M001", "S01", "Slice One");
+  assertEq(merge.branch, "kata/M001/S01", "merge reports branch");
+  assertEq(getCurrentBranch(base), "main", "still on main after merge");
+  assert(
+    readFileSync(join(base, "README.md"), "utf-8").includes("slice"),
+    "main got squashed content",
+  );
+  assert(merge.deletedBranch, "branch was deleted");
+
+  // Verify branch is actually gone
+  const branches = run("git branch", base);
+  assert(!branches.includes("kata/M001/S01"), "slice branch no longer exists");
+
+  console.log("\n=== switchToMain auto-commits dirty files ===");
+  // Set up S02
+  mkdirSync(
+    join(base, ".kata", "milestones", "M001", "slices", "S02", "tasks"),
+    { recursive: true },
+  );
+  writeFileSync(
+    join(base, ".kata", "milestones", "M001", "M001-ROADMAP.md"),
+    [
+      "# M001: Demo",
+      "",
+      "## Slices",
+      "- [x] **S01: Slice One** `risk:low` `depends:[]`",
+      "  > Done",
+      "- [ ] **S02: Slice Two** `risk:low` `depends:[]`",
+      "  > Demo 2",
+    ].join("\n") + "\n",
+    "utf-8",
+  );
+  run("git add .", base);
+  run("git commit -m 'chore: add S02'", base);
+
+  ensureSliceBranch(base, "M001", "S02");
+  writeFileSync(join(base, "feature.txt"), "new feature\n", "utf-8");
+  // Don't commit — switchToMain should auto-commit
+  switchToMain(base);
+  assertEq(
+    getCurrentBranch(base),
+    "main",
+    "switched to main despite dirty files",
+  );
+
+  // Verify the commit happened on the slice branch
+  ensureSliceBranch(base, "M001", "S02");
+  assert(
+    readFileSync(join(base, "feature.txt"), "utf-8").includes("new feature"),
+    "dirty file was committed on slice branch",
+  );
+  switchToMain(base);
+
+  // Now merge S02
+  const mergeS02 = mergeSliceToMain(base, "M001", "S02", "Slice Two");
+  assert(
+    readFileSync(join(base, "feature.txt"), "utf-8").includes("new feature"),
+    "main got feature from auto-committed branch",
+  );
+  assertEq(mergeS02.deletedBranch, true, "S02 branch deleted");
+
+  console.log("\n=== getSliceBranchName ===");
+  assertEq(
+    getSliceBranchName("M001", "S01"),
+    "kata/M001/S01",
+    "branch name format correct",
+  );
+
+  rmSync(base, { recursive: true, force: true });
+  console.log(`\nResults: ${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+  console.log("All tests passed ✓");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/resources/extensions/kata/types.ts

@@ -0,0 +1,159 @@
+// Kata Extension — Core Type Definitions
+// Types consumed by state derivation, file parsing, and status display.
+// Pure interfaces — no logic, no runtime dependencies.
+
+// ─── Enums & Literal Unions ────────────────────────────────────────────────
+
+export type RiskLevel = 'low' | 'medium' | 'high';
+export type Phase = 'pre-planning' | 'discussing' | 'researching' | 'planning' | 'executing' | 'verifying' | 'summarizing' | 'advancing' | 'completing-milestone' | 'replanning-slice' | 'complete' | 'paused' | 'blocked';
+export type ContinueStatus = 'in_progress' | 'interrupted' | 'compacted';
+
+// ─── Roadmap (Milestone-level) ─────────────────────────────────────────────
+
+export interface RoadmapSliceEntry {
+  id: string;          // e.g. "S01"
+  title: string;       // e.g. "Types + File I/O + Git Operations"
+  risk: RiskLevel;
+  depends: string[];   // e.g. ["S01", "S02"]
+  done: boolean;
+  demo: string;        // the "After this:" sentence
+}
+
+export interface BoundaryMapEntry {
+  fromSlice: string;   // e.g. "S01"
+  toSlice: string;     // e.g. "S02" or "terminal"
+  produces: string;    // raw text block of what this slice produces
+  consumes: string;    // raw text block of what it consumes (or "nothing")
+}
+
+export interface Roadmap {
+  title: string;       // e.g. "M001: Kata Extension — Hierarchical Planning with Auto Mode"
+  vision: string;
+  successCriteria: string[];
+  slices: RoadmapSliceEntry[];
+  boundaryMap: BoundaryMapEntry[];
+}
+
+// ─── Slice Plan ────────────────────────────────────────────────────────────
+
+export interface TaskPlanEntry {
+  id: string;          // e.g. "T01"
+  title: string;       // e.g. "Core Type Definitions"
+  description: string;
+  done: boolean;
+  estimate: string;    // e.g. "30m", "2h" — informational only
+  files?: string[];    // e.g. ["types.ts", "files.ts"] — extracted from "- Files:" subline
+  verify?: string;     // e.g. "run tests" — extracted from "- Verify:" subline
+}
+
+export interface SlicePlan {
+  id: string;          // e.g. "S01"
+  title: string;       // from the H1
+  goal: string;
+  demo: string;
+  mustHaves: string[]; // top-level must-have bullet points
+  tasks: TaskPlanEntry[];
+  filesLikelyTouched: string[];
+}
+
+// ─── Summary (Task & Slice level) ──────────────────────────────────────────
+
+export interface SummaryRequires {
+  slice: string;
+  provides: string;
+}
+
+export interface SummaryFrontmatter {
+  id: string;
+  parent: string;
+  milestone: string;
+  provides: string[];
+  requires: SummaryRequires[];
+  affects: string[];
+  key_files: string[];
+  key_decisions: string[];
+  patterns_established: string[];
+  drill_down_paths: string[];
+  observability_surfaces: string[];
+  duration: string;
+  verification_result: string;
+  completed_at: string;
+  blocker_discovered: boolean;
+}
+
+export interface FileModified {
+  path: string;
+  description: string;
+}
+
+export interface Summary {
+  frontmatter: SummaryFrontmatter;
+  title: string;
+  oneLiner: string;
+  whatHappened: string;
+  deviations: string;
+  filesModified: FileModified[];
+}
+
+// ─── Continue-Here ─────────────────────────────────────────────────────────
+
+export interface ContinueFrontmatter {
+  milestone: string;
+  slice: string;
+  task: string;
+  step: number;
+  totalSteps: number;
+  status: ContinueStatus;
+  savedAt: string;
+}
+
+export interface Continue {
+  frontmatter: ContinueFrontmatter;
+  completedWork: string;
+  remainingWork: string;
+  decisions: string;
+  context: string;
+  nextAction: string;
+}
+
+// ─── Kata State (Derived Dashboard) ────────────────────────────────────────
+
+export interface ActiveRef {
+  id: string;
+  title: string;
+}
+
+export interface MilestoneRegistryEntry {
+  id: string;
+  title: string;
+  status: 'complete' | 'active' | 'pending';
+  /** Milestone IDs that must be complete before this milestone becomes active. Populated from CONTEXT.md YAML frontmatter. */
+  dependsOn?: string[];
+}
+
+export interface RequirementCounts {
+  active: number;
+  validated: number;
+  deferred: number;
+  outOfScope: number;
+  blocked: number;
+  total: number;
+}
+
+export interface KataState {
+  activeMilestone: ActiveRef | null;
+  activeSlice: ActiveRef | null;
+  activeTask: ActiveRef | null;
+  phase: Phase;
+  recentDecisions: string[];
+  blockers: string[];
+  nextAction: string;
+  activeBranch?: string;
+  registry: MilestoneRegistryEntry[];
+  requirements?: RequirementCounts;
+  progress?: {
+    milestones: { done: number; total: number };
+    slices?: { done: number; total: number };
+    tasks?: { done: number; total: number };
+  };
+}

package/src/resources/extensions/kata/unit-runtime.ts

@@ -0,0 +1,163 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import {
+  kataRoot,
+  relSliceFile,
+  relTaskFile,
+  resolveSliceFile,
+  resolveTaskFile,
+} from "./paths.ts";
+import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.ts";
+
+export type UnitRuntimePhase =
+  | "dispatched"
+  | "wrapup-warning-sent"
+  | "timeout"
+  | "recovered"
+  | "finalized"
+  | "paused"
+  | "skipped";
+
+export interface ExecuteTaskRecoveryStatus {
+  planPath: string;
+  summaryPath: string;
+  summaryExists: boolean;
+  taskChecked: boolean;
+  nextActionAdvanced: boolean;
+  mustHaveCount: number;
+  mustHavesMentionedInSummary: number;
+}
+
+export interface AutoUnitRuntimeRecord {
+  version: 1;
+  unitType: string;
+  unitId: string;
+  startedAt: number;
+  updatedAt: number;
+  phase: UnitRuntimePhase;
+  wrapupWarningSent: boolean;
+  timeoutAt: number | null;
+  lastProgressAt: number;
+  progressCount: number;
+  lastProgressKind: string;
+  recovery?: ExecuteTaskRecoveryStatus;
+  recoveryAttempts?: number;
+  lastRecoveryReason?: "idle" | "hard";
+}
+
+function runtimeDir(basePath: string): string {
+  return join(kataRoot(basePath), "runtime", "units");
+}
+
+function runtimePath(basePath: string, unitType: string, unitId: string): string {
+  return join(runtimeDir(basePath), `${unitType}-${unitId.replace(/[\/]/g, "-")}.json`);
+}
+
+export function writeUnitRuntimeRecord(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  startedAt: number,
+  updates: Partial<AutoUnitRuntimeRecord> = {},
+): AutoUnitRuntimeRecord {
+  const dir = runtimeDir(basePath);
+  mkdirSync(dir, { recursive: true });
+  const path = runtimePath(basePath, unitType, unitId);
+  const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+  const next: AutoUnitRuntimeRecord = {
+    version: 1,
+    unitType,
+    unitId,
+    startedAt,
+    updatedAt: Date.now(),
+    phase: updates.phase ?? prev?.phase ?? "dispatched",
+    wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
+    timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
+    lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
+    progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
+    lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
+    recovery: updates.recovery ?? prev?.recovery,
+    recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
+    lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+  };
+  writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+  return next;
+}
+
+export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): AutoUnitRuntimeRecord | null {
+  const path = runtimePath(basePath, unitType, unitId);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as AutoUnitRuntimeRecord;
+  } catch {
+    return null;
+  }
+}
+
+export function clearUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): void {
+  const path = runtimePath(basePath, unitType, unitId);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+export async function inspectExecuteTaskDurability(
+  basePath: string,
+  unitId: string,
+): Promise<ExecuteTaskRecoveryStatus | null> {
+  const [mid, sid, tid] = unitId.split("/");
+  if (!mid || !sid || !tid) return null;
+
+  const planAbs = resolveSliceFile(basePath, mid, sid, "PLAN");
+  const summaryAbs = resolveTaskFile(basePath, mid, sid, tid, "SUMMARY");
+  const stateAbs = join(kataRoot(basePath), "STATE.md");
+
+  const planPath = relSliceFile(basePath, mid, sid, "PLAN");
+  const summaryPath = relTaskFile(basePath, mid, sid, tid, "SUMMARY");
+
+  const planContent = planAbs ? await loadFile(planAbs) : null;
+  const stateContent = existsSync(stateAbs) ? readFileSync(stateAbs, "utf-8") : "";
+  const summaryExists = !!(summaryAbs && existsSync(summaryAbs));
+
+  const escapedTid = tid.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const taskChecked = !!planContent && new RegExp(`^- \\[[xX]\\] \\*\\*${escapedTid}:`, "m").test(planContent);
+  const nextActionAdvanced = !new RegExp(`Execute ${tid}\\b`).test(stateContent);
+
+  // Must-have coverage: load task plan and count mentions in summary
+  let mustHaveCount = 0;
+  let mustHavesMentionedInSummary = 0;
+
+  const taskPlanAbs = resolveTaskFile(basePath, mid, sid, tid, "PLAN");
+  if (taskPlanAbs) {
+    const taskPlanContent = await loadFile(taskPlanAbs);
+    if (taskPlanContent) {
+      const mustHaves = parseTaskPlanMustHaves(taskPlanContent);
+      mustHaveCount = mustHaves.length;
+      if (mustHaveCount > 0 && summaryExists && summaryAbs) {
+        const summaryContent = await loadFile(summaryAbs);
+        if (summaryContent) {
+          mustHavesMentionedInSummary = countMustHavesMentionedInSummary(mustHaves, summaryContent);
+        }
+      }
+    }
+  }
+
+  return {
+    planPath,
+    summaryPath,
+    summaryExists,
+    taskChecked,
+    nextActionAdvanced,
+    mustHaveCount,
+    mustHavesMentionedInSummary,
+  };
+}
+
+export function formatExecuteTaskRecoveryStatus(status: ExecuteTaskRecoveryStatus): string {
+  const missing = [] as string[];
+  if (!status.summaryExists) missing.push(`summary missing (${status.summaryPath})`);
+  if (!status.taskChecked) missing.push(`task checkbox unchecked in ${status.planPath}`);
+  if (!status.nextActionAdvanced) missing.push("state next action still points at the timed-out task");
+  if (status.mustHaveCount > 0 && status.mustHavesMentionedInSummary < status.mustHaveCount) {
+    missing.push(`must-have gap: ${status.mustHavesMentionedInSummary} of ${status.mustHaveCount} must-haves addressed in summary`);
+  }
+  return missing.length > 0 ? missing.join("; ") : "all durable task artifacts present";
+}