work-kit-cli 0.3.0 → 0.4.0

package/cli/src/commands/learn.test.ts

@@ -0,0 +1,217 @@
+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 { learnCommand } from "./learn.js";
+import { extractCommand } from "./extract.js";
+import { KNOWLEDGE_DIR, AUTO_BLOCK_START, AUTO_BLOCK_END } from "../utils/knowledge.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `work-kit-test-${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 = [];
+});
+
+function setupSession(tmp: string) {
+  initCommand({
+    mode: "full",
+    description: "Test feature",
+    worktreeRoot: tmp,
+  });
+}
+
+describe("learnCommand", () => {
+  it("rejects invalid type", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+    const r = learnCommand({ type: "garbage", text: "x", worktreeRoot: tmp });
+    assert.equal(r.action, "error");
+  });
+
+  it("rejects empty text", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+    const r = learnCommand({ type: "lesson", text: "   ", worktreeRoot: tmp });
+    assert.equal(r.action, "error");
+  });
+
+  it("appends a lesson and creates auto-block markers", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    const r = learnCommand({
+      type: "lesson",
+      text: "Test fixtures must be reset between Playwright suites.",
+      worktreeRoot: tmp,
+    });
+
+    assert.equal(r.action, "learned");
+    assert.equal(r.file, "lessons.md");
+
+    const lessonsPath = path.join(tmp, KNOWLEDGE_DIR, "lessons.md");
+    assert.ok(fs.existsSync(lessonsPath));
+    const content = fs.readFileSync(lessonsPath, "utf-8");
+    assert.ok(content.includes(AUTO_BLOCK_START));
+    assert.ok(content.includes(AUTO_BLOCK_END));
+    assert.ok(content.includes("Test fixtures must be reset"));
+  });
+
+  it("routes each type to its own file", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    learnCommand({ type: "lesson", text: "L", worktreeRoot: tmp });
+    learnCommand({ type: "convention", text: "C", worktreeRoot: tmp });
+    learnCommand({ type: "risk", text: "R", worktreeRoot: tmp });
+    learnCommand({ type: "workflow", text: "W", worktreeRoot: tmp });
+
+    const dir = path.join(tmp, KNOWLEDGE_DIR);
+    assert.ok(fs.readFileSync(path.join(dir, "lessons.md"), "utf-8").includes("L"));
+    assert.ok(fs.readFileSync(path.join(dir, "conventions.md"), "utf-8").includes("C"));
+    assert.ok(fs.readFileSync(path.join(dir, "risks.md"), "utf-8").includes("R"));
+    assert.ok(fs.readFileSync(path.join(dir, "workflow.md"), "utf-8").includes("W"));
+  });
+
+  it("redacts secrets in text before writing", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    const r = learnCommand({
+      type: "lesson",
+      text: "API key is sk-abc123def456ghi789jkl012mno345 leaked here",
+      worktreeRoot: tmp,
+    });
+
+    assert.equal(r.action, "learned");
+    assert.equal(r.redacted, true);
+    assert.ok((r.redactedKinds ?? []).includes("openai-style"));
+
+    const content = fs.readFileSync(
+      path.join(tmp, KNOWLEDGE_DIR, "lessons.md"),
+      "utf-8"
+    );
+    assert.ok(content.includes("[REDACTED]"));
+    assert.ok(!content.includes("sk-abc123def456ghi789"));
+  });
+
+  it("is idempotent on identical entries (returns duplicate)", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    const first = learnCommand({ type: "risk", text: "Same text", worktreeRoot: tmp });
+    const second = learnCommand({ type: "risk", text: "Same text", worktreeRoot: tmp });
+
+    assert.equal(first.action, "learned");
+    assert.equal(second.action, "duplicate");
+
+    const content = fs.readFileSync(
+      path.join(tmp, KNOWLEDGE_DIR, "risks.md"),
+      "utf-8"
+    );
+    // Only one entry should exist
+    const matches = content.match(/Same text/g) ?? [];
+    assert.equal(matches.length, 1);
+  });
+
+  it("auto-fills phase and step from tracker.json", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    learnCommand({
+      type: "lesson",
+      text: "Phase auto-fill check",
+      worktreeRoot: tmp,
+    });
+
+    const content = fs.readFileSync(
+      path.join(tmp, KNOWLEDGE_DIR, "lessons.md"),
+      "utf-8"
+    );
+    // Init starts at plan/clarify
+    assert.ok(content.includes("plan/clarify"));
+  });
+
+  it("extracts typed bullets from state.md ## Observations", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    // Inject typed bullets into the existing ## Observations section
+    const stateMdPath = path.join(tmp, ".work-kit", "state.md");
+    const original = fs.readFileSync(stateMdPath, "utf-8");
+    const injected = original.replace(
+      "\n## Deviations",
+      "\n- [risk] foo.ts is fragile\n- [convention] All inputs validated via Zod\n- [workflow:test/e2e] e2e step needs server\n- [lesson] We discovered something useful\n\n## Deviations"
+    );
+    fs.writeFileSync(stateMdPath, injected);
+
+    const r = extractCommand({ worktreeRoot: tmp });
+    assert.equal(r.action, "extracted");
+    // 4 typed observation bullets, all should route
+    assert.equal(r.byType.risk, 1);
+    assert.equal(r.byType.convention, 1);
+    assert.equal(r.byType.workflow, 1, "workflow:test/e2e bullet should be routed (regression: digit in step name)");
+    assert.equal(r.byType.lesson, 1);
+
+    const workflowMd = fs.readFileSync(path.join(tmp, KNOWLEDGE_DIR, "workflow.md"), "utf-8");
+    assert.ok(workflowMd.includes("e2e step needs server"));
+  });
+
+  it("extract is idempotent (re-run produces only duplicates)", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    const stateMdPath = path.join(tmp, ".work-kit", "state.md");
+    const original = fs.readFileSync(stateMdPath, "utf-8");
+    fs.writeFileSync(
+      stateMdPath,
+      original.replace("\n## Deviations", "\n- [risk] one\n- [risk] two\n\n## Deviations")
+    );
+
+    const first = extractCommand({ worktreeRoot: tmp });
+    const second = extractCommand({ worktreeRoot: tmp });
+
+    assert.equal(first.written, 2);
+    assert.equal(first.duplicates, 0);
+    assert.equal(second.written, 0);
+    assert.equal(second.duplicates, 2);
+  });
+
+  it("does not contaminate the Manual section", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    setupSession(tmp);
+
+    learnCommand({ type: "lesson", text: "Auto only", worktreeRoot: tmp });
+
+    const content = fs.readFileSync(
+      path.join(tmp, KNOWLEDGE_DIR, "lessons.md"),
+      "utf-8"
+    );
+    // Find the Manual section and ensure the entry isn't in it
+    const manualIdx = content.indexOf("## Manual");
+    assert.ok(manualIdx > -1);
+    const manualSection = content.slice(manualIdx);
+    assert.ok(!manualSection.includes("Auto only"));
+  });
+});

