work-kit-cli 0.2.8 → 0.4.0

package/cli/src/commands/observe.ts

@@ -1,5 +1,4 @@
 import * as path from "node:path";
-import { execFileSync } from "node:child_process";
 import {
   renderDashboard,
   enterAlternateScreen,
@@ -7,27 +6,23 @@ import {
   moveCursorHome,
   renderTooSmall,
 } from "../observer/renderer.js";
-import { collectDashboardData } from "../observer/data.js";
+import { collectDashboardData, discoverWorkKitProjects } from "../observer/data.js";
 import { startWatching } from "../observer/watcher.js";
+import { gitMainRepoRoot } from "../state/store.js";
 
-function findMainRepoRoot(startDir: string): string {
-  // Find the git toplevel
-  try {
-    const result = execFileSync("git", ["rev-parse", "--show-toplevel"], {
-      cwd: startDir,
-      encoding: "utf-8",
-      timeout: 5000,
-    });
-    return result.trim();
-  } catch {
-    return startDir;
-  }
-}
+export async function observeCommand(opts: { mainRepo?: string; all?: boolean }): Promise<void> {
+  const cwdRoot = () => gitMainRepoRoot(process.cwd()) ?? process.cwd();
 
-export async function observeCommand(opts: { mainRepo?: string }): Promise<void> {
-  const mainRepoRoot = opts.mainRepo
-    ? path.resolve(opts.mainRepo)
-    : findMainRepoRoot(process.cwd());
+  let mainRepoRoots: string[];
+  if (opts.all) {
+    mainRepoRoots = discoverWorkKitProjects();
+    if (mainRepoRoots.length === 0) {
+      // Fallback to current repo so the dashboard still has something to show
+      mainRepoRoots = [cwdRoot()];
+    }
+  } else {
+    mainRepoRoots = [opts.mainRepo ? path.resolve(opts.mainRepo) : cwdRoot()];
+  }
 
   let scrollOffset = 0;
   let tick = 0;
@@ -58,7 +53,7 @@ export async function observeCommand(opts: { mainRepo?: string }): Promise<void>
       return;
     }
 
-    const data = collectDashboardData(mainRepoRoot, watcher.getWorktrees());
+    const data = collectDashboardData(mainRepoRoots, watcher.getWorktrees());
     const frame = moveCursorHome() + renderDashboard(data, width, height, scrollOffset, tick);
     process.stdout.write(frame);
   }
@@ -78,7 +73,7 @@ export async function observeCommand(opts: { mainRepo?: string }): Promise<void>
 
   try {
     // Set up file watching (before initial render so worktrees are cached)
-    watcher = startWatching(mainRepoRoot, () => {
+    watcher = startWatching(mainRepoRoots, () => {
       render();
     });
 

package/cli/src/commands/pause-resume.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, afterEach } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+import { initCommand } from "./init.js";
+import { pauseCommand } from "./pause.js";
+import { resumeCommand } from "./resume.js";
+import { nextCommand } from "./next.js";
+import { bootstrapCommand } from "./bootstrap.js";
+import { completeCommand } from "./complete.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `work-kit-pause-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+let tmpDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  tmpDirs = [];
+});
+
+describe("pause / resume", () => {
+  it("pause flips status and records timestamp", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Pause test", worktreeRoot: tmp });
+
+    const result = pauseCommand("lunch", tmp);
+    assert.equal(result.action, "paused");
+
+    const tracker = JSON.parse(fs.readFileSync(path.join(tmp, ".work-kit", "tracker.json"), "utf-8"));
+    assert.equal(tracker.status, "paused");
+    assert.ok(tracker.pausedAt);
+  });
+
+  it("pause is idempotent — second pause errors", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Double pause", worktreeRoot: tmp });
+
+    pauseCommand(undefined, tmp);
+    const result = pauseCommand(undefined, tmp);
+    assert.equal(result.action, "error");
+  });
+
+  it("resume flips status back and clears pausedAt", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Resume test", worktreeRoot: tmp });
+    pauseCommand(undefined, tmp);
+
+    const result = resumeCommand({ worktreeRoot: tmp });
+    assert.equal(result.action, "resumed");
+
+    const tracker = JSON.parse(fs.readFileSync(path.join(tmp, ".work-kit", "tracker.json"), "utf-8"));
+    assert.equal(tracker.status, "in-progress");
+    assert.equal(tracker.pausedAt, undefined);
+  });
+
+  it("resume on already in-progress is idempotent", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Already running", worktreeRoot: tmp });
+
+    const result = resumeCommand({ worktreeRoot: tmp });
+    assert.equal(result.action, "resumed");
+  });
+
+  it("next refuses to advance a paused session", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Paused next", worktreeRoot: tmp });
+    pauseCommand(undefined, tmp);
+
+    const result = nextCommand(tmp);
+    assert.equal(result.action, "error");
+    if (result.action === "error") {
+      assert.ok(result.message.includes("paused"));
+    }
+  });
+
+  it("bootstrap --auto-resume flips paused → in-progress", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Auto resume", worktreeRoot: tmp });
+    pauseCommand(undefined, tmp);
+
+    const result = bootstrapCommand(tmp, { autoResume: true });
+    assert.equal(result.status, "in-progress");
+    assert.equal(result.resumed, true);
+  });
+
+  it("bootstrap without --auto-resume leaves paused state alone", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "No auto", worktreeRoot: tmp });
+    pauseCommand(undefined, tmp);
+
+    const result = bootstrapCommand(tmp);
+    assert.equal(result.status, "paused");
+    assert.notEqual(result.resumed, true);
+  });
+});
+
+describe("complete outcome validation", () => {
+  it("rejects invalid outcomes", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Outcome test", worktreeRoot: tmp });
+
+    const result = completeCommand("plan/clarify", "totally-bogus", tmp);
+    assert.equal(result.action, "error");
+    if (result.action === "error") {
+      assert.ok(result.message.includes("Invalid outcome"));
+    }
+  });
+
+  it("accepts known outcomes", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Outcome ok", worktreeRoot: tmp });
+
+    const result = completeCommand("plan/clarify", "done", tmp);
+    assert.notEqual(result.action, "error");
+  });
+
+  it("accepts undefined outcome", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "No outcome", worktreeRoot: tmp });
+
+    const result = completeCommand("plan/clarify", undefined, tmp);
+    assert.notEqual(result.action, "error");
+  });
+});

