headlesscode 1.0.2

package/src/codeintel/tools.ts

@@ -0,0 +1,280 @@
+/**
+ * OpenAI-format tool schemas for the four code-intelligence tools.
+ *
+ * NEW design work, NOT a port: no code-intelligence tools exist in the
+ * upstream Zoo Code sources this project vendors (the vendored
+ * `search_files` is a regex-based text search, not a symbol resolver). The
+ * schema SHAPE follows the vendored native-tools conventions exactly (see
+ * src/vendor/zoo-code/src/core/prompts/tools/native-tools/codebase_search.ts):
+ * `type: "function"`, `strict: true`, `additionalProperties: false`, a long
+ * prose description with Parameters/Examples, one const per parameter
+ * description. The implementation lives in src/codeintel/.
+ *
+ * Parameter-shape rationale (the spec's "design around what the API needs"):
+ * `getDefinitionAtPosition` / `getReferencesAtPosition` take a character
+ * OFFSET, not a line — so `line` alone is genuinely ambiguous on a line with
+ * several symbols. `character` (1-based column) is the precise answer;
+ * `symbol` (the name) is the cheap alternative the model can supply without
+ * counting columns; with neither, the first identifier on the line is used.
+ */
+
+import type OpenAI from "openai"
+
+// ─── outline ─────────────────────────────────────────────────────────────────
+
+const OUTLINE_DESCRIPTION = `List every top-level (and one level of nested) declaration in a source file — functions, classes, interfaces, types, enums, namespaces, consts, and class/interface members — as one compact line per symbol: "<line> <kind> <signature>". Signatures only, no bodies, so this is a cheap structural map of a file WITHOUT reading it in full.
+
+Use this instead of read_file when you only need a file's structure (symbol names, kinds, and line numbers) to plan where to read or what to call.
+
+Only works on TypeScript/JavaScript source files (.ts/.tsx/.mts/.cts/.js/.jsx). Non-TS files return a clear "not supported" result.
+
+Parameters:
+- path: (required) Path to the source file, relative to the workspace root.
+
+Example: { "path": "src/engine/loop.ts" }`
+
+const OUTLINE_PATH_PARAMETER_DESCRIPTION = `Path to the source file to outline, relative to the workspace root`
+
+export const outlineTool = {
+	type: "function",
+	function: {
+		name: "outline",
+		description: OUTLINE_DESCRIPTION,
+		strict: true,
+		parameters: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: OUTLINE_PATH_PARAMETER_DESCRIPTION,
+				},
+			},
+			required: ["path"],
+			additionalProperties: false,
+		},
+	},
+} satisfies OpenAI.Chat.ChatCompletionTool
+
+// ─── go_to_definition ────────────────────────────────────────────────────────
+
+const GO_TO_DEFINITION_DESCRIPTION = `Resolve the definition of the symbol at a given line of a source file, using the TypeScript compiler's real symbol resolution (not a text search). Returns the real definition location(s) as "<file>:<line>:<column> <kind> <name> — <snippet of the definition line>" — one entry per definition; overloaded functions return ALL definitions. Definitions in vendored/d.ts/node_modules files are returned as their real locations.
+
+Use this to jump straight to where a symbol is actually defined instead of grep-ing for it.
+
+Only works on TypeScript/JavaScript source files. A symbol with no resolvable definition (ambient, any-typed, etc.) returns a clear "could not resolve" message.
+
+Parameters:
+- path: (required) Path to the source file containing the symbol, relative to the workspace root.
+- line: (required) 1-based line number of the symbol.
+- character: (optional) 1-based column of the symbol within the line. Needed when the line has multiple symbols and you want a specific one; omit to use the symbol name or the first identifier on the line.
+- symbol: (optional) The symbol's name, used to disambiguate when the line has several identifiers (e.g. { "path": "src/foo.ts", "line": 12, "symbol": "bar" }). Ignored when character is given.
+
+Example: go to the definition of the call on line 42: { "path": "src/engine/loop.ts", "line": 42, "symbol": "truncateHistory" }`
+
+const GTD_PATH_PARAMETER_DESCRIPTION = `Path to the source file containing the symbol, relative to the workspace root`
+const GTD_LINE_PARAMETER_DESCRIPTION = `1-based line number of the symbol`
+const GTD_CHARACTER_PARAMETER_DESCRIPTION = `1-based column of the symbol within the line (disambiguates on multi-symbol lines); omit to use symbol name or the first identifier on the line`
+const GTD_SYMBOL_PARAMETER_DESCRIPTION = `Symbol name to disambiguate when the line has several identifiers; ignored when character is given`
+
+export const goToDefinitionTool = {
+	type: "function",
+	function: {
+		name: "go_to_definition",
+		description: GO_TO_DEFINITION_DESCRIPTION,
+		strict: true,
+		parameters: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: GTD_PATH_PARAMETER_DESCRIPTION,
+				},
+				line: {
+					type: "integer",
+					description: GTD_LINE_PARAMETER_DESCRIPTION,
+				},
+				character: {
+					type: ["integer", "null"],
+					description: GTD_CHARACTER_PARAMETER_DESCRIPTION,
+				},
+				symbol: {
+					type: ["string", "null"],
+					description: GTD_SYMBOL_PARAMETER_DESCRIPTION,
+				},
+			},
+			required: ["path", "line", "character", "symbol"],
+			additionalProperties: false,
+		},
+	},
+} satisfies OpenAI.Chat.ChatCompletionTool
+
+// ─── find_references ─────────────────────────────────────────────────────────
+
+const FIND_REFERENCES_DESCRIPTION = `Find every real usage site of the symbol at a given line of a source file, using the TypeScript compiler's real reference resolution (not grep). Returns compact "<file>:<line> — <snippet of the line>" entries (the declaration site itself is included), so you can see all callers/uses without reading each file. Results are capped at 50 with a clear "N more references not shown" note — narrow your search to a more specific symbol if you need the rest.
+
+Use this to answer "who uses this symbol / what would this change affect".
+
+Only works on TypeScript/JavaScript source files.
+
+Parameters:
+- path: (required) Path to the source file containing the symbol, relative to the workspace root.
+- line: (required) 1-based line number of the symbol.
+- character: (optional) 1-based column of the symbol within the line; omit to use symbol name or the first identifier on the line.
+- symbol: (optional) Symbol name to disambiguate when the line has several identifiers; ignored when character is given.
+
+Example: { "path": "src/config/mode-models.ts", "line": 12, "symbol": "resolveModelForMode" }`
+
+const FR_PATH_PARAMETER_DESCRIPTION = `Path to the source file containing the symbol, relative to the workspace root`
+const FR_LINE_PARAMETER_DESCRIPTION = `1-based line number of the symbol`
+const FR_CHARACTER_PARAMETER_DESCRIPTION = `1-based column of the symbol within the line (disambiguates on multi-symbol lines); omit to use symbol name or the first identifier on the line`
+const FR_SYMBOL_PARAMETER_DESCRIPTION = `Symbol name to disambiguate when the line has several identifiers; ignored when character is given`
+
+export const findReferencesTool = {
+	type: "function",
+	function: {
+		name: "find_references",
+		description: FIND_REFERENCES_DESCRIPTION,
+		strict: true,
+		parameters: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: FR_PATH_PARAMETER_DESCRIPTION,
+				},
+				line: {
+					type: "integer",
+					description: FR_LINE_PARAMETER_DESCRIPTION,
+				},
+				character: {
+					type: ["integer", "null"],
+					description: FR_CHARACTER_PARAMETER_DESCRIPTION,
+				},
+				symbol: {
+					type: ["string", "null"],
+					description: FR_SYMBOL_PARAMETER_DESCRIPTION,
+				},
+			},
+			required: ["path", "line", "character", "symbol"],
+			additionalProperties: false,
+		},
+	},
+} satisfies OpenAI.Chat.ChatCompletionTool
+
+// ─── rename_symbol ───────────────────────────────────────────────────────────
+
+const RENAME_SYMBOL_DESCRIPTION = `Rename a symbol at a given line of a source file to a new name EVERYWHERE it's used across the workspace, as ONE atomic operation — either every call site updates or none do (on any failure, already-applied edits are rolled back and the error names the failing site). Uses the TypeScript compiler's real reference resolution (the same engine as find_references) to enumerate sites, so it is correct on overloads, re-exports, and aliased imports where a text find/replace would miss or wrongly hit.
+
+Use this instead of composing N separate apply_diff/search_replace edits when you need to rename a symbol used across multiple files — one call replaces the whole read-every-file + edit-every-file round trip.
+
+Only works on TypeScript/JavaScript source files, and refuses (with nothing changed) when any reference site lies outside the workspace root.
+
+Parameters:
+- path: (required) Path to the source file containing the symbol, relative to the workspace root.
+- line: (required) 1-based line number of the symbol.
+- character: (optional) 1-based column of the symbol within the line; omit to use the symbol name or the first identifier on the line.
+- symbol: (optional) The symbol's name, used to disambiguate when the line has several identifiers (e.g. { "path": "src/foo.ts", "line": 12, "symbol": "bar" }). Ignored when character is given.
+- new_name: (required) The new identifier to rename the symbol to (must be a valid TypeScript identifier).
+
+Example: rename the function on line 1 of src/util.ts to "compute": { "path": "src/util.ts", "line": 1, "symbol": "util", "new_name": "compute" }`
+
+const RS_PATH_PARAMETER_DESCRIPTION = `Path to the source file containing the symbol, relative to the workspace root`
+const RS_LINE_PARAMETER_DESCRIPTION = `1-based line number of the symbol`
+const RS_CHARACTER_PARAMETER_DESCRIPTION = `1-based column of the symbol within the line (disambiguates on multi-symbol lines); omit to use the symbol name or the first identifier on the line`
+const RS_SYMBOL_PARAMETER_DESCRIPTION = `Symbol name to disambiguate when the line has several identifiers; ignored when character is given`
+const RS_NEW_NAME_PARAMETER_DESCRIPTION = `The new identifier to rename the symbol to (must be a valid TypeScript identifier)`
+
+export const renameSymbolTool = {
+	type: "function",
+	function: {
+		name: "rename_symbol",
+		description: RENAME_SYMBOL_DESCRIPTION,
+		strict: true,
+		parameters: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: RS_PATH_PARAMETER_DESCRIPTION,
+				},
+				line: {
+					type: "integer",
+					description: RS_LINE_PARAMETER_DESCRIPTION,
+				},
+				character: {
+					type: ["integer", "null"],
+					description: RS_CHARACTER_PARAMETER_DESCRIPTION,
+				},
+				symbol: {
+					type: ["string", "null"],
+					description: RS_SYMBOL_PARAMETER_DESCRIPTION,
+				},
+				new_name: {
+					type: "string",
+					description: RS_NEW_NAME_PARAMETER_DESCRIPTION,
+				},
+			},
+			required: ["path", "line", "character", "symbol", "new_name"],
+			additionalProperties: false,
+		},
+	},
+} satisfies OpenAI.Chat.ChatCompletionTool
+
+// ─── import_graph ────────────────────────────────────────────────────────────
+
+const IMPORT_GRAPH_DESCRIPTION = `Show a file's import relationships: (a) everything it imports, resolved to the REAL file paths the TypeScript compiler resolves them to (relative specifiers like "./foo" resolve to the actual file; bare specifiers like "vscode" resolve to the module the compiler maps them to, e.g. the vendored shim), and (b) everything that imports it (reverse lookup across the whole program). Static analysis of import/export declarations — deterministic and fast (the program-wide import map is cached).
+
+Use this to understand module dependencies before editing, or to find every file that depends on a module you're about to change.
+
+Only works on TypeScript/JavaScript source files.
+
+Parameters:
+- path: (required) Path to the source file, relative to the workspace root.
+
+Example: { "path": "src/tools/executor.ts" }`
+
+const IG_PATH_PARAMETER_DESCRIPTION = `Path to the source file, relative to the workspace root`
+
+export const importGraphTool = {
+	type: "function",
+	function: {
+		name: "import_graph",
+		description: IMPORT_GRAPH_DESCRIPTION,
+		strict: true,
+		parameters: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: IG_PATH_PARAMETER_DESCRIPTION,
+				},
+			},
+			required: ["path"],
+			additionalProperties: false,
+		},
+	},
+} satisfies OpenAI.Chat.ChatCompletionTool
+
+export const CODE_INTEL_TOOLS: readonly OpenAI.Chat.ChatCompletionTool[] = [
+	outlineTool,
+	goToDefinitionTool,
+	findReferencesTool,
+	importGraphTool,
+]
+
+export const CODE_INTEL_TOOL_NAMES: readonly string[] = [
+	outlineTool.function.name,
+	goToDefinitionTool.function.name,
+	findReferencesTool.function.name,
+	importGraphTool.function.name,
+]
+
+/**
+ * The EDIT-capable code-intelligence tool (`rename_symbol`). Deliberately NOT
+ * part of CODE_INTEL_TOOLS: that set is appended for every mode including the
+ * read-only reviewer/QA executors (which never register write tools), whereas
+ * rename_symbol edits files and must only be advertised to executors that
+ * actually register it (the headless executor — see src/tools/executor.ts).
+ * Callers append it explicitly, gated on executor capability.
+ */
+export const RENAME_SYMBOL_TOOL: OpenAI.Chat.ChatCompletionTool = renameSymbolTool

