headlesscode 1.0.2

package/src/dashboard/cli.ts

@@ -0,0 +1,193 @@
+/**
+ * `headlesscode dashboard` subcommand — a local, auto-refreshing cost/token
+ * dashboard (workstream 3) + live per-session event feed + pause/resume
+ * control (live worker monitoring).
+ *
+ *   npx tsx src/cli.ts dashboard [--port 4390] [--repo <path>]
+ *
+ * Thin dispatch to src/dashboard/server.ts — no logic duplicated here. When
+ * `--repo` is omitted the page still starts but shows no sessions/round data
+ * (the aggregation gracefully degrades — see src/dashboard/aggregate.ts).
+ *
+ * NOTE (Phase 3 scope change): the dashboard is no longer purely read-only —
+ * the page's pause/resume buttons issue state-changing POSTs to the running
+ * worker (see src/dashboard/server.ts's header note). Still local-only +
+ * no-auth (binds 127.0.0.1), but that assumption needs revisiting if this is
+ * ever exposed beyond localhost.
+ */
+
+import { DEFAULT_DASHBOARD_PORT, startDashboardServer } from "./server.js"
+
+const DASHBOARD_USAGE = `headlesscode dashboard — local cost/token dashboard + live worker control
+
+Usage:
+  headlesscode dashboard [--port 4390] [--repo <path>]
+
+Options:
+  --port <n>     Port to listen on (default: 4390, or $HEADLESSCODE_DASHBOARD_PORT)
+  --repo <path>  Repo root to scan for .headlesscode/usage/*.jsonl (own +
+                 .worktrees/*) and .worktrees/.orchestrator-state.json.
+                 Omit to start the page with no data (still useful to confirm
+                 the server runs).
+  --help         Show this help and exit
+
+Environment:
+  HEADLESSCODE_DASHBOARD_TOKEN  Optional bearer token for the control-plane
+                 POST routes (/api/session/start|pause|resume|answer) and
+                 the destructive /api/checkpoints/restore. Unset (default) =
+                 no auth. Local-only tool; see the notes below.
+  HEADLESSCODE_DASHBOARD_SESSION_CLI      Override the CLI invocation
+                 POST /api/session/start spawns (default: "npx tsx
+                 src/cli.ts", resolved from HEADLESSCODE_DASHBOARD_SESSION_REPO_ROOT).
+                 Not a CLI flag deliberately (DashboardServerOptions.cli is a
+                 test-only injection point) — this exists for container
+                 deployments where the dashboard runs from a live bind-mounted
+                 source tree but "npx tsx" has no node_modules there to
+                 resolve against (see docker-compose.headlesscode-local.yml).
+  HEADLESSCODE_DASHBOARD_SESSION_REPO_ROOT  Override the directory a launched
+                 session's CLI runs in (default: process.cwd()). Same
+                 container rationale as above — the dashboard's own cwd may
+                 be a baked image copy while the live source lives elsewhere.
+  HEADLESSCODE_DASHBOARD_WORKTREE_ROOT    Root directory for POST
+                 /api/projects/ensure-worktree's disposable per-project
+                 worktrees. Unset (default) = that endpoint responds 501.
+  HEADLESSCODE_DASHBOARD_WORKTREE_OWNER   chown target (e.g. "1000:1000")
+                 for a newly-created worktree and the ref/admin files
+                 'git worktree add' writes into the source repo's own
+                 .git — read directly by session-launch.ts, not a
+                 startDashboardServer option. Only matters when this
+                 process runs as root (a container's usual default);
+                 unset (default) = skip, leaving those files owned by
+                 whoever ran the dashboard.
+
+Notes:
+  Binds to 127.0.0.1 only — no auth unless HEADLESSCODE_DASHBOARD_TOKEN is
+  set. Never expose this port beyond localhost.
+  IMPORTANT (browser control plane): the "start a session" endpoint spawns
+  the CLI as a detached child that INHERITS this process's environment — it
+  does NOT re-source .env. Export HEADLESSCODE_OPENROUTER_API_KEY (e.g. 'set -a; source
+  .env; set +a') before starting the dashboard, or launched sessions will
+  fail immediately with an OpenRouter auth error.
+`
+
+interface DashboardCliOptions {
+	port: number
+	repo?: string
+	help: boolean
+}
+
+export function parseDashboardArgs(argv: string[]): { options: DashboardCliOptions; error?: string } {
+	const options: DashboardCliOptions = {
+		port: Number(process.env.HEADLESSCODE_DASHBOARD_PORT ?? DEFAULT_DASHBOARD_PORT),
+		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 "--port": {
+				const v = next()
+				const n = v === undefined ? Number.NaN : Number(v)
+				if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+					return { options, error: "--port requires an integer between 1 and 65535" }
+				}
+				options.port = n
+				break
+			}
+			case "--repo": {
+				const v = next()
+				if (v === undefined) {
+					return { options, error: "Missing value for --repo" }
+				}
+				options.repo = v
+				break
+			}
+			case "--help":
+			case "-h":
+				options.help = true
+				break
+			default:
+				return { options, error: `Unknown argument: ${arg}` }
+		}
+	}
+
+	return { options }
+}
+
+export async function dashboardMain(argv: string[]): Promise<number> {
+	const { options, error } = parseDashboardArgs(argv)
+	if (error) {
+		process.stderr.write(`headlesscode dashboard: ${error}\n\n${DASHBOARD_USAGE}`)
+		return 2
+	}
+	if (options.help) {
+		process.stdout.write(DASHBOARD_USAGE)
+		return 0
+	}
+
+	let server: Awaited<ReturnType<typeof startDashboardServer>>
+	try {
+		server = await startDashboardServer({
+			port: options.port,
+			repo: options.repo,
+			token: process.env.HEADLESSCODE_DASHBOARD_TOKEN || undefined,
+			cli: process.env.HEADLESSCODE_DASHBOARD_SESSION_CLI || undefined,
+			repoRoot: process.env.HEADLESSCODE_DASHBOARD_SESSION_REPO_ROOT || undefined,
+			worktreeRoot: process.env.HEADLESSCODE_DASHBOARD_WORKTREE_ROOT || undefined,
+		})
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err)
+		if ((err as NodeJS.ErrnoException)?.code === "EADDRINUSE") {
+			process.stderr.write(
+				`headlesscode dashboard: port ${options.port} is already in use. Pick another with --port <n>.\n`,
+			)
+			return 2
+		}
+		process.stderr.write(`headlesscode dashboard: failed to start: ${message}\n`)
+		return 2
+	}
+
+	process.stdout.write(
+		`[dashboard] listening on http://127.0.0.1:${options.port}${options.repo ? ` (repo: ${options.repo})` : " (no --repo given; page will show no data)"}\n`,
+	)
+
+	// Keep the process alive until interrupted; clean shutdown on SIGINT/SIGTERM.
+	return new Promise<number>((resolve) => {
+		let shuttingDown = false
+		const onSignal = (): void => {
+			// Only the first signal shuts down; a second Ctrl-C while the
+			// server is mid-close is ignored (the process exits on its own
+			// once the listening handle is gone).
+			if (shuttingDown) {
+				return
+			}
+			shuttingDown = true
+			process.stdout.write("\n[dashboard] shutting down\n")
+			process.removeListener("SIGINT", onSignal)
+			process.removeListener("SIGTERM", onSignal)
+			// Release the port: stop accepting new connections and drop
+			// keep-alive sockets so the process can exit. Without close the
+			// listening handle keeps the event loop alive and the port bound.
+			server.close()
+			server.closeAllConnections?.()
+			resolve(0)
+		}
+		process.on("SIGINT", onSignal)
+		process.on("SIGTERM", onSignal)
+	})
+}

