headlesscode 1.0.2

package/src/checkpoints/cli.ts

@@ -0,0 +1,256 @@
+/**
+ * `headlesscode checkpoints` subcommand.
+ *
+ *   npx tsx src/cli.ts checkpoints --workspace <path> list
+ *   npx tsx src/cli.ts checkpoints --workspace <path> restore <hash>
+ *   npx tsx src/cli.ts checkpoints --workspace <path> diff <hash> [<to-hash>]
+ *
+ * A human-facing wrapper around src/checkpoints/service.ts. Since each
+ * `HeadlessSession` gets its own random taskId (see src/engine/loop.ts), a
+ * workspace can have checkpoints from multiple past sessions. This CLI
+ * operates on the MOST RECENT session's checkpoints for the workspace (the
+ * one most likely relevant to "undo my last run") — found by scanning
+ * `<checkpointDir>/tasks/*\/checkpoints` for the shadow repo whose
+ * `core.worktree` matches `--workspace` and picking the one with the newest
+ * commit. Pass `--task-id <id>` to target a specific session explicitly.
+ */
+
+import { execFileSync } from "node:child_process"
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import { createCheckpointService, defaultCheckpointDir, type CheckpointService } from "./service.js"
+
+const CHECKPOINTS_USAGE = `headlesscode checkpoints — inspect/revert shadow-git checkpoints
+
+Usage:
+  headlesscode checkpoints --workspace <path> list
+  headlesscode checkpoints --workspace <path> restore <hash>
+  headlesscode checkpoints --workspace <path> diff [<from-hash>] [<to-hash>]
+
+Options:
+  --workspace <path>     Workspace root whose checkpoints to inspect (required)
+  --checkpoint-dir <path> Shadow-git storage root (default: ${defaultCheckpointDir()})
+  --task-id <id>         Operate on this session's checkpoints instead of
+                         auto-detecting the most recent one for --workspace
+  --help                 Show this help and exit
+
+Commands:
+  list                   List checkpoints for the workspace, oldest-first
+                         (hash, date, message)
+  restore <hash>         Check the shadow ref out onto the real workspace,
+                         reverting files to that checkpoint. DESTRUCTIVE:
+                         uncommitted changes since that checkpoint are lost.
+  diff [<from>] [<to>]   Show changed files between two checkpoints (default
+                         from: the first checkpoint; default to: the current
+                         working tree)
+`
+
+interface CheckpointsCliOptions {
+	workspace?: string
+	checkpointDir?: string
+	taskId?: string
+	help: boolean
+	command?: "list" | "restore" | "diff"
+	commandArgs: string[]
+}
+
+export function parseCheckpointsArgs(argv: string[]): { options: CheckpointsCliOptions; error?: string } {
+	const options: CheckpointsCliOptions = { help: false, commandArgs: [] }
+
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]
+		const eq = arg.indexOf("=")
+		const flag = eq === -1 ? arg : arg.slice(0, eq)
+		const inlineValue = eq === -1 ? undefined : arg.slice(eq + 1)
+		const next = (): string | undefined => {
+			if (inlineValue !== undefined) {
+				return inlineValue
+			}
+			const v = argv[i + 1]
+			if (v === undefined || v.startsWith("--")) {
+				return undefined
+			}
+			i++
+			return v
+		}
+
+		switch (flag) {
+			case "--workspace": {
+				const v = next()
+				if (v === undefined) {
+					return { options, error: "Missing value for --workspace" }
+				}
+				options.workspace = v
+				break
+			}
+			case "--checkpoint-dir": {
+				const v = next()
+				if (v === undefined) {
+					return { options, error: "Missing value for --checkpoint-dir" }
+				}
+				options.checkpointDir = v
+				break
+			}
+			case "--task-id": {
+				const v = next()
+				if (v === undefined) {
+					return { options, error: "Missing value for --task-id" }
+				}
+				options.taskId = v
+				break
+			}
+			case "--help":
+			case "-h":
+				options.help = true
+				break
+			case "list":
+			case "restore":
+			case "diff":
+				if (options.command) {
+					return { options, error: `Unexpected extra command: ${arg}` }
+				}
+				options.command = flag
+				break
+			default:
+				if (arg.startsWith("--")) {
+					return { options, error: `Unknown argument: ${arg}` }
+				}
+				options.commandArgs.push(arg)
+				break
+		}
+	}
+
+	return { options }
+}
+
+/**
+ * Find the most recently active session (taskId) for `workspace` under
+ * `checkpointDir`, by scanning `<checkpointDir>/tasks/*\/checkpoints` shadow
+ * repos and picking the one whose `core.worktree` matches and whose `.git`
+ * dir has the newest mtime.
+ */
+function findMostRecentTaskId(checkpointDir: string, workspace: string): string | undefined {
+	const tasksDir = path.join(checkpointDir, "tasks")
+	let entries: string[]
+	try {
+		entries = fs.readdirSync(tasksDir)
+	} catch {
+		return undefined
+	}
+
+	const workspaceAbs = path.resolve(workspace)
+	let best: { taskId: string; mtimeMs: number } | undefined
+
+	for (const taskId of entries) {
+		const gitDir = path.join(tasksDir, taskId, "checkpoints", ".git")
+		let worktree: string
+		try {
+			worktree = execFileSync("git", ["--git-dir", gitDir, "config", "core.worktree"], {
+				encoding: "utf-8",
+			}).trim()
+		} catch {
+			continue
+		}
+		if (path.resolve(worktree) !== workspaceAbs) {
+			continue
+		}
+		let mtimeMs: number
+		try {
+			mtimeMs = fs.statSync(gitDir).mtimeMs
+		} catch {
+			continue
+		}
+		if (!best || mtimeMs > best.mtimeMs) {
+			best = { taskId, mtimeMs }
+		}
+	}
+
+	return best?.taskId
+}
+
+async function resolveService(options: CheckpointsCliOptions): Promise<{ service: CheckpointService } | { error: string }> {
+	if (!options.workspace) {
+		return { error: "--workspace <path> is required" }
+	}
+	const workspace = path.resolve(options.workspace)
+	const checkpointDir = options.checkpointDir ? path.resolve(options.checkpointDir) : defaultCheckpointDir()
+
+	const taskId = options.taskId ?? findMostRecentTaskId(checkpointDir, workspace)
+	if (!taskId) {
+		return {
+			error: `No checkpoints found for workspace '${workspace}' under '${checkpointDir}'. Has a session run there yet?`,
+		}
+	}
+
+	const service = createCheckpointService({ taskId, workspaceRoot: workspace, checkpointDir })
+	await service.init()
+	return { service }
+}
+
+export async function checkpointsMain(argv: string[]): Promise<number> {
+	const { options, error } = parseCheckpointsArgs(argv)
+	if (error) {
+		process.stderr.write(`headlesscode checkpoints: ${error}\n\n${CHECKPOINTS_USAGE}`)
+		return 2
+	}
+	if (options.help || !options.command) {
+		process.stdout.write(CHECKPOINTS_USAGE)
+		return options.help ? 0 : 2
+	}
+
+	const resolved = await resolveService(options)
+	if ("error" in resolved) {
+		process.stderr.write(`headlesscode checkpoints: ${resolved.error}\n`)
+		return 2
+	}
+	const { service } = resolved
+
+	try {
+		switch (options.command) {
+			case "list": {
+				const entries = await service.list()
+				if (entries.length === 0) {
+					process.stdout.write("(no checkpoints)\n")
+					return 0
+				}
+				for (const entry of entries) {
+					process.stdout.write(`${entry.hash.slice(0, 12)}  ${entry.date}  ${entry.message}\n`)
+				}
+				return 0
+			}
+			case "restore": {
+				const hash = options.commandArgs[0]
+				if (!hash) {
+					process.stderr.write("headlesscode checkpoints restore: a commit hash is required\n")
+					return 2
+				}
+				await service.restore(hash)
+				process.stdout.write(`Restored workspace to checkpoint ${hash}\n`)
+				return 0
+			}
+			case "diff": {
+				const [from, to] = options.commandArgs
+				const changes = await service.diff({ from, to })
+				if (changes.length === 0) {
+					process.stdout.write("(no changes)\n")
+					return 0
+				}
+				for (const change of changes) {
+					process.stdout.write(`--- ${change.paths.relative}\n`)
+					process.stdout.write(`+++ ${change.paths.relative}\n`)
+					process.stdout.write(`  before: ${change.content.before.length} chars\n`)
+					process.stdout.write(`  after:  ${change.content.after.length} chars\n`)
+				}
+				return 0
+			}
+		}
+	} catch (err) {
+		process.stderr.write(
+			`headlesscode checkpoints ${options.command}: ${err instanceof Error ? err.message : String(err)}\n`,
+		)
+		return 1
+	}
+
+	return 2
+}