package/cli/src/commands/pause.ts

@@ -0,0 +1,34 @@
+import { readState, writeState, findWorktreeRoot } from "../state/store.js";
+import type { Action } from "../state/schema.js";
+
+export function pauseCommand(reason?: string, worktreeRoot?: string): Action {
+  const root = worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    return { action: "error", message: "No work-kit state found." };
+  }
+
+  const state = readState(root);
+
+  if (state.status === "completed") {
+    return { action: "error", message: `${state.slug} is already completed; nothing to pause.` };
+  }
+  if (state.status === "paused") {
+    return { action: "error", message: `${state.slug} is already paused (since ${state.pausedAt}).` };
+  }
+  if (state.status === "failed") {
+    return { action: "error", message: `${state.slug} is in failed state; cannot pause.` };
+  }
+
+  state.status = "paused";
+  state.pausedAt = new Date().toISOString();
+  writeState(root, state);
+
+  const where = state.currentPhase
+    ? ` at ${state.currentPhase}${state.currentStep ? "/" + state.currentStep : ""}`
+    : "";
+
+  return {
+    action: "paused",
+    message: `Paused ${state.slug}${where}.${reason ? ` Reason: ${reason}` : ""} Run \`work-kit resume\` to continue.`,
+  };
+}

package/cli/src/commands/report.ts