package/src/dashboard/codemap.ts

@@ -0,0 +1,44 @@
+/**
+ * Dashboard read-side for the codemap: serves the stored codemap.json /
+ * codemap.html from the CENTRAL per-project store (same resolution the
+ * `headlesscode codemap` CLI writes to — see src/codemap/lock.ts). The
+ * dashboard deliberately does NOT generate the map on request (it's a
+ * deterministic script job, run by the CLI/watcher); it just serves what's
+ * there and gives a clear pointer when nothing has been generated yet.
+ */
+
+import * as fs from "node:fs"
+
+import { codemapHtmlPath, codemapJsonPath } from "../codemap/lock.js"
+
+export interface CodemapFileResult {
+	content: string
+	contentType: string
+}
+
+/** The stored codemap.json content; undefined when not generated yet. */
+export function readCodemapJson(workspaceRoot: string): CodemapFileResult | undefined {
+	return readFileIfPresent(codemapJsonPath(workspaceRoot), "application/json; charset=utf-8")
+}
+
+/** The stored codemap.html content; undefined when not generated yet. */
+export function readCodemapHtml(workspaceRoot: string): CodemapFileResult | undefined {
+	return readFileIfPresent(codemapHtmlPath(workspaceRoot), "text/html; charset=utf-8")
+}
+
+/** The error message + exit hint a route returns when the map doesn't exist yet. */
+export function codemapMissingError(workspaceRoot: string): string {
+	return (
+		`no codemap generated for ${workspaceRoot} yet — run ` +
+		`\`headlesscode codemap --workspace ${workspaceRoot}\` (or start it in --watch mode) to build it.`
+	)
+}
+
+function readFileIfPresent(file: string, contentType: string): CodemapFileResult | undefined {
+	try {
+		const content = fs.readFileSync(file, "utf-8")
+		return { content, contentType }
+	} catch {
+		return undefined
+	}
+}

package/src/dashboard/files.ts