package/src/checkpoints/service.ts

@@ -0,0 +1,227 @@
+/**
+ * Checkpoint service — thin wrapper around the vendored
+ * `RepoPerTaskCheckpointService` (a shadow git repo, per-task, tracking the
+ * real workspace via `core.worktree`; see
+ * `src/vendor/zoo-code/src/services/checkpoints/`).
+ *
+ * A "checkpoint" is a commit in a hidden shadow git repository — separate
+ * from any real git repo the workspace happens to have — so it never
+ * interferes with the user's own commits/branches/index. Restoring a
+ * checkpoint checks the shadow ref out onto the REAL working tree
+ * (`core.worktree` points at the workspace), so it genuinely reverts files.
+ *
+ * IMPORTANT — the shadow dir must live OUTSIDE the workspace it tracks. Zoo
+ * Code's real shadow dir is always outside any workspace (a VS Code
+ * extension's `globalStorageUri`, e.g. under the user's app-data profile).
+ * Two vendored operations assume that:
+ *   - `stageAll()` (called by `initShadowGit`/`saveCheckpoint`/`getDiff`) runs
+ *     `git add` with `cwd` set to the shadow dir itself. If the shadow dir is
+ *     nested inside the workspace, `git add .`'s `.` pathspec resolves
+ *     relative to that nested `cwd`, not the worktree root — so it only ever
+ *     matches the (nearly empty) shadow dir, and both the "initial commit"
+ *     and every checkpoint silently become empty-tree commits (verified
+ *     empirically). This wrapper patches `stageAll` to `git add -A` (which
+ *     resolves against the repo root regardless of `cwd`) as a belt-and-suspenders
+ *     fix — see the patch below — but that alone does not make nesting safe:
+ *   - `restoreCheckpoint()` runs `git clean -f -d -f` against the worktree.
+ *     If the shadow dir is nested inside the workspace and isn't part of the
+ *     shadow repo's own tracked tree (it never is — a git repo can't usefully
+ *     track its own `.git`), `git clean` treats the entire shadow dir —
+ *     `.git` included — as untracked cruft in the worktree and DELETES IT,
+ *     destroying the checkpoint history it's mid-restore from. Verified
+ *     empirically: a nested shadow dir does not survive a single restore.
+ *
+ * For both reasons, `createCheckpointService` refuses to create a service
+ * whose `checkpointDir` resolves inside `workspaceRoot`, and defaults to a
+ * per-user location outside any workspace: the central store's
+ * `~/.local/share/headlesscode/checkpoints` (mirroring Zoo Code's
+ * `globalStorageUri` design; consolidated here from the old
+ * `~/.headlesscode/checkpoints` — see src/project-store.ts's
+ * migrateCheckpointStore). Each session's shadow repo is further namespaced by
+ * a random `taskId`, so unrelated workspaces/sessions never collide there.
+ *
+ * Failure handling: every method here can throw (init can fail if git isn't
+ * installed, a nested git repo is detected, etc.). This wrapper does NOT
+ * swallow errors — callers (e.g. `HeadlessSession` in `src/engine/loop.ts`)
+ * are expected to wrap calls in try/catch and treat failures as non-fatal,
+ * exactly like the existing Phase 3 memory-recall pattern. The CLI
+ * (`src/checkpoints/cli.ts`) surfaces errors directly since a human is
+ * driving it there.
+ */
+
+import * as path from "node:path"
+
+import { ensureCheckpointMigration, projectStoreRoot } from "../project-store.js"
+import { ShadowCheckpointService } from "../vendor/zoo-code/src/services/checkpoints/ShadowCheckpointService.js"
+import type { CheckpointDiff, CheckpointResult } from "../vendor/zoo-code/src/services/checkpoints/types.js"
+
+/**
+ * Default shadow-git storage root, outside any workspace (see file header).
+ * Lives under the central data store (`~/.local/share/headlesscode/checkpoints`)
+ * — consolidated from the old `~/.headlesscode/checkpoints`, which is migrated
+ * once automatically on first use (see ensureCheckpointMigration).
+ */
+export function defaultCheckpointDir(): string {
+	ensureCheckpointMigration()
+	return path.join(projectStoreRoot(), "checkpoints")
+}
+
+export interface CreateCheckpointServiceOptions {
+	/** Session/task id — the shadow repo lives at `<checkpointDir>/tasks/<taskId>/checkpoints`. */
+	taskId: string
+	/** The real workspace whose files are being tracked (not the shadow dir itself). */
+	workspaceRoot: string
+	/** Base shadow-git storage dir. Default: `defaultCheckpointDir()`. Must NOT be inside workspaceRoot. */
+	checkpointDir?: string
+	/** Optional log sink (default: no-op — callers typically wire this to their own logger). */
+	log?: (message: string) => void
+}
+
+export interface CheckpointLogEntry {
+	hash: string
+	date: string
+	message: string
+}
+
+/** True when `child` is `parent` itself or nested anywhere inside it. */
+function isSameOrInside(parent: string, child: string): boolean {
+	const parentAbs = path.resolve(parent)
+	const childAbs = path.resolve(child)
+	if (parentAbs === childAbs) {
+		return true
+	}
+	const rel = path.relative(parentAbs, childAbs)
+	return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel)
+}
+
+/**
+ * Internal subclass that exposes just enough of `ShadowCheckpointService`'s
+ * protected `git` handle to list commits with metadata (message/date) —
+ * `getCheckpoints()` on the base class only returns bare hashes, which isn't
+ * enough for a human-facing `checkpoints list` CLI. Everything else is
+ * inherited from the vendored class unmodified. Named "RepoPerTask..." to
+ * match the vendored subclass's directory-layout convention
+ * (`shadowDir/tasks/<taskId>/checkpoints`).
+ */
+class RepoPerTaskCheckpointServiceWithLog extends ShadowCheckpointService {
+	static create({ taskId, workspaceRoot, checkpointDir, log }: Required<CreateCheckpointServiceOptions>) {
+		return new RepoPerTaskCheckpointServiceWithLog(
+			taskId,
+			path.join(checkpointDir, "tasks", taskId, "checkpoints"),
+			workspaceRoot,
+			log,
+		)
+	}
+
+	async logEntries(): Promise<CheckpointLogEntry[]> {
+		if (!this.git) {
+			throw new Error("Shadow git repo not initialized")
+		}
+		const log = await this.git.log()
+		// simple-git returns newest-first; checkpoints read more naturally oldest-first.
+		return log.all.map((c) => ({ hash: c.hash, date: c.date, message: c.message })).reverse()
+	}
+}
+
+/**
+ * Patch `ShadowCheckpointService`'s private `stageAll()` to use `git add -A`
+ * instead of the vendored `git add . --ignore-errors` — see the file header
+ * for why. `stageAll` is declared `private` on `ShadowCheckpointService`,
+ * which is a compile-time-only restriction in TypeScript; the method still
+ * exists on the prototype at runtime and can be replaced like any other.
+ * This patches ONE method's implementation on our own subclass's prototype;
+ * every other vendored code path (`initShadowGit`, `saveCheckpoint`,
+ * `restoreCheckpoint`, `getDiff`) is untouched and calls through to this
+ * patched `stageAll` exactly as before. `git add -A` behaves identically to
+ * `git add .` when `cwd` is already the repo root (the expected/enforced
+ * layout here), so this is a no-op behavior change in the supported
+ * configuration and only matters as defense in depth.
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+;(RepoPerTaskCheckpointServiceWithLog.prototype as any).stageAll = async function (
+	this: { log: (message: string) => void },
+	git: { add: (args: string[]) => Promise<unknown> },
+) {
+	try {
+		await git.add(["-A", "--ignore-errors"])
+	} catch (error) {
+		this.log(`[stageAll] failed to add files to git: ${error instanceof Error ? error.message : String(error)}`)
+	}
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+export class CheckpointService {
+	private readonly svc: RepoPerTaskCheckpointServiceWithLog
+	private initialized = false
+
+	constructor(private readonly options: Required<CreateCheckpointServiceOptions>) {
+		this.svc = RepoPerTaskCheckpointServiceWithLog.create(options)
+	}
+
+	get taskId(): string {
+		return this.options.taskId
+	}
+
+	get checkpointsDir(): string {
+		return this.svc.checkpointsDir
+	}
+
+	/** Initialize the shadow git repo (idempotent per process — safe to call once per session). */
+	async init(): Promise<{ created: boolean; duration: number }> {
+		if (this.initialized) {
+			return { created: false, duration: 0 }
+		}
+		const result = await this.svc.initShadowGit()
+		this.initialized = true
+		return result
+	}
+
+	/** Save a checkpoint (commit). Returns undefined when there was nothing to commit (no changes, allowEmpty false). */
+	async save(message: string, options?: { allowEmpty?: boolean }): Promise<CheckpointResult | undefined> {
+		return this.svc.saveCheckpoint(message, options)
+	}
+
+	/** Check the shadow ref out onto the real workspace, reverting files to that checkpoint. */
+	async restore(commitHash: string): Promise<void> {
+		return this.svc.restoreCheckpoint(commitHash)
+	}
+
+	/** Diff between two checkpoints (or a checkpoint and the current working tree when `to` is omitted). */
+	async diff(options: { from?: string; to?: string }): Promise<CheckpointDiff[]> {
+		return this.svc.getDiff(options)
+	}
+
+	/** List checkpoints oldest-first, with commit message + date. */
+	async list(): Promise<CheckpointLogEntry[]> {
+		return this.svc.logEntries()
+	}
+}
+
+/**
+ * Create (but do not initialize) a checkpoint service for a task/session.
+ * Call `.init()` before `.save()`/`.restore()`/`.diff()`/`.list()`.
+ *
+ * Throws synchronously if `checkpointDir` resolves inside `workspaceRoot` —
+ * see the file header for why that combination is unsafe (a restore would
+ * delete the shadow repo, and possibly nothing would ever get staged).
+ */
+export function createCheckpointService(options: CreateCheckpointServiceOptions): CheckpointService {
+	const checkpointDir = options.checkpointDir ?? defaultCheckpointDir()
+
+	if (isSameOrInside(options.workspaceRoot, checkpointDir)) {
+		throw new Error(
+			`Checkpoint dir '${checkpointDir}' is inside the workspace it tracks ('${options.workspaceRoot}'). ` +
+				"The shadow git repo must live outside the workspace (restoring a checkpoint runs " +
+				"`git clean` against the workspace, which would delete a nested shadow repo). " +
+				"Pass a checkpointDir outside the workspace, or omit it to use the default " +
+				`(${defaultCheckpointDir()}).`,
+		)
+	}
+
+	return new CheckpointService({
+		taskId: options.taskId,
+		workspaceRoot: options.workspaceRoot,
+		checkpointDir,
+		log: options.log ?? (() => {}),
+	})
+}