package/src/codemap/build.ts

@@ -0,0 +1,135 @@
+/**
+ * The codemap build pipeline: inventory → fingerprint diff → extract →
+ * write. Deterministic end to end, NO LLM anywhere (issue #17's hard
+ * requirement).
+ *
+ * Fingerprint-aware regeneration: the lock (codemap.lock) stores a sha256
+ * per module path. When the current inventory exactly matches the lock —
+ * same key set, same hash per key — and a codemap.json already exists, the
+ * build writes NOTHING and reports "unchanged". Any diff (edited, added,
+ * deleted file) triggers a FULL regeneration: extraction is fast and cheap,
+ * so per-module incremental regeneration is not worth the complexity for v1
+ * (the issue explicitly allows full regen as long as it's fast).
+ */
+
+import * as fs from "node:fs"
+import * as fsp from "node:fs/promises"
+import * as path from "node:path"
+
+import { inventoryModules } from "./files.js"
+import { codemapFingerprint, contentHash, fingerprintMap, lockMatches } from "./fingerprint.js"
+import { computeEntrypointFlows } from "./flows.js"
+import { renderCodemapHtml } from "./html.js"
+import { codemapDir, codemapHtmlPath, codemapJsonPath, codemapLockPath, loadCodemap, loadLock } from "./lock.js"
+import { extractEdges } from "./extract.js"
+import type { Codemap, CodemapLock, CodemapEdge, ModuleEntry } from "./types.js"
+
+export interface CodemapBuildOptions {
+	workspaceRoot: string
+	/** Skip the fingerprint check and regenerate unconditionally. */
+	force?: boolean
+}
+
+export interface CodemapBuildResult {
+	/** False when the fingerprint check short-circuited (nothing written). */
+	changed: boolean
+	project: string
+	root: string
+	modules: ModuleEntry[]
+	edges: CodemapEdge[]
+	/** Per-module external (unresolved/out-of-workspace) specifiers. */
+	externalDeps: Record<string, string[]>
+	/** Entrypoint-rooted reachability (Phase 2, issue #18). */
+	flows: Record<string, string[]>
+	fingerprint: string
+	jsonPath: string
+	htmlPath: string
+	lockPath: string
+}
+
+/** Resolve the human-readable project name (repo dir basename). */
+export function projectName(workspaceRoot: string): string {
+	return path.basename(path.resolve(workspaceRoot)) || "project"
+}
+
+/**
+ * Build (or refresh) the codemap for a workspace. When nothing changed since
+ * the last build, no files are written and `changed` is false.
+ */
+export async function buildCodemap(options: CodemapBuildOptions): Promise<CodemapBuildResult> {
+	const root = path.resolve(options.workspaceRoot)
+	const project = projectName(root)
+
+	const modules = await inventoryModules(root, contentHash)
+
+	if (!options.force) {
+		const lock = loadLock(root)
+		const existing = loadCodemap(root)
+		if (lockMatches(lock, modules) && existing !== undefined) {
+			return {
+				changed: false,
+				project: existing.project || project,
+				root,
+				modules: existing.modules,
+				edges: existing.edges,
+				externalDeps: existing.externalDeps,
+				// Derived from modules+edges; a map written before flows existed
+				// simply has none until the next real regeneration.
+				flows: existing.flows ?? {},
+				fingerprint: existing.fingerprint,
+				jsonPath: codemapJsonPath(root),
+				htmlPath: codemapHtmlPath(root),
+				lockPath: codemapLockPath(root),
+			}
+		}
+	}
+
+	const { edges, externalDeps } = await extractEdges(root, modules)
+	const flows = computeEntrypointFlows(modules, edges)
+	const fingerprint = codemapFingerprint({ project, modules, edges, externalDeps })
+
+	const codemap: Codemap = {
+		project,
+		root,
+		generatedAt: new Date().toISOString(),
+		fingerprint,
+		modules,
+		edges,
+		externalDeps,
+		flows,
+	}
+	const lock: CodemapLock = {
+		project,
+		fingerprints: fingerprintMap(modules),
+		codemapFingerprint: fingerprint,
+	}
+
+	const dir = codemapDir(root)
+	await fsp.mkdir(dir, { recursive: true })
+	await fsp.writeFile(codemapJsonPath(root), JSON.stringify(codemap, null, 2) + "\n", "utf-8")
+	await fsp.writeFile(codemapLockPath(root), JSON.stringify(lock, null, 2) + "\n", "utf-8")
+	await fsp.writeFile(codemapHtmlPath(root), renderCodemapHtml(codemap), "utf-8")
+
+	return {
+		changed: true,
+		project,
+		root,
+		modules,
+		edges,
+		externalDeps,
+		flows,
+		fingerprint,
+		jsonPath: codemapJsonPath(root),
+		htmlPath: codemapHtmlPath(root),
+		lockPath: codemapLockPath(root),
+	}
+}
+
+/** True when a codemap already exists for the workspace (dashboard 404 helper). */
+export function codemapExists(workspaceRoot: string): boolean {
+	try {
+		return fs.existsSync(codemapJsonPath(workspaceRoot))
+	} catch {
+		return false
+	}
+}