@@ -0,0 +1,217 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findWorktreeRoot, resolveMainRepoRoot } from "../state/store.js";
+import { TRACKER_DIR, ARCHIVE_DIR, INDEX_FILE } from "../config/constants.js";
+import {
+  PHASE_NAMES,
+  MODE_FULL,
+  MODE_AUTO,
+  type PhaseName,
+  type Classification,
+  type WorkKitState,
+} from "../state/schema.js";
+import { readJsonFile } from "../utils/json.js";
+import { durationMs, formatDurationMs } from "../utils/time.js";
+import { bold, cyan, dim, green, yellow } from "../utils/colors.js";
+
+const RECENT_LIMIT = 10;
+
+export interface PhaseStats {
+  runs: number;
+  avgDurationMs: number;
+  totalDurationMs: number;
+}
+
+export interface RecentEntry {
+  slug: string;
+  completedAt: string;
+  classification?: Classification;
+  mode: typeof MODE_FULL | typeof MODE_AUTO;
+  durationMs?: number;
+}
+
+export interface ReportData {
+  totalCompleted: number;
+  byClassification: Partial<Record<Classification | "unclassified", number>>;
+  byMode: Partial<Record<typeof MODE_FULL | typeof MODE_AUTO, number>>;
+  avgDurationMs: number;
+  totalLoopbacks: number;
+  loopbackRate: number;
+  perPhase: Record<PhaseName, PhaseStats>;
+  recent: RecentEntry[];
+  source: { mainRepoRoot: string; trackerDir: string };
+}
+
+function emptyPhaseStats(): PhaseStats {
+  return { runs: 0, avgDurationMs: 0, totalDurationMs: 0 };
+}
+
+export function collectReport(mainRepoRoot: string): ReportData {
+  const trackerDir = path.join(mainRepoRoot, TRACKER_DIR);
+  const archiveDir = path.join(trackerDir, ARCHIVE_DIR);
+
+  const data: ReportData = {
+    totalCompleted: 0,
+    byClassification: {},
+    byMode: {},
+    avgDurationMs: 0,
+    totalLoopbacks: 0,
+    loopbackRate: 0,
+    perPhase: PHASE_NAMES.reduce((acc, p) => {
+      acc[p] = emptyPhaseStats();
+      return acc;
+    }, {} as Record<PhaseName, PhaseStats>),
+    recent: [],
+    source: { mainRepoRoot, trackerDir },
+  };
+
+  let folders: string[];
+  try {
+    folders = fs.readdirSync(archiveDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+  } catch {
+    return data;
+  }
+
+  let totalRunDurationMs = 0;
+  let runsWithDuration = 0;
+  // Bounded min-heap-by-completedAt would be ideal; for ≤10 entries
+  // a simple sorted insertion is cheaper than a full sort at the end.
+  const keepRecent = (entry: RecentEntry) => {
+    data.recent.push(entry);
+    data.recent.sort((a, b) => (a.completedAt < b.completedAt ? 1 : -1));
+    if (data.recent.length > RECENT_LIMIT) data.recent.length = RECENT_LIMIT;
+  };
+
+  for (const folder of folders) {
+    const state = readJsonFile<WorkKitState>(path.join(archiveDir, folder, "tracker.json"));
+    if (!state) continue;
+
+    data.totalCompleted++;
+
+    const cls = state.classification ?? "unclassified";
+    data.byClassification[cls] = (data.byClassification[cls] ?? 0) + 1;
+    data.byMode[state.mode] = (data.byMode[state.mode] ?? 0) + 1;
+    data.totalLoopbacks += state.loopbacks?.length ?? 0;
+
+    let runDuration = 0;
+    let lastEnd: string | undefined;
+    for (const phase of PHASE_NAMES) {
+      const ps = state.phases[phase];
+      if (!ps || ps.status !== "completed") continue;
+      const d = durationMs(ps.startedAt, ps.completedAt);
+      data.perPhase[phase].runs++;
+      data.perPhase[phase].totalDurationMs += d;
+      runDuration += d;
+      if (ps.completedAt && (!lastEnd || ps.completedAt > lastEnd)) lastEnd = ps.completedAt;
+    }
+
+    if (runDuration > 0) {
+      totalRunDurationMs += runDuration;
+      runsWithDuration++;
+    }
+
+    keepRecent({
+      slug: state.slug,
+      completedAt: lastEnd ?? state.started,
+      classification: state.classification,
+      mode: state.mode,
+      durationMs: runDuration > 0 ? runDuration : undefined,
+    });
+  }
+
+  for (const phase of PHASE_NAMES) {
+    const s = data.perPhase[phase];
+    s.avgDurationMs = s.runs > 0 ? Math.round(s.totalDurationMs / s.runs) : 0;
+  }
+  data.avgDurationMs = runsWithDuration > 0 ? Math.round(totalRunDurationMs / runsWithDuration) : 0;
+  data.loopbackRate = data.totalCompleted > 0 ? data.totalLoopbacks / data.totalCompleted : 0;
+
+  return data;
+}
+
+export interface ReportOptions {
+  json?: boolean;
+  worktreeRoot?: string;
+  repo?: string;
+}
+
+export function reportCommand(options: ReportOptions = {}): ReportData {
+  const mainRepoRoot = options.repo
+    ? path.resolve(options.repo)
+    : resolveMainRepoRoot(options.worktreeRoot || findWorktreeRoot() || process.cwd());
+
+  const data = collectReport(mainRepoRoot);
+
+  if (options.json) {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+    return data;
+  }
+
+  const out: string[] = [];
+  out.push("");
+  out.push(bold("  WORK-KIT REPORT"));
+  out.push(dim(`  ${data.source.trackerDir}`));
+  out.push("");
+
+  if (data.totalCompleted === 0) {
+    out.push(dim("  No completed work-kits found."));
+    out.push("");
+    process.stderr.write(out.join("\n") + "\n");
+    return data;
+  }
+
+  out.push(`  ${cyan("Completed")}    ${bold(String(data.totalCompleted))}`);
+  out.push(`  ${cyan("Avg run")}      ${formatDurationMs(data.avgDurationMs)}`);
+  out.push(`  ${cyan("Loopbacks")}    ${data.totalLoopbacks} ${dim(`(${(data.loopbackRate * 100).toFixed(0)}% rate)`)}`);
+  out.push("");
+
+  const byClassEntries = Object.entries(data.byClassification);
+  if (byClassEntries.length > 0) {
+    out.push(bold("  By Classification"));
+    for (const [cls, count] of byClassEntries.sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))) {
+      out.push(`    ${cls.padEnd(16)} ${count}`);
+    }
+    out.push("");
+  }
+
+  const byModeEntries = Object.entries(data.byMode);
+  if (byModeEntries.length > 0) {
+    out.push(bold("  By Mode"));
+    for (const [mode, count] of byModeEntries.sort((a, b) => (b[1] ?? 0) - (a[1] ?? 0))) {
+      out.push(`    ${mode.padEnd(16)} ${count}`);
+    }
+    out.push("");
+  }
+
+  out.push(bold("  Avg Phase Duration"));
+  for (const phase of PHASE_NAMES) {
+    const s = data.perPhase[phase];
+    if (s.runs === 0) continue;
+    out.push(`    ${phase.padEnd(10)} ${formatDurationMs(s.avgDurationMs).padStart(7)} ${dim(`(${s.runs} runs)`)}`);
+  }
+  out.push("");
+
+  if (data.recent.length > 0) {
+    out.push(bold("  Recent"));
+    for (const r of data.recent) {
+      const date = r.completedAt.split("T")[0];
+      const cls = r.classification ? dim(` [${r.classification}]`) : "";
+      const dur = r.durationMs ? dim(` ${formatDurationMs(r.durationMs)}`) : "";
+      out.push(`    ${green("✓")} ${date}  ${r.slug}${cls}${dur}`);
+    }
+    out.push("");
+  }
+
+  const indexPath = path.join(data.source.trackerDir, INDEX_FILE);
+  if (fs.existsSync(indexPath)) {
+    out.push(dim(`  Full index: ${indexPath}`));
+  } else {
+    out.push(yellow(`  Note: ${INDEX_FILE} not found.`));
+  }
+  out.push("");
+
+  process.stderr.write(out.join("\n") + "\n");
+  return data;
+}