package/cli/src/commands/learn.ts

@@ -0,0 +1,104 @@
+import { findWorktreeRoot, readState, resolveMainRepoRoot, stateExists, gitHeadSha } from "../state/store.js";
+import {
+  appendAutoEntry,
+  ensureKnowledgeDir,
+  fileForType,
+  isKnowledgeType,
+  redact,
+  type KnowledgeEntry,
+  type KnowledgeType,
+} from "../utils/knowledge.js";
+import { skillFilePath } from "../config/workflow.js";
+import type { PhaseName } from "../state/schema.js";
+
+export interface LearnOptions {
+  type: string;
+  text: string;
+  scope?: string;
+  phase?: string;
+  step?: string;
+  source?: string;
+  worktreeRoot?: string;
+  /** When true, suppress the one-time commit warning. Used by extract. */
+  quiet?: boolean;
+}
+
+export interface LearnResult {
+  action: "learned" | "duplicate" | "error";
+  type?: KnowledgeType;
+  file?: string;
+  redacted?: boolean;
+  redactedKinds?: string[];
+  message?: string;
+}
+
+export function learnCommand(opts: LearnOptions): LearnResult {
+  if (!opts.type || !isKnowledgeType(opts.type)) {
+    return {
+      action: "error",
+      message: `Invalid --type "${opts.type}". Must be one of: lesson, convention, risk, workflow.`,
+    };
+  }
+  if (!opts.text || opts.text.trim().length === 0) {
+    return { action: "error", message: "--text is required and cannot be empty." };
+  }
+
+  const type = opts.type as KnowledgeType;
+
+  // Try to locate a session for auto-fill. Falls back to manual --phase/--step.
+  const root = opts.worktreeRoot || findWorktreeRoot();
+  let sessionSlug: string | undefined;
+  let phase: string | undefined = opts.phase;
+  let step: string | undefined = opts.step;
+  let mainRepoRoot: string | undefined;
+  let skillPath: string | undefined;
+
+  if (root && stateExists(root)) {
+    const state = readState(root);
+    sessionSlug = state.slug;
+    mainRepoRoot = state.metadata?.mainRepoRoot ?? resolveMainRepoRoot(root);
+    if (!phase) phase = state.currentPhase ?? undefined;
+    if (!step) step = state.currentStep ?? undefined;
+    if (phase && step) {
+      skillPath = skillFilePath(phase as PhaseName, step);
+    }
+  }
+
+  if (!mainRepoRoot) {
+    // No session — caller must be in a git repo we can resolve
+    mainRepoRoot = resolveMainRepoRoot(process.cwd());
+    if (!mainRepoRoot) {
+      return {
+        action: "error",
+        message: "No work-kit session found and not inside a git repo. Run from a project directory or provide --worktree-root.",
+      };
+    }
+  }
+
+  const { text, redacted, matches } = redact(opts.text);
+
+  ensureKnowledgeDir(mainRepoRoot);
+
+  const entry: KnowledgeEntry = {
+    ts: new Date().toISOString(),
+    sessionSlug,
+    phase,
+    step,
+    skillPath,
+    gitSha: gitHeadSha(mainRepoRoot),
+    source: opts.source ?? "explicit-cli",
+    text,
+    scope: opts.scope,
+  };
+
+  const file = fileForType(type);
+  const wrote = appendAutoEntry(mainRepoRoot, file, entry);
+
+  return {
+    action: wrote ? "learned" : "duplicate",
+    type,
+    file,
+    redacted,
+    redactedKinds: matches,
+  };
+}

