import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { Readable } from "node:stream"; import { describe, expect, it, vi } from "vitest"; import { parseHookPayload, runCli } from "../src/cli/commands"; import * as courses from "../src/core/courses"; import * as db from "../src/core/db"; import { parseLesson } from "../src/core/models"; import { fetchSharedInput } from "../src/core/share-fetch"; import { VERSION } from "../src/version"; vi.mock("../src/core/share-fetch", async (importOriginal) => { const actual = await importOriginal(); return { ...actual, fetchSharedInput: vi.fn(actual.fetchSharedInput) }; }); // Drop a fake executable on a throwaway PATH dir so install can exercise the `claude` CLI branch. function fakeBin(name: string, script: string): string { const dir = mkdtempSync(join(tmpdir(), "dc-bin-")); writeFileSync(join(dir, name), script, { mode: 0o755 }); return dir; } const cleanClaudeSettings = (): string => { const p = join(process.env.HOME as string, ".claude", "settings.json"); mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, "{}"); return p; }; async function run(args: string[]): Promise<{ out: string; code: number | null }> { const lines: string[] = []; const logSpy = vi.spyOn(console, "log").mockImplementation((...a) => lines.push(a.join(" "))); const errSpy = vi.spyOn(console, "error").mockImplementation((...a) => lines.push(a.join(" "))); const errWriteSpy = vi.spyOn(process.stderr, "write").mockImplementation((s: any) => { lines.push(String(s)); return true; }); // Commander writes --help / --version to stdout; capture it too. const outWriteSpy = vi.spyOn(process.stdout, "write").mockImplementation((s: any) => { lines.push(String(s)); return true; }); let code: number | null = null; const exitSpy = vi.spyOn(process, "exit").mockImplementation(((c?: number) => { code = c ?? 0; throw new Error("__exit__"); }) as never); const argv = process.argv; process.argv = ["node", "bin", ...args]; try { await runCli(); } catch (e) { if ((e as Error).message !== "__exit__") throw e; } finally { process.argv = argv; logSpy.mockRestore(); errSpy.mockRestore(); errWriteSpy.mockRestore(); outWriteSpy.mockRestore(); exitSpy.mockRestore(); } return { out: lines.join("\n"), code }; } describe("cli", () => { it("welcome, version, unknown", async () => { expect((await run([])).out).toContain("devcoach"); expect((await run(["-v"])).out).toContain("devcoach"); expect((await run(["frobnicate"])).code).toBe(2); }); it("hooks: onboard-hook then lesson-ready", async () => { db.withConnection((c) => c.exec( "DELETE FROM knowledge; DELETE FROM knowledge_groups; DELETE FROM knowledge_group_names;", ), ); // No profile → emit a {decision:block} onboarding cue on stdout, exit 0 (not an error). const onb = await run(["onboard-hook"]); expect(onb.code).toBe(0); expect(onb.out).toContain('"decision":"block"'); expect(onb.out).toContain("complete_onboarding"); db.withConnection((c) => { db.upsertKnowledge(c, "python", 4); db.setSetting(c, "nudge_every", "0"); // disable interaction pacing for this test }); // Profile exists → silent: exit 0 with no decision payload. const silent = await run(["onboard-hook"]); expect(silent.code).toBe(0); expect(silent.out).not.toContain("decision"); // Lesson due → {decision:block} cue carrying the self-contained directive. const lr = await run(["lesson-ready"]); expect(lr.code).toBe(0); expect(lr.out).toContain('"decision":"block"'); expect(lr.out).toContain("log_lesson"); expect(lr.out).toContain("get_briefing"); expect(lr.out).toContain("notebook"); }); it("lesson-ready gates the notebook update to every 10 lessons", async () => { const seed = (n: number) => db.withConnection((c) => { c.exec("DELETE FROM lessons"); for (let i = 0; i < n; i++) { db.insertLesson( c, parseLesson({ id: `seed-${i}`, timestamp: "2026-01-01T00:00:00Z", topic_id: "python", categories: [], title: "T", level: "mid", summary: "s", }), ); } db.upsertKnowledge(c, "python", 4); db.setSetting(c, "nudge_every", "0"); // isolate the notebook-checkpoint gate }); seed(5); // next lesson is #6 → not a checkpoint → skip the notebook update expect((await run(["lesson-ready"])).out).toContain("Skip the notebook update this time"); seed(9); // next lesson is #10 → checkpoint → update the notebook const due = await run(["lesson-ready"]); expect(due.out).toContain("notebook checkpoint"); expect(due.out).toContain("references/calibration.md"); }); it("lesson-ready paces the cue by nudge_every (interaction counter)", async () => { db.withConnection((c) => { c.exec("DELETE FROM lessons; DELETE FROM nudge_state;"); db.upsertKnowledge(c, "python", 4); db.setSetting(c, "nudge_every", "2"); }); // 1st eligible stop → counter 1 < 2 → silent expect((await run(["lesson-ready"])).out).not.toContain("decision"); // 2nd → counter 2 ≥ 2 → cue expect((await run(["lesson-ready"])).out).toContain('"decision":"block"'); }); it("lesson-ready resets pacing on emission (no cue storm) and retries while pending", async () => { db.withConnection((c) => { c.exec("DELETE FROM lessons; DELETE FROM nudge_state; UPDATE cue_state SET pending = 0;"); db.upsertKnowledge(c, "python", 4); db.setSetting(c, "nudge_every", "2"); db.setSetting(c, "min_gap_minutes", "0"); db.setSetting(c, "max_per_day", "99"); }); expect((await run(["lesson-ready"])).out).not.toContain("decision"); const cue = await run(["lesson-ready"]); expect(cue.out).toContain('"decision":"block"'); // the new compact cue invokes the skill and offers the explicit no-op path expect(cue.out).toContain("devcoach` skill"); expect(cue.out).toContain("skip_lesson"); expect(cue.out).toContain("systemMessage"); // the stop right after a cue is silent again (reset-on-emission)… expect((await run(["lesson-ready"])).out).not.toContain("decision"); // …and the unresolved cue re-fires at the retry threshold expect((await run(["lesson-ready"])).out).toContain('"decision":"block"'); }); it("prompt-hook primes only when the next stop reaches the threshold", async () => { db.withConnection((c) => { c.exec("DELETE FROM lessons; DELETE FROM nudge_state; UPDATE cue_state SET pending = 0;"); db.upsertKnowledge(c, "python", 4); db.setSetting(c, "nudge_every", "2"); db.setSetting(c, "min_gap_minutes", "0"); db.setSetting(c, "max_per_day", "99"); }); // counter 0 → next stop is 1/2 → no prime expect((await run(["prompt-hook"])).out).not.toContain("additionalContext"); db.withConnection((c) => db.bumpNudge(c, "__nosession__", "session")); // counter 1 → next stop reaches 2/2 → prime, without bumping const primed = await run(["prompt-hook"]); expect(primed.out).toContain("additionalContext"); expect(primed.out).toContain("skip_lesson"); expect(db.withConnection((c) => db.peekNudge(c, "__nosession__", "session"))).toBe(1); }); it("doctor reports wiring, pacing, and a verdict — and always exits 0", async () => { cleanClaudeSettings(); db.withConnection((c) => { db.upsertKnowledge(c, "python", 4); db.setSetting(c, "nudge_every", "2"); }); const r = await run(["doctor"]); expect(r.code).toBeNull(); // never process.exit(≠0) expect(r.out).toContain("devcoach doctor"); expect(r.out).toContain("no devcoach hooks"); expect(r.out).toContain("onboarding complete"); expect(r.out).toContain("nudge_every=2"); expect(r.out).toContain("Verdict"); expect(r.out).not.toContain("Runtime:"); // only when a plugin/extension launcher started us process.env.DEVCOACH_LAUNCHER = "devcoach plugin · devcoach 9.9.9 · /tmp/runtime/9.9.9"; try { expect((await run(["doctor"])).out).toContain("Runtime: devcoach plugin · devcoach 9.9.9"); } finally { delete process.env.DEVCOACH_LAUNCHER; } writeFileSync(join(process.env.HOME as string, ".claude", "settings.json"), "{bad json"); expect((await run(["doctor"])).out).toContain("not valid JSON"); // plugin + settings.json hooks at once → double-count warning writeFileSync( join(process.env.HOME as string, ".claude", "settings.json"), JSON.stringify({ enabledPlugins: { "devcoach@marketplace": true }, hooks: { Stop: [{ hooks: [{ type: "command", command: "devcoach stop-hook" }] }] }, }), ); expect((await run(["doctor"])).out).toContain("registered TWICE"); // release + beta channel both enabled → each ships the hooks writeFileSync( join(process.env.HOME as string, ".claude", "settings.json"), JSON.stringify({ enabledPlugins: { "devcoach@ultimaphoenix": true, "devcoach@ultimaphoenix-beta": true }, }), ); const both = (await run(["doctor"])).out; expect(both).toContain("2 devcoach plugins enabled"); expect(both).toContain("devcoach@ultimaphoenix-beta"); }); // Claude Desktop starts devcoach from its own config with its own PATH, which it prints in its // log. The fixture is the real log of a failed start (2026-10-05): six `Failed to spawn process: // No such file or directory`, nothing from devcoach. Doctor must say which of the two causes. // On Linux both paths follow XDG_CONFIG_HOME, which CI runners set: pin it inside the sandbox // HOME for these tests so doctor and install never look at the runner's real config. const desktopPaths = (home: string) => { if (process.platform !== "darwin") process.env.XDG_CONFIG_HOME = join(home, ".config"); return process.platform === "darwin" ? { config: join( home, "Library", "Application Support", "Claude", "claude_desktop_config.json", ), log: join(home, "Library", "Logs", "Claude", "mcp-server-devcoach.log"), } : { config: join(home, ".config", "Claude", "claude_desktop_config.json"), log: join(home, ".config", "Claude", "logs", "mcp-server-devcoach.log"), }; }; const savedXdg = process.env.XDG_CONFIG_HOME; const restoreXdg = () => { if (savedXdg === undefined) delete process.env.XDG_CONFIG_HOME; else process.env.XDG_CONFIG_HOME = savedXdg; }; it.skipIf(process.platform === "win32")( "doctor checks Claude Desktop's entry on the PATH from Desktop's own log", async () => { cleanClaudeSettings(); const home = process.env.HOME as string; const { config, log } = desktopPaths(home); mkdirSync(dirname(config), { recursive: true }); mkdirSync(dirname(log), { recursive: true }); const hostBin = mkdtempSync(join(tmpdir(), "dc-desktop-path-")); const fixture = readFileSync( join(__dirname, "fixtures", "claude-desktop-mcp-devcoach.log"), "utf8", ).replace( /paths: \[[\s\S]*?\[length\]: \d+/, `paths: [\n '${hostBin}',\n [length]: 1`, ); writeFileSync(log, fixture); try { writeFileSync(config, JSON.stringify({ mcpServers: {} })); expect((await run(["doctor"])).out).toContain("not registered — add it with"); // yesterday's case: the bare name is on no directory of Desktop's PATH writeFileSync( config, JSON.stringify({ mcpServers: { devcoach: { command: "devcoach", args: ["mcp"] } } }), ); const bare = (await run(["doctor"])).out; expect(bare).toContain("registered: devcoach mcp"); expect(bare).toContain("`devcoach` is not found on Claude Desktop's PATH (from its log)"); expect(bare).toContain(`log: ${log}`); expect(bare).toContain( "last error in it: Failed to spawn process: No such file or directory", ); // the other cause: the file exists, its #! interpreter does not const script = join(hostBin, "devcoach"); writeFileSync(script, "#!/opt/gone/node\n", { mode: 0o755 }); const interp = (await run(["doctor"])).out; expect(interp).toContain( `command resolves to ${script} on Claude Desktop's PATH (from its log)`, ); expect(interp).toContain("its interpreter /opt/gone/node does not exist"); } finally { rmSync(dirname(config), { recursive: true, force: true }); rmSync(dirname(log), { recursive: true, force: true }); restoreXdg(); } }, ); it.skipIf(process.platform === "win32")( "install writes Claude Desktop an absolute command — npx when devcoach only lives in npx's cache", async () => { const { config } = desktopPaths(process.env.HOME as string); const savedPath = process.env.PATH; try { const real = fakeBin("devcoach", "#!/bin/sh\necho 0.0.0\n"); process.env.PATH = real; await run(["install", "--claude-desktop", "--force"]); expect(JSON.parse(readFileSync(config, "utf8")).mcpServers.devcoach).toEqual({ command: join(real, "devcoach"), args: ["mcp"], }); // `npx -y devcoach install` puts npx's cache first on PATH: that path will vanish const npxBin = join( mkdtempSync(join(tmpdir(), "dc-npxcache-")), "_npx", "0123", "node_modules", ".bin", ); mkdirSync(npxBin, { recursive: true }); writeFileSync(join(npxBin, "devcoach"), "#!/bin/sh\n", { mode: 0o755 }); process.env.PATH = npxBin; await run(["install", "--claude-desktop", "--force"]); expect(JSON.parse(readFileSync(config, "utf8")).mcpServers.devcoach).toEqual({ command: "npx", args: ["-y", "devcoach", "mcp"], }); } finally { process.env.PATH = savedPath; rmSync(dirname(config), { recursive: true, force: true }); restoreXdg(); } }, ); it("DEVCOACH_HOOK_DEBUG=1 logs hook decisions to ~/.devcoach/hook.log", async () => { db.withConnection((c) => { c.exec("DELETE FROM nudge_state;"); db.upsertKnowledge(c, "python", 4); db.setSetting(c, "nudge_every", "5"); }); process.env.DEVCOACH_HOOK_DEBUG = "1"; try { await run(["lesson-ready"]); } finally { delete process.env.DEVCOACH_HOOK_DEBUG; } const logFile = join(process.env.HOME as string, ".devcoach", "hook.log"); expect(readFileSync(logFile, "utf8")).toContain("lesson-ready - paced"); }); it("set accepts/validates nudge_every and nudge_scope", async () => { expect((await run(["set", "nudge_every", "5"])).out).toContain("Set nudge_every"); expect((await run(["set", "nudge_every", "abc"])).code).toBe(1); expect((await run(["set", "nudge_scope", "global"])).out).toContain("Set nudge_scope"); expect((await run(["set", "nudge_scope", "bogus"])).code).toBe(1); expect((await run(["settings"])).out).toContain("nudge_scope"); }); it("parseHookPayload: extracts stop_hook_active and permission_mode", () => { expect(parseHookPayload(JSON.stringify({ stop_hook_active: true })).stop_hook_active).toBe( true, ); expect(parseHookPayload(JSON.stringify({ stop_hook_active: false })).stop_hook_active).toBe( false, ); expect(parseHookPayload(JSON.stringify({ permission_mode: "plan" })).permission_mode).toBe( "plan", ); expect(parseHookPayload(JSON.stringify({ permission_mode: "default" })).permission_mode).toBe( "default", ); const empty = parseHookPayload("not json"); expect(empty.stop_hook_active).toBe(false); expect(empty.permission_mode).toBeNull(); }); it("knowledge + group + settings commands", async () => { expect( (await run(["knowledge-add", "rust", "--confidence", "6", "--group", "Languages"])).out, ).toContain("Added"); expect((await run(["profile"])).out).toContain("Knowledge Map"); expect((await run(["group-add", "Backend"])).out).toContain("ready"); expect((await run(["group-assign", "rust", "Backend"])).out).toContain("Moved"); expect((await run(["group-assign", "rust", "Other"])).out).toContain("Other"); expect((await run(["group-assign", "missing", "X"])).code).toBe(1); expect((await run(["group-remove", "Backend"])).out).toContain("Removed group"); expect((await run(["knowledge-remove", "rust"])).out).toContain("Removed"); expect((await run(["set", "max_per_day", "5"])).out).toContain("Set max_per_day"); expect((await run(["set", "bad", "5"])).code).toBe(1); expect((await run(["settings"])).out).toContain("max_per_day"); expect((await run(["stats"])).out).toContain("Coaching Stats"); }); it("courses / course list and show a course", async () => { expect((await run(["courses"])).out).toContain("No courses yet"); const course = db.withConnection((c) => courses.createCourse(c, { title: "CLI course", topic_id: "python", goal: "See it in the terminal", prerequisites: [{ concept: "loops", known: true }], }), ); const before = (await run(["course", course.id])).out; expect(before).toContain("not written yet"); expect(before).toContain("No steps registered yet"); writeFileSync(courses.documentPath(course.id), '
x
'); db.withConnection((c) => { courses.addStep(c, course.id, { title: "Loops", kind: "concept", anchor: "step-1" }); courses.setStepStatus(c, course.id, 1, "done"); }); const list = (await run(["courses"])).out; expect(list).toContain("CLI course"); expect(list).toContain("1/1"); expect(list).toContain("completed"); const show = (await run(["course", course.id])).out; expect(show).toContain("✓ loops"); expect(show).toContain("1. Loops"); expect(show).toContain("index.html"); expect((await run(["course", "missing"])).code).toBe(1); }); it("lesson commands (lesson/star/feedback/delete)", async () => { db.withConnection((c) => db.insertLesson( c, parseLesson({ id: "c1", timestamp: "2026-06-16T10:00:00Z", topic_id: "python", categories: ["python"], title: "Cli", level: "mid", summary: "s", branch: "main", commit_hash: "abcdef1", }), ), ); expect((await run(["lessons"])).out).toContain("Cli"); expect((await run(["lesson", "c1"])).out).toContain("Cli"); expect((await run(["lesson", "missing"])).code).toBe(1); expect((await run(["star", "c1"])).out).toContain("starred"); expect((await run(["unstar", "c1"])).out).toContain("unstarred"); expect((await run(["star", "missing"])).code).toBe(1); expect((await run(["feedback", "c1", "know"])).out).toContain("confidence"); expect((await run(["feedback", "c1", "clear"])).out).toContain("cleared"); expect((await run(["feedback", "missing", "know"])).code).toBe(1); expect((await run(["feedback", "c1", "bogus"])).code).toBe(1); expect((await run(["delete", "c1"])).out).toContain("deleted"); expect((await run(["delete", "c1"])).code).toBe(1); }); it("backup + restore", async () => { db.withConnection((c) => db.upsertKnowledge(c, "go", 5)); const file = join(mkdtempSync(join(tmpdir(), "dc-cli-")), "b.zip"); expect((await run(["backup", file])).out).toContain("Backup saved"); expect((await run(["restore", file])).out).toContain("restored"); expect((await run(["restore", "/no/such/file.zip"])).code).toBe(1); }); it("install writes Claude Desktop config", async () => { const r = await run(["install", "--claude-desktop", "--force"]); expect(r.out).toContain("Installed into"); }); it("install reports (and never clobbers) a malformed Claude Code settings file", async () => { const settings = join(process.env.HOME as string, ".claude", "settings.json"); mkdirSync(dirname(settings), { recursive: true }); const broken = "{ bad json,, }"; writeFileSync(settings, broken); const savedPath = process.env.PATH; process.env.PATH = ""; // avoid spawning the real `claude` CLI — exercise the JSON path directly try { const r = await run(["install", "--claude-code", "--force"]); expect(r.out).toContain("is not valid JSON"); // friendly message, no stack trace expect(r.code).toBeNull(); // did not crash / exit non-zero expect(readFileSync(settings, "utf8")).toBe(broken); // left untouched } finally { process.env.PATH = savedPath; } }); it("install via a present `claude` CLI registers + writes/repairs the hooks", async () => { const settings = cleanClaudeSettings(); const binDir = fakeBin("claude", "#!/bin/sh\nexit 0\n"); const savedPath = process.env.PATH; process.env.PATH = binDir; try { const r = await run(["install", "--claude-code", "--force"]); expect(r.out).toContain("Registered via"); expect(r.out).toContain("Hooks installed"); const saved = JSON.parse(readFileSync(settings, "utf8")); expect(saved.hooks.Stop).toHaveLength(1); expect(saved.hooks.Stop[0].hooks[0].command).toContain("stop-hook"); expect(saved.hooks.Stop[0].hooks[0].timeout).toBe(60); expect(saved.hooks.UserPromptSubmit[0].hooks[0].command).toContain("prompt-hook"); expect(saved.hooks.UserPromptSubmit[0].hooks[0].timeout).toBe(30); // re-run without --force → current layout, left alone expect((await run(["install", "--claude-code"])).out).toContain("Already installed"); // legacy two-entry Stop layout (pre-0.8) is repaired WITHOUT --force, // leaving foreign hooks untouched saved.hooks.Stop = [ { hooks: [{ type: "command", command: "npx -y devcoach onboard-hook" }] }, { hooks: [{ type: "command", command: "npx -y devcoach lesson-ready" }] }, { hooks: [{ type: "command", command: "my-other-tool --check" }] }, ]; saved.hooks.UserPromptSubmit = undefined; writeFileSync(settings, JSON.stringify(saved)); expect((await run(["install", "--claude-code"])).out).toContain("Hooks installed"); const repaired = JSON.parse(readFileSync(settings, "utf8")); const stopCmds = repaired.hooks.Stop.flatMap((e: any) => e.hooks.map((h: any) => h.command)); expect(stopCmds).toHaveLength(2); // merged devcoach entry + the foreign hook expect(stopCmds.some((cmd: string) => cmd.includes("stop-hook"))).toBe(true); expect(stopCmds.some((cmd: string) => cmd.includes("my-other-tool"))).toBe(true); expect(stopCmds.some((cmd: string) => cmd.includes("lesson-ready"))).toBe(false); expect(repaired.hooks.UserPromptSubmit).toHaveLength(1); // dev-tree layouts spell it `dev-coach` (not `devcoach`) — they must be swept // too, or they double-count interactions alongside the current entry (seen live) repaired.hooks.Stop = [ { hooks: [ { type: "command", command: "node /Users/x/dev/dev-coach/dist/bin.js onboard-hook" }, ], }, { hooks: [ { type: "command", command: "node /Users/x/dev/dev-coach/dist/bin.js lesson-ready" }, ], }, { hooks: [{ type: "command", command: "/opt/homebrew/bin/devcoach stop-hook" }] }, ]; writeFileSync(settings, JSON.stringify(repaired)); expect((await run(["install", "--claude-code"])).out).toContain("Hooks installed"); const swept = JSON.parse(readFileSync(settings, "utf8")); expect(swept.hooks.Stop).toHaveLength(1); expect(swept.hooks.Stop[0].hooks[0].command).toContain("stop-hook"); } finally { process.env.PATH = savedPath; } }); it("install skips the hooks when the devcoach plugin is enabled", async () => { const settings = cleanClaudeSettings(); writeFileSync(settings, JSON.stringify({ enabledPlugins: { "devcoach@ultimaphoenix": true } })); const savedPath = process.env.PATH; process.env.PATH = fakeBin("claude", "#!/bin/sh\nexit 0\n"); try { const r = await run(["install", "--claude-code"]); expect(r.out).toContain("plugin already provides the hooks"); expect(JSON.parse(readFileSync(settings, "utf8")).hooks).toBeUndefined(); } finally { process.env.PATH = savedPath; } }); it("install surfaces an existing/failed `claude mcp add`", async () => { const savedPath = process.env.PATH; try { process.env.PATH = fakeBin("claude", '#!/bin/sh\necho "already exists" >&2\nexit 1\n'); expect((await run(["install", "--claude-code", "--skip-hook"])).out).toContain( "Already registered", ); process.env.PATH = fakeBin("claude", "#!/bin/sh\necho boom >&2\nexit 1\n"); expect((await run(["install", "--claude-code", "--skip-hook"])).out).toContain( "claude mcp add failed", ); } finally { process.env.PATH = savedPath; } }); it("install into Claude Desktop reports an already-registered server", async () => { expect((await run(["install", "--claude-desktop", "--force"])).out).toContain("Installed into"); expect((await run(["install", "--claude-desktop"])).out).toContain("Already registered"); }); it("install writes the Claude Code skill + stamp; welcome/stats hint when missing or outdated", async () => { const settings = cleanClaudeSettings(); const skillDir = join(process.env.HOME as string, ".claude", "skills", "devcoach"); const savedPath = process.env.PATH; process.env.PATH = fakeBin("claude", "#!/bin/sh\nexit 0\n"); try { // Fresh install → SKILL.md + version stamp written. const r = await run(["install", "--claude-code", "--force"]); expect(r.out).toContain("Skill…"); expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true); expect(readFileSync(join(skillDir, ".devcoach-version"), "utf8").trim()).toBe(VERSION); // Current → no hint, and a re-run without --force leaves it alone. expect((await run([])).out).not.toContain("out of date"); expect((await run(["install", "--claude-code"])).out).toContain("Already installed"); // Stale stamp (post-upgrade) → welcome + stats hint to re-run install… writeFileSync(join(skillDir, ".devcoach-version"), "0.0.1\n"); expect((await run([])).out).toContain("out of date"); expect((await run(["stats"])).out).toContain("out of date"); // …and install refreshes it without --force (the skill file is devcoach-owned). expect((await run(["install", "--claude-code"])).out).toContain(`Installed into ${skillDir}`); expect(readFileSync(join(skillDir, ".devcoach-version"), "utf8").trim()).toBe(VERSION); // Missing + Stop hooks present → hinted; missing + no hooks (Desktop-only) → silent. rmSync(join(process.env.HOME as string, ".claude", "skills"), { recursive: true, force: true, }); expect((await run([])).out).toContain("not installed"); writeFileSync(settings, "{}"); expect((await run([])).out).not.toContain("not installed"); } finally { process.env.PATH = savedPath; } }); it("install --gemini writes settings.json hooks + MCP (fallback path) and the shared skill", async () => { const home = process.env.HOME as string; const settings = join(home, ".gemini", "settings.json"); const skillDir = join(home, ".agents", "skills", "devcoach"); rmSync(join(home, ".gemini"), { recursive: true, force: true }); rmSync(join(home, ".agents"), { recursive: true, force: true }); // An empty PATH dir guarantees the no-CLI fallback even when a real gemini is installed. const savedPath = process.env.PATH; process.env.PATH = mkdtempSync(join(tmpdir(), "dc-nobin-")); const r = await run(["install", "--gemini", "--force"]); expect(r.out).toContain("Gemini CLI (beta)"); const saved = JSON.parse(readFileSync(settings, "utf8")); expect(saved.mcpServers.devcoach.args).toContain("mcp"); expect(saved.hooks.AfterAgent[0].hooks[0].command).toContain("gemini-stop-hook"); expect(saved.hooks.AfterAgent[0].hooks[0].timeout).toBe(60000); expect(saved.hooks.BeforeAgent[0].hooks[0].command).toContain("gemini-prompt-hook"); expect(saved.hooks.BeforeAgent[0].hooks[0].timeout).toBe(30000); expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true); expect(readFileSync(join(skillDir, ".devcoach-version"), "utf8").trim()).toBe(VERSION); // Re-run without --force → everything already current. expect((await run(["install", "--gemini"])).out).toContain("Already"); // A stale gemini hook layout self-heals without --force (regex covers gemini-*-hook). saved.hooks.AfterAgent = [ { hooks: [{ type: "command", command: "npx -y devcoach gemini-stop-hook" }] }, { hooks: [{ type: "command", command: "my-other-tool --check" }] }, ]; writeFileSync(settings, JSON.stringify(saved)); try { expect((await run(["install", "--gemini"])).out).toContain("Hooks installed"); const repaired = JSON.parse(readFileSync(settings, "utf8")); const cmds = repaired.hooks.AfterAgent.flatMap((e: any) => e.hooks.map((h: any) => h.command), ); expect(cmds).toHaveLength(2); expect(cmds.some((c: string) => c.includes("my-other-tool"))).toBe(true); expect(repaired.hooks.AfterAgent.flatMap((e: any) => e.hooks)[1].timeout).toBe(60000); } finally { process.env.PATH = savedPath; } }); it("install --gemini registers via a present `gemini` CLI and skips hooks+skill when the extension is installed", async () => { const home = process.env.HOME as string; rmSync(join(home, ".gemini"), { recursive: true, force: true }); rmSync(join(home, ".agents"), { recursive: true, force: true }); const savedPath = process.env.PATH; process.env.PATH = fakeBin("gemini", "#!/bin/sh\nexit 0\n"); // fake shadows any real gemini try { expect((await run(["install", "--gemini"])).out).toContain("Registered via `gemini mcp add`"); // Extension manifest present → hooks and skill are its job (double-count guard). const extDir = join(home, ".gemini", "extensions", "devcoach"); mkdirSync(extDir, { recursive: true }); writeFileSync(join(extDir, "gemini-extension.json"), "{}"); rmSync(join(home, ".gemini", "settings.json"), { force: true }); rmSync(join(home, ".agents"), { recursive: true, force: true }); const r = await run(["install", "--gemini"]); expect(r.out).toContain("extension already provides the hooks"); expect(r.out).toContain("bundled with the devcoach Gemini extension"); expect(existsSync(join(home, ".gemini", "settings.json"))).toBe(false); expect(existsSync(join(home, ".agents"))).toBe(false); } finally { process.env.PATH = savedPath; rmSync(join(home, ".gemini", "extensions"), { recursive: true, force: true }); } }); it("install --codex writes hooks.json + skill and prints the TOML snippet without the codex CLI", async () => { const home = process.env.HOME as string; const hooksJson = join(home, ".codex", "hooks.json"); rmSync(join(home, ".codex"), { recursive: true, force: true }); rmSync(join(home, ".agents"), { recursive: true, force: true }); const savedPath = process.env.PATH; // An empty PATH dir guarantees the no-CLI branch even when a real codex is installed. process.env.PATH = mkdtempSync(join(tmpdir(), "dc-nobin-")); try { const r = await run(["install", "--codex"]); expect(r.out).toContain("Codex CLI (beta)"); expect(r.out).toContain("[mcp_servers.devcoach]"); // manual TOML snippet, config left alone const saved = JSON.parse(readFileSync(hooksJson, "utf8")); expect(saved.hooks.Stop[0].hooks[0].command).toContain("codex-stop-hook"); expect(saved.hooks.Stop[0].hooks[0].timeout).toBe(60); expect(saved.hooks.UserPromptSubmit[0].hooks[0].command).toContain("codex-prompt-hook"); expect(existsSync(join(home, ".agents", "skills", "devcoach", "SKILL.md"))).toBe(true); // With a fake codex CLI on PATH the MCP step goes through `codex mcp add`. process.env.PATH = fakeBin("codex", "#!/bin/sh\nexit 0\n"); expect((await run(["install", "--codex"])).out).toContain("Registered via `codex mcp add`"); } finally { process.env.PATH = savedPath; } }); it("install never clobbers malformed gemini/codex config files", async () => { const home = process.env.HOME as string; const settings = join(home, ".gemini", "settings.json"); mkdirSync(dirname(settings), { recursive: true }); writeFileSync(settings, "{not json"); const r = await run(["install", "--gemini"]); expect(r.out).toContain("not valid JSON"); expect(readFileSync(settings, "utf8")).toBe("{not json"); rmSync(join(home, ".gemini"), { recursive: true, force: true }); }); it("doctor shows Gemini/Codex sections only when their config dirs exist", async () => { const home = process.env.HOME as string; rmSync(join(home, ".gemini"), { recursive: true, force: true }); rmSync(join(home, ".codex"), { recursive: true, force: true }); const before = await run(["doctor"]); expect(before.out).not.toContain("Gemini CLI wiring"); expect(before.out).not.toContain("Codex CLI wiring"); // Empty PATH dir → deterministic config-write path even with real CLIs installed. const savedPath = process.env.PATH; process.env.PATH = mkdtempSync(join(tmpdir(), "dc-nobin-")); try { await run(["install", "--gemini", "--codex", "--force"]); } finally { process.env.PATH = savedPath; } const after = await run(["doctor"]); expect(after.out).toContain("Gemini CLI wiring (beta)"); expect(after.out).toContain("AfterAgent stop hook wired"); expect(after.out).toContain("BeforeAgent priming hook wired"); expect(after.out).toContain("Codex CLI wiring (beta)"); expect(after.out).toContain("Stop hook wired"); // Extension + settings hooks together → the double-registration alarm. const extDir = join(home, ".gemini", "extensions", "devcoach"); mkdirSync(extDir, { recursive: true }); writeFileSync(join(extDir, "gemini-extension.json"), "{}"); expect((await run(["doctor"])).out).toContain("registered TWICE (extension + settings.json)"); rmSync(join(home, ".gemini"), { recursive: true, force: true }); rmSync(join(home, ".codex"), { recursive: true, force: true }); rmSync(join(home, ".agents"), { recursive: true, force: true }); }); it("onboard-hook re-cues every stop until a profile exists (no debounce)", async () => { db.withConnection((c) => c.exec( "DELETE FROM knowledge; DELETE FROM knowledge_groups; DELETE FROM knowledge_group_names;", ), ); // No 24h session window any more: an unanswered cue must fire again next stop, // so an interrupted onboarding is never silently suppressed. const first = await run(["onboard-hook"]); expect(first.out).toContain('"decision":"block"'); const second = await run(["onboard-hook"]); expect(second.out).toContain('"decision":"block"'); }); it("hooks never create coaching.db when there is no profile", async () => { rmSync(db.DB_PATH, { force: true }); // onboard-hook cues, lesson-ready stays silent — neither opens (creates) the DB. const onb = await run(["onboard-hook"]); expect(onb.out).toContain('"decision":"block"'); expect(existsSync(db.DB_PATH)).toBe(false); const lr = await run(["lesson-ready"]); expect(lr.out).not.toContain("decision"); expect(existsSync(db.DB_PATH)).toBe(false); }); it("usage errors exit 2", async () => { expect((await run(["lesson"])).code).toBe(2); expect((await run(["set", "onlyone"])).code).toBe(2); }); it("Commander help/version/error handling", async () => { // top-level --help → usage text, no crash, clean exit const help = await run(["--help"]); expect(help.out).toContain("Usage: devcoach"); expect(help.out).toContain("lessons"); expect(help.code).toBeNull(); // help is not an error exit // per-command --help (the case that used to crash with parseArgs) const lessonsHelp = await run(["lessons", "--help"]); expect(lessonsHelp.out).toContain("Usage: devcoach lessons"); expect(lessonsHelp.out).toContain("--period"); // --version const ver = await run(["--version"]); expect(ver.out).toContain(`devcoach ${VERSION}`); // unknown flag → friendly error, exit 2 (not a stack trace) const badFlag = await run(["lessons", "--nope"]); expect(badFlag.code).toBe(2); expect(badFlag.out).toContain("unknown option"); expect(badFlag.out).not.toContain("at "); // no stack-trace frames }); }); describe("cli on a database newer than this build (read-only)", () => { const stamp = (v: number) => { const raw = db.getConnection(db.DB_PATH); raw.exec(`PRAGMA user_version = ${v}`); raw.close(); }; it("read commands work and say so; a write is refused with the versions; doctor explains", async () => { db.withConnection((c) => db.insertLesson( c, parseLesson({ id: "ro1", timestamp: "2026-01-01T00:00:00Z", topic_id: "python", categories: [], title: "Read me", level: "mid", summary: "s", }), ), ); stamp(99); try { const stats = await run(["stats"]); expect(stats.code).toBeNull(); expect(stats.out).toContain("Reads work; writes need"); const lessons = await run(["lessons"]); expect(lessons.out).toContain("Read me"); expect(lessons.out).toContain("schema v99"); await expect(run(["feedback", "ro1", "know"])).rejects.toThrow(db.SchemaTooNewError); const doctor = await run(["doctor"]); expect(doctor.code).toBeNull(); expect(doctor.out).toContain("READ-ONLY"); expect(doctor.out).toContain(`devcoach ${VERSION} (schema v${db.SCHEMA_VERSION})`); const check = db.getConnection(db.DB_PATH); expect( (check.prepare("PRAGMA user_version").get() as { user_version: number }).user_version, ).toBe(99); check.close(); } finally { stamp(db.SCHEMA_VERSION); } expect((await run(["doctor"])).out).toContain( `schema v${db.SCHEMA_VERSION}, last upgraded by devcoach ${VERSION}`, ); }); }); describe("cli rich rendering branches", () => { function seed() { db.withConnection((c) => { const mk = (o: Record) => db.insertLesson( c, parseLesson({ timestamp: "2026-06-16T10:00:00Z", topic_id: "python", categories: ["python"], summary: "s", ...o, }), ); mk({ id: "jr", title: "Jr", level: "junior", feedback: "dont_know", starred: true }); mk({ id: "sr", title: "Sr", level: "senior", feedback: "know", starred: true, task_context: "ctx", project: "P", repository: "o/r", repository_platform: "github", branch: "main", commit_hash: "abc1234", folder: "/f", }); mk({ id: "po", title: "Po", level: "mid", project: "OnlyP" }); // project, no branch/commit }); } it("lessons table renders junior/senior colors, dont_know icon, and meta columns", async () => { seed(); const out = (await run(["lessons"])).out; expect(out).toContain("Jr"); expect(out).toContain("Sr"); expect(out).toContain("OnlyP"); // project column populated }); it("lesson detail renders git metadata, context, starred, and both feedback labels", async () => { const sr = (await run(["lesson", "sr"])).out; expect(sr).toContain("project=P"); expect(sr).toContain("branch="); expect(sr).toContain("commit="); expect(sr).toContain("folder=/f"); expect(sr).toContain("Context:"); expect(sr).toContain("★ starred"); expect(sr).toContain("I knew this"); const jr = (await run(["lesson", "jr"])).out; expect(jr).toContain("Couldn't follow"); }); it("leaving know undoes its +1; understood and dont_know leave confidence alone", async () => { const left = (await run(["feedback", "sr", "dont_know"])).out; const m = left.match(/confidence: (\d+) → (\d+)/); expect(m).not.toBeNull(); expect(Number(m?.[2])).toBe(Number(m?.[1]) - 1); // leaving `know` undoes its +1 expect((await run(["feedback", "sr", "understood"])).out).toContain("confidence unchanged"); expect((await run(["feedback", "sr", "understood"])).out).toContain("💡 Understood"); }); it("stats shows weakest and strongest topics", async () => { db.withConnection((c) => { db.upsertKnowledge(c, "weak1", 1); db.upsertKnowledge(c, "weak2", 2); db.upsertKnowledge(c, "strong1", 9); db.upsertKnowledge(c, "strong2", 10); }); const out = (await run(["stats"])).out; expect(out).toContain("Weakest topics"); expect(out).toContain("Strongest topics"); }); it("knowledge-add without a group lands in Other; remove of a missing topic warns", async () => { expect((await run(["knowledge-add", "loner", "--confidence", "3"])).out).toContain("Added"); expect((await run(["knowledge-remove", "ghost"])).out).toContain("not found"); }); it("group-add rejects the reserved 'Other' name", async () => { expect((await run(["group-add", "Other"])).code).toBe(1); }); it("backup notes the notebook when a learning-state file exists", async () => { writeFileSync(db.LEARNING_STATE_PATH, "# notes\n"); const file = join(mkdtempSync(join(tmpdir(), "dc-nb-")), "b.zip"); expect((await run(["backup", file])).out).toContain("+ notebook"); // restoring it twice → second run reports duplicates skipped + notebook restored await run(["restore", file]); expect((await run(["restore", file])).out).toContain("duplicates skipped"); }); it("install uses the bare `devcoach` command when it is on PATH", async () => { const binDir = fakeBin("devcoach", "#!/bin/sh\nexit 0\n"); const savedPath = process.env.PATH; process.env.PATH = binDir; // devcoach present, claude absent try { const r = await run(["install", "--claude-desktop", "--force"]); expect(r.out).toContain("devcoach mcp"); // detectInstallMethod chose the bare command } finally { process.env.PATH = savedPath; } }); }); describe("cli share / import", () => { const seed = (id: string) => db.withConnection((c) => db.insertLesson( c, parseLesson({ id, timestamp: "2026-09-01T10:00:00Z", topic_id: "docker", categories: ["docker"], title: `Layer cache ${id}`, level: "mid", summary: "Order Dockerfile steps from stable to volatile.", body: "Body text.", folder: "/Users/someone/private", repository_platform: "local", repository: "/Users/someone/private", }), ), ); it("share prints the card + code, --link the link, --file a .devcoach.md; errors are friendly", async () => { seed("s1"); const text = await run(["share", "s1", "--anonymous"]); expect(text.out).toContain("🎓 devcoach"); expect(text.out).toContain("Layer cache s1"); expect(text.out).toMatch(/devcoach:lesson:1:[A-Za-z0-9_-]+/); expect(text.out).toContain("Shared anonymously"); expect(text.out).not.toContain("/Users/someone"); // local paths never leave const link = await run(["share", "--last", "--anonymous", "--link"]); expect(link.out.trim()).toMatch( /^https:\/\/ultimaphoenix\.github\.io\/dev-coach\/lesson#devcoach:lesson:1:/, ); const dir = mkdtempSync(join(tmpdir(), "dc-share-")); const file = join(dir, "l.devcoach.md"); expect( (await run(["share", "s1", "--file", file, "--with-context", "--by", "Ada"])).out, ).toContain("Saved:"); expect(readFileSync(file, "utf8")).toContain('shared_by: "Ada"'); expect(readFileSync(file, "utf8")).not.toContain("/Users/someone"); expect((await run(["share", "nope"])).code).toBe(1); expect((await run(["share"])).code).toBe(2); expect((await run(["share", "s1", "--by", "X", "--anonymous"])).code).toBe(1); }); it("--by is remembered as share_name once; settings/set expose it", async () => { seed("s2"); expect(db.withConnection((c) => db.getSettings(c).share_name)).toBe("Ada"); // from the --file share above expect((await run(["share", "s2", "--by", "Bob"])).out).toContain("Shared by Bob"); expect(db.withConnection((c) => db.getSettings(c).share_name)).toBe("Ada"); // not overwritten expect((await run(["settings"])).out).toContain("Ada"); expect((await run(["set", "share_name", "Carol"])).out).toContain("Set share_name = Carol"); expect((await run(["set", "share_name", ""])).out).toContain("Cleared"); expect((await run(["set", "share_name", "x".repeat(81)])).code).toBe(1); // no setting left → falls back to git user.name, or anonymous when git has none expect((await run(["share", "s2"])).out).toMatch( /Shared (by [^\n]+ with devcoach|anonymously)/, ); }); it("import takes a code, a file, stdin, a URL — duplicates and junk are reported, not thrown", async () => { seed("s3"); const code = (await run(["share", "s3", "--anonymous"])).out.match( /devcoach:lesson:1:[A-Za-z0-9_-]+/, )?.[0] ?? ""; db.withConnection((c) => c.exec("DELETE FROM lessons WHERE id = 's3'")); const first = await run(["import", code]); expect(first.out).toContain('✓ Imported "Layer cache s3"'); expect(first.out).toContain("shared anonymously"); expect(first.out).toContain("not in your knowledge map"); expect((await run(["import", code])).out).toContain("Already in your log"); expect((await run(["lessons", "--imported"])).out).toContain("Layer cache s3"); expect((await run(["lesson", "s3"])).out).toContain("Shared by:"); // file seed("s4"); const dir = mkdtempSync(join(tmpdir(), "dc-import-")); const file = join(dir, "l.devcoach.md"); await run(["share", "s4", "--file", file, "--by", "Ada"]); db.withConnection((c) => c.exec("DELETE FROM lessons WHERE id = 's4'")); expect((await run(["import", file])).out).toContain("shared by Ada"); expect((await run(["lessons", "--from", "Ada"])).out).toContain("Layer cache s4"); expect((await run(["lessons", "--from", "Nobody"])).out).toContain("No lessons found"); // stdin seed("s5"); const stdinText = (await run(["share", "s5", "--anonymous"])).out; db.withConnection((c) => c.exec("DELETE FROM lessons WHERE id = 's5'")); const stdinSpy = vi .spyOn(process, "stdin", "get") .mockReturnValue(Readable.from([stdinText]) as never); try { expect((await run(["import", "-"])).out).toContain('✓ Imported "Layer cache s5"'); } finally { stdinSpy.mockRestore(); } // URL (fetched) and share link (decoded locally, never fetched) seed("s6"); const link = (await run(["share", "s6", "--anonymous", "--link"])).out.trim(); db.withConnection((c) => c.exec("DELETE FROM lessons WHERE id = 's6'")); const fetchSpy = vi.mocked(fetchSharedInput).mockImplementation(async () => { throw new Error("must not fetch a share link"); }); try { expect((await run(["import", link])).out).toContain('✓ Imported "Layer cache s6"'); expect(fetchSpy).not.toHaveBeenCalled(); fetchSpy.mockResolvedValueOnce(stdinText); expect((await run(["import", "https://example.test/raw"])).out).toContain( "Already in your log", ); } finally { fetchSpy.mockReset(); } // legacy lessons array + junk expect( ( await run([ "import", JSON.stringify([ { id: "legacy-1", timestamp: "2026-01-01T00:00:00Z", topic_id: "go", categories: [], title: "t", level: "mid", summary: "s", }, ]), ]) ).out, ).toContain("1 imported"); const junk = await run(["import", "/no/such/file"]); expect(junk.code).toBe(1); expect(junk.out).toContain("Not a devcoach lesson"); expect(junk.out).not.toContain(" at "); }); it("import with no argument reads the clipboard, and says so when there is none", async () => { const path = process.env.PATH; process.env.PATH = ""; // no pbpaste/xclip reachable → friendly error, no spawn of anything real try { const r = await run(["import"]); expect(r.code).toBe(1); expect(r.out).toContain("Clipboard is empty or unavailable"); } finally { process.env.PATH = path; } expect((await run([])).out).toContain("share / import"); }); }); describe("cli uninstall", () => { const home = () => process.env.HOME as string; it("removes the MCP entry, the devcoach hooks and the skill — user hooks and other keys survive", async () => { const savedPath = process.env.PATH; process.env.PATH = ""; // no `claude` CLI → the JSON path for both install and uninstall try { const settings = cleanClaudeSettings(); await run(["install", "--claude-code", "--force"]); const before = JSON.parse(readFileSync(settings, "utf8")); before.hooks.Stop.push({ hooks: [{ type: "command", command: "my-other-tool --check" }] }); before.theme = "dark"; writeFileSync(settings, JSON.stringify(before)); const codeConfig = join(home(), ".claude.json"); const cfg = JSON.parse(readFileSync(codeConfig, "utf8")); cfg.mcpServers.other = { command: "x" }; writeFileSync(codeConfig, JSON.stringify(cfg)); const skillDir = join(home(), ".claude", "skills", "devcoach"); expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true); const r = await run(["uninstall", "--claude-code"]); expect(r.out).toContain("Removed from"); expect(r.out).toContain("Hooks removed from"); expect(r.out).toContain("Removed " + skillDir); expect(r.out).toContain("still in"); // data kept by default const after = JSON.parse(readFileSync(settings, "utf8")); expect(after.theme).toBe("dark"); expect(after.hooks.UserPromptSubmit).toBeUndefined(); expect(after.hooks.Stop).toHaveLength(1); expect(after.hooks.Stop[0].hooks[0].command).toBe("my-other-tool --check"); const cfgAfter = JSON.parse(readFileSync(codeConfig, "utf8")); expect(cfgAfter.mcpServers.devcoach).toBeUndefined(); expect(cfgAfter.mcpServers.other).toEqual({ command: "x" }); expect(existsSync(skillDir)).toBe(false); // idempotent: a second run reports nothing to remove and exits cleanly const again = await run(["uninstall", "--claude-code"]); expect(again.code).toBeNull(); expect(again.out).toContain("Not registered"); expect(again.out).toContain("No devcoach hooks"); expect(again.out).toContain("Not installed"); } finally { process.env.PATH = savedPath; } }); it("unregisters through a present `claude` CLI and clears the Desktop config", async () => { const savedPath = process.env.PATH; process.env.PATH = fakeBin("claude", "#!/bin/sh\nexit 0\n"); try { await run(["install", "--claude-desktop", "--force"]); const r = await run(["uninstall"]); expect(r.out).toContain("Removed via `claude mcp remove`"); expect(r.out).toContain("Claude Desktop"); expect(r.out).toContain("Removed from"); expect(r.out).toContain("Restart Claude Desktop"); } finally { process.env.PATH = savedPath; } }); it("--all covers Gemini/Codex (manual TOML note without codex) and keeps the shared skill while in use", async () => { const savedPath = process.env.PATH; process.env.PATH = ""; try { await run(["install", "--gemini", "--force"]); await run(["install", "--codex", "--force"]); const shared = join(home(), ".agents", "skills", "devcoach"); expect(existsSync(join(shared, "SKILL.md"))).toBe(true); // removing only Gemini keeps the skill Codex still reads const g = await run(["uninstall", "--gemini"]); expect(g.out).toContain("Gemini CLI"); expect(g.out).toContain("Kept"); expect(existsSync(join(shared, "SKILL.md"))).toBe(true); const all = await run(["uninstall", "--all"]); expect(all.out).toContain("Manual step"); // no codex CLI → TOML left to the user expect(all.out).toContain("Removed " + shared); expect(existsSync(shared)).toBe(false); const codexHooks = JSON.parse(readFileSync(join(home(), ".codex", "hooks.json"), "utf8")); expect(codexHooks.hooks).toBeUndefined(); } finally { process.env.PATH = savedPath; } }); it("--data needs --yes outside a terminal, then deletes the data dir; malformed settings are left alone", async () => { const savedPath = process.env.PATH; process.env.PATH = ""; try { const settings = join(home(), ".claude", "settings.json"); mkdirSync(dirname(settings), { recursive: true }); writeFileSync(settings, "{ bad json,, }"); const dataDir = db.DEVCOACH_DIR; db.withConnection((c) => c.exec("SELECT 1")); // make sure the data dir exists expect(existsSync(dataDir)).toBe(true); const noYes = await run(["uninstall", "--claude-code", "--data"]); expect(noYes.out).toContain("is not valid JSON"); expect(noYes.out).toContain("pass --yes"); expect(existsSync(dataDir)).toBe(true); expect(readFileSync(settings, "utf8")).toBe("{ bad json,, }"); const yes = await run(["uninstall", "--claude-code", "--data", "--yes"]); expect(yes.out).toContain("Deleted " + dataDir); expect(existsSync(dataDir)).toBe(false); // the store recreates itself on the next use expect(db.withConnection((c) => db.getSettings(c).max_per_day)).toBe(2); } finally { process.env.PATH = savedPath; } }); }); describe("cli ui — link, --open, --stop, graceful shutdown", () => { it("browserCommand picks the platform opener", async () => { const { browserCommand } = await import("../src/cli/open"); expect(browserCommand("darwin", "http://x")).toEqual(["open", ["http://x"]]); expect(browserCommand("win32", "http://x")).toEqual(["cmd", ["/c", "start", "", "http://x"]]); expect(browserCommand("linux", "http://x")).toEqual(["xdg-open", ["http://x"]]); }); it("startUi prints the URL, hands it to onReady, and POST /shutdown closes it gracefully", async () => { const { startUi } = await import("../src/web/app"); const lines: string[] = []; const logSpy = vi.spyOn(console, "log").mockImplementation((...a) => lines.push(a.join(" "))); let readyUrl = ""; const server = startUi(0, { handleSignals: false, onReady: (u) => (readyUrl = u) }); const port = await new Promise((resolve) => server.once("listening", () => resolve((server.address() as { port: number }).port)), ); const closed = new Promise((resolve) => server.once("close", () => resolve())); try { await vi.waitFor(() => expect(readyUrl).toBe(`http://localhost:${port}`)); expect(lines.join("\n")).toContain(`running at http://localhost:${port}`); // GET is not a stop; a cross-site POST is refused; a same-origin POST stops it expect((await fetch(`http://127.0.0.1:${port}/shutdown`)).status).toBe(405); const cross = await fetch(`http://127.0.0.1:${port}/shutdown`, { method: "POST", headers: { "sec-fetch-site": "cross-site" }, }); expect(cross.status).toBe(403); expect(server.listening).toBe(true); const ok = await fetch(`http://127.0.0.1:${port}/shutdown`, { method: "POST" }); expect(await ok.json()).toEqual({ ok: true }); await closed; expect(server.listening).toBe(false); } finally { logSpy.mockRestore(); if (server.listening) server.close(); } }); it("ui --stop reports stopped / not running", async () => { const { startUi } = await import("../src/web/app"); const server = startUi(0, { handleSignals: false }); const port = await new Promise((resolve) => server.once("listening", () => resolve((server.address() as { port: number }).port)), ); const closed = new Promise((resolve) => server.once("close", () => resolve())); expect((await run(["ui", "--stop", "--port", String(port)])).out).toContain("stopped"); await closed; expect((await run(["ui", "--stop", "--port", String(port)])).out).toContain( "No devcoach UI is running", ); }); it("startUi on a port held by a running dashboard explains it instead of crashing", async () => { const { startUi } = await import("../src/web/app"); const first = startUi(0, { handleSignals: false }); const port = await new Promise((resolve) => first.once("listening", () => resolve((first.address() as { port: number }).port)), ); const onListenError = vi.fn(); const second = startUi(port, { handleSignals: false, onListenError }); try { await vi.waitFor(() => expect(onListenError).toHaveBeenCalledTimes(1)); const failure = onListenError.mock.calls[0][0]; expect(failure.exitCode).toBe(0); expect(failure.existingUrl).toBe(`http://localhost:${port}`); expect(failure.message).toContain("already running at"); expect(failure.message).toContain(`(v${VERSION})`); expect(failure.message).toContain("devcoach ui --stop"); expect(first.listening).toBe(true); } finally { if (second.listening) second.close(); first.close(); } }); it("startUi on a port held by another process reports it as busy (exit 1)", async () => { const { createServer } = await import("node:net"); const { startUi } = await import("../src/web/app"); const other = createServer(); const port = await new Promise((resolve) => other.listen(0, "127.0.0.1", () => resolve((other.address() as { port: number }).port)), ); const onListenError = vi.fn(); const ui = startUi(port, { handleSignals: false, onListenError }); try { // The raw socket accepts and never answers, so the /ping probe runs into its 1.5 s timeout. await vi.waitFor(() => expect(onListenError).toHaveBeenCalledTimes(1), { timeout: 4000 }); const failure = onListenError.mock.calls[0][0]; expect(failure.exitCode).toBe(1); expect(failure.existingUrl).toBeUndefined(); expect(failure.message).toContain(`Port ${port} is already in use by another process`); expect(failure.message).toContain("--port "); } finally { if (ui.listening) ui.close(); other.close(); } }); it("explainListenError words EACCES and unknown errors; pingUi is null off a dashboard", async () => { const { explainListenError, pingUi } = await import("../src/web/app"); const eacces = Object.assign(new Error("listen EACCES"), { code: "EACCES" }); expect((await explainListenError(80, eacces)).message).toContain("permission denied"); const odd = Object.assign(new Error("boom"), { code: "EWEIRD" }); const failure = await explainListenError(7860, odd); expect(failure.exitCode).toBe(1); expect(failure.message).toContain("Could not start the devcoach UI on port 7860: boom"); // A non-devcoach answer on the port (ping rejects the body) counts as "another process". const busy = Object.assign(new Error("in use"), { code: "EADDRINUSE" }); const foreign = await explainListenError(7860, busy, async () => null); expect(foreign.existingUrl).toBeUndefined(); const { createServer } = await import("node:net"); const other = createServer(); const port = await new Promise((resolve) => other.listen(0, "127.0.0.1", () => resolve((other.address() as { port: number }).port)), ); other.close(); expect(await pingUi(port)).toBeNull(); const notOk = async () => new Response(JSON.stringify({ ok: false }), { status: 200 }); expect(await pingUi(port, notOk as unknown as typeof fetch)).toBeNull(); const err500 = async () => new Response("nope", { status: 500 }); expect(await pingUi(port, err500 as unknown as typeof fetch)).toBeNull(); }); }); describe("gracefulShutdown", () => { it("lets an in-flight response finish, refuses new connections, then closes", async () => { const { gracefulShutdown } = await import("../src/web/app"); const { createServer } = await import("node:http"); const server = createServer((_req, res) => { setTimeout(() => res.end("done"), 400); // a slow handler, still running when we shut down }); await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); const port = (server.address() as { port: number }).port; const inflight = fetch(`http://127.0.0.1:${port}/slow`); await new Promise((r) => setTimeout(r, 100)); // the request is accepted and being handled const t0 = Date.now(); const done = gracefulShutdown(server, 2000); const res = await inflight; expect(res.status).toBe(200); expect(await res.text()).toBe("done"); // finished, not cut await done; expect(Date.now() - t0).toBeLessThan(1500); // closed as soon as the drain completed, not at the deadline expect(server.listening).toBe(false); await expect(fetch(`http://127.0.0.1:${port}/slow`)).rejects.toThrow(); // nothing listens any more }); it("cuts connections that outlive the grace period", async () => { const { gracefulShutdown } = await import("../src/web/app"); const { createServer } = await import("node:http"); const server = createServer((_req, res) => { res.write("partial"); // never ends — a hung response }); await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve)); const port = (server.address() as { port: number }).port; const hung = fetch(`http://127.0.0.1:${port}/hang`).then((r) => r.text()); await new Promise((r) => setTimeout(r, 100)); const t0 = Date.now(); await gracefulShutdown(server, 300); expect(Date.now() - t0).toBeGreaterThanOrEqual(250); expect(server.listening).toBe(false); await expect(hung).rejects.toThrow(); // the hung response was terminated at the deadline }); });