package/cli/src/commands/resume.ts

@@ -0,0 +1,126 @@
+import * as fs from "node:fs";
+import { readState, writeState, findWorktreeRoot, statePath, gitMainRepoRoot } from "../state/store.js";
+import { unpause } from "../state/helpers.js";
+import { CLI_BINARY } from "../config/constants.js";
+import { discoverWorktrees } from "../observer/data.js";
+import type { Action, ResumableSessionSummary } from "../state/schema.js";
+
+export interface ResumeOptions {
+  worktreeRoot?: string;
+  slug?: string;
+}
+
+function collectResumableSessions(mainRepoRoot: string): ResumableSessionSummary[] {
+  const sessions: ResumableSessionSummary[] = [];
+  const now = Date.now();
+  for (const wt of discoverWorktrees(mainRepoRoot)) {
+    let state;
+    try {
+      state = readState(wt);
+    } catch {
+      continue;
+    }
+    if (state.status !== "paused" && state.status !== "in-progress") continue;
+
+    let mtimeMs = now;
+    try {
+      mtimeMs = fs.statSync(statePath(wt)).mtimeMs;
+    } catch {
+      // ignore — keep current time as fallback
+    }
+
+    sessions.push({
+      slug: state.slug,
+      branch: state.branch,
+      worktreeRoot: wt,
+      status: state.status,
+      pausedAt: state.pausedAt,
+      currentPhase: state.currentPhase,
+      currentStep: state.currentStep,
+      lastUpdatedAgoMs: now - mtimeMs,
+    });
+  }
+  // Sort: most recently updated first — fresh crashes are easy to spot at the top,
+  // and a still-running session in another terminal will have the smallest age.
+  sessions.sort((a, b) => a.lastUpdatedAgoMs - b.lastUpdatedAgoMs);
+  return sessions;
+}
+
+function resumeAt(root: string): Action {
+  const state = readState(root);
+
+  if (state.status === "completed") {
+    return { action: "error", message: `${state.slug} is already completed.` };
+  }
+  if (state.status === "in-progress") {
+    return {
+      action: "resumed",
+      message: `${state.slug} is already in progress. Run \`${CLI_BINARY} next\` to continue.`,
+      phase: state.currentPhase,
+      step: state.currentStep,
+      worktreeRoot: root,
+    };
+  }
+  if (state.status === "failed") {
+    return { action: "error", message: `${state.slug} is in failed state; cannot resume.` };
+  }
+
+  unpause(state);
+  writeState(root, state);
+
+  return {
+    action: "resumed",
+    message: `Resumed ${state.slug}. cd into ${root} and run \`${CLI_BINARY} next\` to continue.`,
+    phase: state.currentPhase,
+    step: state.currentStep,
+    worktreeRoot: root,
+  };
+}
+
+export function resumeCommand(options: ResumeOptions = {}): Action {
+  // 1. Explicit worktree path → resume there directly (legacy behavior)
+  if (options.worktreeRoot) {
+    return resumeAt(options.worktreeRoot);
+  }
+
+  // 2. Determine the main repo we're operating against. Works whether
+  // we're called from the main repo or from inside one of its worktrees.
+  const mainRepoRoot = gitMainRepoRoot(process.cwd());
+  if (!mainRepoRoot) {
+    // Non-git context: try the legacy cwd-walking lookup
+    const root = findWorktreeRoot();
+    if (!root) {
+      return { action: "error", message: "No work-kit state found and not inside a git repo." };
+    }
+    return resumeAt(root);
+  }
+
+  const sessions = collectResumableSessions(mainRepoRoot);
+
+  // 3. Slug selector → find matching session in this repo (paused OR in-progress)
+  if (options.slug) {
+    const match = sessions.find(s => s.slug === options.slug);
+    if (!match) {
+      return {
+        action: "error",
+        message: `No work-kit session with slug "${options.slug}" found in ${mainRepoRoot}.`,
+      };
+    }
+    return resumeAt(match.worktreeRoot);
+  }
+
+  // 4. No slug → list resumable sessions for the user to pick from
+  if (sessions.length === 0) {
+    return {
+      action: "error",
+      message: `No resumable work-kit sessions in ${mainRepoRoot}.`,
+      suggestion: `Start a new session with /full-kit or /auto-kit, or run \`${CLI_BINARY} observe\` to see active work.`,
+    };
+  }
+
+  return {
+    action: "select_session",
+    message: `Found ${sessions.length} resumable session${sessions.length === 1 ? "" : "s"}. Re-run with --slug <slug> to continue one.`,
+    sessions,
+  };
+}