package/cli/src/commands/next.ts

@@ -4,6 +4,7 @@ import { validatePhasePrerequisites } from "../state/validators.js";
 import { buildAgentPrompt } from "../context/prompt-builder.js";
 import { getParallelGroup } from "../workflow/parallel.js";
 import { skillFilePath } from "../config/workflow.js";
+import { resolveModel } from "../config/model-routing.js";
 import { CLI_BINARY } from "../config/constants.js";
 
 import type { Action, PhaseName, WorkKitState } from "../state/schema.js";
@@ -109,27 +110,27 @@ function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, s
         const sState = state.phases[phase].steps[s];
         return sState && sState.status !== "skipped" && sState.status !== "completed";
       })
-      .map((s) => ({
+      .map((s) => withModel({
         phase,
         step: s,
         skillFile: skillFilePath(phase, s),
         agentPrompt: buildAgentPrompt(root, state, phase, s, stateMd),
         outputFile: `.work-kit/${phase}-${s}.md`,
-      }));
+      }, state));
 
     // If all parallel members were filtered out, fall through to single agent
     if (agents.length === 0) {
       // Skip to thenSequential if it exists, otherwise nothing to do
       if (parallelGroup.thenSequential) {
         const seqStep = parallelGroup.thenSequential;
-        return {
+        return withModelAction({
           action: "spawn_agent",
           phase,
           step: seqStep,
           skillFile: skillFilePath(phase, seqStep),
           agentPrompt: buildAgentPrompt(root, state, phase, seqStep, stateMd),
           onComplete: `${CLI_BINARY} complete ${phase}/${seqStep}`,
-        };
+        }, state);
       }
       return { action: "error", message: `No active steps in parallel group for ${phase}` };
     }
