feat(ui): --debug-input flag logs raw keystrokes for support

When users report "Backspace doesn't work" or "paste behaves
weirdly," the fastest way to diagnose is to see the actual bytes
their terminal emits. Running with --debug-input writes each Ink
useInput call (input string + key flags + raw code points) to
~/.codebase/logs/input.log as JSONL.

No-op when the env var is unset, so production users pay nothing.

Author: halfaipg

src/cli.tsx

@@ -25,7 +25,20 @@ interface ParsedRunArgs {
 
 const VALID_OUTPUT_FORMATS = new Set<HeadlessOutputFormat>(["text", "json", "stream-json"]);
 
-const argv = process.argv.slice(2);
+const rawArgv = process.argv.slice(2);
+
+// Strip flags consumed at the top-level dispatcher before subcommand
+// matching. `--debug-input` is one of those: it sets an env var that
+// the Input component picks up, then disappears from argv so it can't
+// confuse downstream parsers.
+const argv: string[] = [];
+for (const a of rawArgv) {
+	if (a === "--debug-input") {
+		process.env.CODEBASE_DEBUG_INPUT = "1";
+		continue;
+	}
+	argv.push(a);
+}
 
 if (argv[0] === "--version" || argv[0] === "-v") {
 	process.stdout.write(`${readPackageVersion()}\n`);
@@ -132,6 +145,10 @@ function printHelp(): void {
 			"  codebase --version           print version and exit",
 			"  codebase --help              show this message",
 			"",
+			"Diagnostics:",
+			"  --debug-input                log every keystroke to ~/.codebase/logs/input.log",
+			"                               (use when reporting a keyboard/terminal issue)",
+			"",
 			"More: https://github.com/codebase-foundation/codebase-cli",
 			"",
 		].join("\n"),

src/ui/Input.tsx

@@ -15,6 +15,7 @@ import {
 	undo,
 	yank,
 } from "./input-state.js";
+import { logInputEvent } from "./debug-input.js";
 import { completePath, findAtTokenAt } from "./path-complete.js";
 
 export interface SlashCommandSuggestion {
@@ -120,6 +121,10 @@ export function Input({ disabled, onSubmit, onAbort, commands, history, cwd }: I
 	const clampedSuggestionIdx = Math.min(suggestionIdx, Math.max(0, suggestions.length - 1));
 
 	useInput((input, key) => {
+		// First thing — log every keystroke when --debug-input is on, so
+		// we can diagnose "key X doesn't work" reports from real terminals.
+		logInputEvent(input, key);
+
 		if (key.ctrl && input === "c") {
 			onAbort?.();
 			return;

src/ui/debug-input.ts

@@ -0,0 +1,72 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Opt-in raw-input logger. When CODEBASE_DEBUG_INPUT=1 (set by the
+ * `--debug-input` flag), every keystroke Ink hands us is appended to
+ * `~/.codebase/logs/input.log` as one JSON line. We can ask a user
+ * with a wedged keyboard ("backspace doesn't work", "weird chars on
+ * paste") to share that file and see exactly what bytes their
+ * terminal emitted.
+ *
+ * No-op when the env var is unset, so production users pay nothing.
+ */
+
+interface InkKeyShape {
+	readonly leftArrow?: boolean;
+	readonly rightArrow?: boolean;
+	readonly upArrow?: boolean;
+	readonly downArrow?: boolean;
+	readonly return?: boolean;
+	readonly escape?: boolean;
+	readonly ctrl?: boolean;
+	readonly shift?: boolean;
+	readonly tab?: boolean;
+	readonly backspace?: boolean;
+	readonly delete?: boolean;
+	readonly pageDown?: boolean;
+	readonly pageUp?: boolean;
+	readonly meta?: boolean;
+}
+
+let logPath: string | null = null;
+let warned = false;
+
+export function isDebugInputEnabled(): boolean {
+	return process.env.CODEBASE_DEBUG_INPUT === "1";
+}
+
+function resolveLogPath(): string {
+	if (logPath) return logPath;
+	const dir = join(homedir(), ".codebase", "logs");
+	try {
+		mkdirSync(dir, { recursive: true });
+	} catch {
+		// The fs error is non-fatal; the appendFileSync below will throw
+		// the same problem and we'll surface it once via the `warned`
+		// guard, not on every keystroke.
+	}
+	logPath = join(dir, "input.log");
+	return logPath;
+}
+
+export function logInputEvent(input: string, key: InkKeyShape): void {
+	if (!isDebugInputEnabled()) return;
+	try {
+		const entry = {
+			t: new Date().toISOString(),
+			// Show the actual code points so a stray \x7f or \x1b is visible.
+			input,
+			codes: Array.from(input).map((ch) => ch.charCodeAt(0)),
+			key,
+		};
+		appendFileSync(resolveLogPath(), `${JSON.stringify(entry)}\n`);
+	} catch (err) {
+		if (warned) return;
+		warned = true;
+		process.stderr.write(
+			`\n[debug-input] failed to write log: ${err instanceof Error ? err.message : String(err)}\n`,
+		);
+	}
+}