@@ -0,0 +1,121 @@
+/**
+ * Dashboard file-browser backend — thin adapters over the tool executor's
+ * existing, already-tested directory-listing logic.
+ *
+ * The non-negotiable rule here is path safety: every path that crosses the
+ * HTTP surface goes through `resolveWithinWorkspace` / `PathTraversalError`
+ * (src/tools/executor.ts) — the SAME guard the model-facing tools use. A bug
+ * here would be a real directory-traversal vulnerability on a locally-running
+ * HTTP server, so this module deliberately reuses that guard instead of
+ * reimplementing containment checking.
+ *
+ * Listing semantics mirror `list_files` (`listFilesHandler` in
+ * src/tools/executor.ts): a raw `readdir` of the requested directory, no
+ * `.gitignore` filtering (the model-facing tool doesn't filter either — the
+ * gitignore-aware walker lives in src/codesearch/files.ts for the codebase
+ * index, a different surface). Each entry carries its name, type, and size so
+ * the browser can render a tree without extra round-trips.
+ *
+ * Content retrieval mirrors `read_file`'s size discipline: files over
+ * `MAX_RESULT_CHARS` (30k chars, the same cap tool results use to keep model
+ * context bounded) or containing NUL bytes (a strong binary signal) return a
+ * clear "not previewable" response instead of dumping raw bytes into a JSON
+ * response.
+ */
+
+import * as fsp from "node:fs/promises"
+import * as path from "node:path"
+
+import { resolveWithinWorkspace, PathTraversalError, MAX_RESULT_CHARS } from "../tools/executor.js"
+import { DEFAULT_PROTECTED_FILES, isProtectedPath } from "../permissions/protected-files.js"
+
+/** One directory entry, ready for JSON. */
+export interface FileEntry {
+	/** Entry name (basename) — NOT a path, safe to render directly. */
+	name: string
+	type: "file" | "dir"
+	/** Size in bytes (0 for directories). */
+	size: number
+}
+
+/**
+ * List a directory's entries for a workspace. `dir` is a workspace-relative
+ * path (default "."). Throws `PathTraversalError` when the requested path
+ * escapes the workspace — callers (the HTTP layer) translate that to a 400.
+ */
+export async function listWorkspaceDir(workspaceRoot: string, dir: string): Promise<FileEntry[]> {
+	const root = path.resolve(workspaceRoot)
+	const target = resolveWithinWorkspace(root, dir)
+
+	const dirents = await fsp.readdir(target, { withFileTypes: true })
+	const out: FileEntry[] = []
+	for (const ent of dirents) {
+		const abs = path.join(target, ent.name)
+		let size = 0
+		if (ent.isFile()) {
+			try {
+				const st = await fsp.stat(abs)
+				size = st.size
+			} catch {
+				// File vanished between readdir and stat — report size 0.
+			}
+		}
+		out.push({ name: ent.name, type: ent.isDirectory() ? "dir" : "file", size })
+	}
+	// Dirs first, then alphabetical — same ordering list_files uses.
+	out.sort((a, b) => {
+		if (a.type !== b.type) {
+			return a.type === "dir" ? -1 : 1
+		}
+		return a.name.localeCompare(b.name)
+	})
+	return out
+}
+
+/** Result of a file-content read: previewable text, or a clear refusal. */
+export type FileContentResult =
+	| { previewable: true; content: string }
+	| { previewable: false; reason: string }
+
+/**
+ * Read a single file's content for browser preview. Only text files are
+ * previewable: content over `MAX_RESULT_CHARS` or containing NUL bytes (the
+ * strongest cheap binary signal) returns a "not previewable" reason instead
+ * of raw bytes. Throws `PathTraversalError` for escaping paths.
+ *
+ * SEC-7: files matching the protected-file patterns (`.env`, `*.pem`, `*.key`,
+ * `id_rsa*`, etc. — the same defaults `src/permissions/protected-files.ts`
+ * uses to stop the WRITE tools from touching secrets) are refused here too,
+ * unconditionally — the dashboard's GET file-content route must not become a
+ * read side-channel for the exact files the write-side guard protects. This
+ * check is independent of the optional bearer-token gate in server.ts (it
+ * applies even when no token is configured).
+ */
+export async function readWorkspaceFile(workspaceRoot: string, file: string): Promise<FileContentResult> {
+	const root = path.resolve(workspaceRoot)
+	const target = resolveWithinWorkspace(root, file)
+
+	const relFromRoot = path.relative(root, target).replace(/\\/g, "/")
+	if (isProtectedPath(relFromRoot, DEFAULT_PROTECTED_FILES)) {
+		return { previewable: false, reason: "protected file — not previewable via the dashboard (matches a secrets pattern like .env/*.key/*.pem)" }
+	}
+
+	const st = await fsp.stat(target)
+	if (!st.isFile()) {
+		return { previewable: false, reason: "not a file" }
+	}
+	if (st.size > MAX_RESULT_CHARS) {
+		return {
+			previewable: false,
+			reason: `file is ${st.size.toLocaleString()} bytes — over the ${MAX_RESULT_CHARS.toLocaleString()}-char preview cap (same convention as read_file's MAX_RESULT_CHARS)`,
+		}
+	}
+
+	const buf = await fsp.readFile(target)
+	if (buf.includes(0)) {
+		return { previewable: false, reason: "binary file — contains NUL bytes, not text-previewable" }
+	}
+	// UTF-8 decode; replacement chars for invalid sequences are acceptable
+	// here (the NUL check above already caught the common binary case).
+	return { previewable: true, content: buf.toString("utf-8") }
+}