@@ -137,14 +138,14 @@ function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, s
     // If only 1 agent remains, run as single agent (no need for parallel)
     if (agents.length === 1 && !parallelGroup.thenSequential) {
       const agent = agents[0];
-      return {
+      return withModelAction({
         action: "spawn_agent",
         phase: agent.phase,
         step: agent.step,
         skillFile: agent.skillFile,
         agentPrompt: agent.agentPrompt,
         onComplete: `${CLI_BINARY} complete ${agent.phase}/${agent.step}`,
-      };
+      }, state);
     }
 
     for (const agent of agents) {
@@ -153,12 +154,12 @@ function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, s
     }
 
     const thenSequential = parallelGroup.thenSequential
-      ? {
+      ? withModel({
           phase,
           step: parallelGroup.thenSequential,
           skillFile: skillFilePath(phase, parallelGroup.thenSequential),
           agentPrompt: buildAgentPrompt(root, state, phase, parallelGroup.thenSequential, stateMd),
-        }
+        }, state)
       : undefined;
 
     writeState(root, state);
@@ -174,12 +175,31 @@ function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, s
   const skill = skillFilePath(phase, step);
   const prompt = buildAgentPrompt(root, state, phase, step, stateMd);
 
-  return {
+  return withModelAction({
     action: "spawn_agent",
     phase,
     step,
     skillFile: skill,
     agentPrompt: prompt,
     onComplete: `${CLI_BINARY} complete ${phase}/${step}`,
-  };
+  }, state);
+}
+
+/**
+ * Attach the resolved model tier to an AgentSpec. Omits the field entirely
+ * when resolveModel returns undefined (policy "inherit" or hard-default miss),
+ * keeping the action JSON compatible with skills that haven't yet been updated
+ * to forward a model parameter.
+ */
+function withModel<T extends { phase: PhaseName; step: string }>(spec: T, state: WorkKitState): T & { model?: ReturnType<typeof resolveModel> } {
+  const model = resolveModel(state, spec.phase, spec.step);
+  return model ? { ...spec, model } : spec;
+}
+
+function withModelAction(
+  action: Extract<Action, { action: "spawn_agent" }>,
+  state: WorkKitState
+): Extract<Action, { action: "spawn_agent" }> {
+  const model = resolveModel(state, action.phase, action.step);
+  return model ? { ...action, model } : action;
 }

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

@@ -56,7 +56,7 @@ describe("pause / resume", () => {
     initCommand({ mode: "full", description: "Resume test", worktreeRoot: tmp });
     pauseCommand(undefined, tmp);
 
-    const result = resumeCommand(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"));
@@ -69,7 +69,7 @@ describe("pause / resume", () => {
     tmpDirs.push(tmp);
     initCommand({ mode: "full", description: "Already running", worktreeRoot: tmp });
 
-    const result = resumeCommand(tmp);
+    const result = resumeCommand({ worktreeRoot: tmp });
     assert.equal(result.action, "resumed");
   });
 

package/cli/src/commands/resume.ts

@@ -1,14 +1,52 @@
-import { readState, writeState, findWorktreeRoot } from "../state/store.js";
+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 type { Action } from "../state/schema.js";
+import { discoverWorktrees } from "../observer/data.js";
+import type { Action, ResumableSessionSummary } from "../state/schema.js";
 
-export function resumeCommand(worktreeRoot?: string): Action {
-  const root = worktreeRoot || findWorktreeRoot();
-  if (!root) {
-    return { action: "error", message: "No work-kit state found." };
+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") {
@@ -20,6 +58,7 @@ export function resumeCommand(worktreeRoot?: string): Action {
       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") {
@@ -31,8 +70,57 @@ export function resumeCommand(worktreeRoot?: string): Action {
 
   return {
     action: "resumed",
-    message: `Resumed ${state.slug}. Run \`${CLI_BINARY} next\` to continue.`,
+    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,
   };
 }