package/src/codemap/cli.ts

@@ -0,0 +1,190 @@
+/**
+ * `headlesscode codemap` subcommand — build/refresh a project's deterministic
+ * module/import map (issue #17).
+ *
+ *   npx tsx src/cli.ts codemap --workspace <path> [--force] [--watch] [--interval-ms <n>]
+ *
+ * Generates codemap.json / codemap.lock / codemap.html into the CENTRAL
+ * per-project data store (~/.local/share/headlesscode/projects/<key>/codemap/ —
+ * same resolution as the codesearch index; worktrees of a repo share it).
+ * Regeneration is fingerprint-aware: an unchanged repo produces NO writes.
+ *
+ * `--watch` turns the command into a long-running poll loop (regenerate on
+ * change, sleep, repeat) — the watcher mode a systemd timer or cron job can
+ * also drive with one-shot invocations instead; see docs/codemap.md.
+ */
+
+import * as path from "node:path"
+import { setTimeout as sleep } from "node:timers/promises"
+
+import { buildCodemap } from "./build.js"
+import { codemapJsonPath } from "./lock.js"
+
+const CODEMAP_USAGE = `headlesscode codemap — build/refresh a project's deterministic codemap
+
+Usage:
+  headlesscode codemap --workspace <path> [--force] [--watch] [--interval-ms <n>]
+
+Options:
+  --workspace <path>  Workspace root to map (required)
+  --force             Regenerate even when the fingerprint lock says nothing changed
+  --watch             Watch mode: poll for changes and regenerate, forever
+                      (Ctrl-C to stop). One-shot runs are what a cron job /
+                      systemd timer should invoke instead.
+  --interval-ms <n>   Watch-mode poll interval in ms (default: 60000)
+  --help              Show this help and exit
+
+The map is written to the CENTRAL per-project store:
+  ~/.local/share/headlesscode/projects/<project-key>/codemap/
+    codemap.json   machine-readable module/edge graph (dashboard-served)
+    codemap.lock   per-module content fingerprints (change detection)
+    codemap.html   self-contained interactive visualizer (open in a browser)
+
+No LLM is involved anywhere in the pipeline — the map is generated
+deterministically from the repo's source files.
+`
+
+interface CodemapCliOptions {
+	workspace?: string
+	force: boolean
+	watch: boolean
+	intervalMs: number
+	help: boolean
+}
+
+export function parseCodemapArgs(argv: string[]): { options: CodemapCliOptions; error?: string } {
+	const options: CodemapCliOptions = { force: false, watch: false, intervalMs: 60_000, help: false }
+	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 value = next()
+				if (value === undefined) {
+					return { options, error: "Missing value for --workspace" }
+				}
+				options.workspace = value
+				break
+			}
+			case "--interval-ms": {
+				const value = next()
+				const n = value === undefined ? Number.NaN : Number(value)
+				if (!Number.isInteger(n) || n <= 0) {
+					return { options, error: "--interval-ms requires a positive integer" }
+				}
+				options.intervalMs = n
+				break
+			}
+			case "--force":
+				options.force = true
+				break
+			case "--watch":
+				options.watch = true
+				break
+			case "--help":
+			case "-h":
+				options.help = true
+				break
+			default:
+				return { options, error: `Unknown argument: ${arg}` }
+		}
+	}
+	return { options }
+}
+
+// `--force` always regenerates (buildCodemap skips the lock check), so only
+// two outcomes exist: a real (re)generation, or an unchanged short-circuit.
+function report(result: Awaited<ReturnType<typeof buildCodemap>>): void {
+	if (result.changed) {
+		process.stdout.write(
+			`codemap: regenerated ${result.modules.length} modules, ${result.edges.length} edges` +
+				` (fp ${result.fingerprint.slice(0, 12)})\n` +
+				`  ${result.jsonPath}\n` +
+				`  ${result.htmlPath}\n`,
+		)
+		return
+	}
+	process.stdout.write(
+		`codemap: unchanged — no writes (${result.modules.length} modules, ${result.edges.length} edges cached, ` +
+			`fp ${result.fingerprint.slice(0, 12)})\n`,
+	)
+}
+
+export async function codemapMain(argv: string[]): Promise<number> {
+	const { options, error } = parseCodemapArgs(argv)
+	if (error) {
+		process.stderr.write(`headlesscode codemap: ${error}\n\n${CODEMAP_USAGE}`)
+		return 2
+	}
+	if (options.help) {
+		process.stdout.write(CODEMAP_USAGE)
+		return 0
+	}
+	if (!options.workspace) {
+		process.stderr.write(`headlesscode codemap: --workspace <path> is required\n\n${CODEMAP_USAGE}`)
+		return 2
+	}
+
+	const workspaceRoot = path.resolve(options.workspace)
+
+	const runOnce = async (): Promise<void> => {
+		const result = await buildCodemap({ workspaceRoot, force: options.force })
+		report(result)
+	}
+
+	if (!options.watch) {
+		try {
+			await runOnce()
+			return 0
+		} catch (err) {
+			process.stderr.write(`headlesscode codemap: ${err instanceof Error ? err.message : String(err)}\n`)
+			return 1
+		}
+	}
+
+	// Watch mode: clean shutdown on SIGINT/SIGTERM (same idiom as watchMain —
+	// see src/watcher/cli.ts).
+	const controller = new AbortController()
+	const onSignal = (): void => controller.abort()
+	process.on("SIGINT", onSignal)
+	process.on("SIGTERM", onSignal)
+
+	process.stdout.write(`codemap: watching ${workspaceRoot} every ${options.intervalMs}ms (Ctrl-C to stop)\n`)
+	try {
+		for (;;) {
+			if (controller.signal.aborted) {
+				break
+			}
+			try {
+				await runOnce()
+			} catch (err) {
+				process.stderr.write(`headlesscode codemap: ${err instanceof Error ? err.message : String(err)}\n`)
+			}
+			await Promise.race([
+				sleep(options.intervalMs),
+				new Promise<void>((resolve) => controller.signal.addEventListener("abort", () => resolve(), { once: true })),
+			])
+		}
+	} finally {
+		process.off("SIGINT", onSignal)
+		process.off("SIGTERM", onSignal)
+	}
+	process.stdout.write(`codemap: stopped\n`)
+	return 0
+}
+
+/** Convenience for tests/scripts: absolute path of the stored codemap.json. */
+export { codemapJsonPath }