@oh-my-pi/pi-coding-agent 17.2.13 → 17.2.15

package/src/cleanse/index.ts

@@ -1,10 +1,11 @@
 import { getProjectDir, sanitizeText } from "@oh-my-pi/pi-utils";
+import { pickCleanseTarget, promptCleanseRequest } from "../cli/cleanse-picker";
+import { createProgressReporter } from "../cli/progress-reporter";
 import { shortenPath } from "../tools/render-utils";
-import { type CleanseAgentRuntime, createCleanseAgentRuntime } from "./agent";
+import { type CleanseAgentHooks, type CleanseAgentRuntime, createCleanseAgentRuntime } from "./agent";
 import { groupDiagnosticsByFile } from "./balance";
-import { discoverCleanseDiagnosticSuite } from "./checkers";
+import { buildCustomCleanseSuite, type CleanseDiagnosticSuite, discoverCleanseDiagnosticSuite } from "./checkers";
 import { runCleanseLoop } from "./loop";
-import { createCleanseProgressReporter } from "./progress";
 import type { CleanseAgentOutcome, CleanseAssignment, CleanseDiagnosticReport, CleanseLoopResult } from "./types";
 
 const DEFAULT_MODEL = "@smol";
@@ -15,6 +16,10 @@ export interface CleanseCommandOptions {
 	maxAgents?: number;
 	model?: string;
 	includeTests?: boolean;
+	/** Free-form description handed to a discovery agent instead of built-in checker discovery. */
+	request?: string;
+	/** Run every discovered checker without the interactive picker. */
+	all?: boolean;
 }
 
 /** Observable completion state returned to the CLI adapter. */
@@ -27,7 +32,7 @@ export interface CleanseCommandResult {
 
 /** Detect project diagnostics, dispatch one bounded repair batch, and verify it. */
 export async function runCleanseCommand(options: CleanseCommandOptions = {}): Promise<CleanseCommandResult> {
-	const maxAgents = options.maxAgents ?? 8;
+	const maxAgents = options.maxAgents ?? 32;
 	if (!Number.isInteger(maxAgents) || maxAgents <= 0) throw new Error("--agents must be a positive integer");
 	const model = options.model?.trim() || DEFAULT_MODEL;
 	const cwd = getProjectDir();
@@ -37,7 +42,7 @@ export async function runCleanseCommand(options: CleanseCommandOptions = {}): Pr
 	process.once("SIGTERM", abort);
 	let runtime: CleanseAgentRuntime | undefined;
 	let loopResult: CleanseLoopResult | undefined;
-	const progress = createCleanseProgressReporter();
+	const progress = createProgressReporter("Repairing");
 	const interactiveFailures: CleanseAgentOutcome[] = [];
 	let interactiveFailuresPrinted = false;
 	const printInteractiveFailures = (): void => {
@@ -45,15 +50,85 @@ export async function runCleanseCommand(options: CleanseCommandOptions = {}): Pr
 		interactiveFailuresPrinted = true;
 		for (const outcome of interactiveFailures) printAgentOutcome(outcome);
 	};
+	const hooks: CleanseAgentHooks = {
+		onStart(name, assignment) {
+			if (progress.interactive) return;
+			process.stdout.write(`[start] ${name}: ${formatAssignmentFiles(assignment)} (weight ${assignment.weight})\n`);
+		},
+		onFinish(outcome) {
+			progress.complete();
+			if (progress.interactive) {
+				if (!outcome.success) interactiveFailures.push(outcome);
+				return;
+			}
+			printAgentOutcome(outcome);
+		},
+	};
+	const ensureRuntime = async (): Promise<CleanseAgentRuntime> => {
+		if (runtime) return runtime;
+		process.stdout.write(`Resolving model ${model}...\n`);
+		runtime = await createCleanseAgentRuntime({ cwd, model, hooks });
+		process.stdout.write(`Model: ${runtime.model}\nSession: ${shortenPath(runtime.sessionFile)}\n`);
+		return runtime;
+	};
 
 	try {
-		process.stdout.write("Detecting configured project checkers...\n");
-		const suite = await discoverCleanseDiagnosticSuite(cwd, { includeTests: options.includeTests });
-		if (suite.checkCount === 0) {
-			const report: CleanseDiagnosticReport = { checks: [], diagnostics: [], skipped: [...suite.skipped] };
+		let request = options.request?.trim() || undefined;
+		let suite: CleanseDiagnosticSuite | undefined;
+		if (!request) {
+			process.stdout.write("Detecting configured project checkers...\n");
+			suite = await discoverCleanseDiagnosticSuite(cwd, { includeTests: options.includeTests });
+			const interactive = options.all !== true && process.stdin.isTTY === true && process.stdout.isTTY === true;
+			if (interactive) {
+				if (suite.checkers.length > 0) {
+					const choice = await pickCleanseTarget(suite.checkers);
+					if (choice.kind === "cancel") {
+						process.stderr.write("Cleanse cancelled.\n");
+						return {
+							exitCode: 130,
+							status: "cancelled",
+							report: { checks: [], diagnostics: [], skipped: [...suite.skipped] },
+						};
+					}
+					if (choice.kind === "checker") suite.select([choice.id]);
+					if (choice.kind === "request") {
+						request = choice.request;
+						suite = undefined;
+					}
+				} else {
+					printSkippedChecks({ checks: [], diagnostics: [], skipped: [...suite.skipped] });
+					process.stdout.write("No supported checker with an available executable was found.\n");
+					const answer = await promptCleanseRequest();
+					if (answer === null) {
+						return {
+							exitCode: 1,
+							status: "unsupported",
+							report: { checks: [], diagnostics: [], skipped: [...suite.skipped] },
+						};
+					}
+					request = answer;
+					suite = undefined;
+				}
+			}
+		}
+		if (request) {
+			const activeRuntime = await ensureRuntime();
+			process.stdout.write(`Discovering checkers for "${request}"...\n`);
+			const specs = await activeRuntime.discoverCheckers(request, abortController.signal);
+			suite = await buildCustomCleanseSuite(cwd, specs);
+			for (const checker of suite.checkers) {
+				process.stdout.write(`[checker] ${checker.label}: ${checker.command}\n`);
+			}
+		}
+		if (!suite || suite.checkers.length === 0) {
+			const report: CleanseDiagnosticReport = { checks: [], diagnostics: [], skipped: [...(suite?.skipped ?? [])] };
 			printSkippedChecks(report);
-			process.stderr.write("No supported checker with an available executable was found.\n");
-			return { exitCode: 1, status: "unsupported", report };
+			process.stderr.write(
+				request
+					? "Checker discovery produced no runnable command.\n"
+					: "No supported checker with an available executable was found.\n",
+			);
+			return { exitCode: 1, status: "unsupported", report, sessionFile: runtime?.sessionFile };
 		}
 		const initialReport = await suite.run(abortController.signal);
 		printCheckReport(initialReport);
@@ -61,7 +136,7 @@ export async function runCleanseCommand(options: CleanseCommandOptions = {}): Pr
 			process.stdout.write(
 				`Clean: ${initialReport.checks.length} checker${initialReport.checks.length === 1 ? "" : "s"} passed.\n`,
 			);
-			return { exitCode: 0, status: "clean", report: initialReport };
+			return { exitCode: 0, status: "clean", report: initialReport, sessionFile: runtime?.sessionFile };
 		}
 
 		const assignments = groupDiagnosticsByFile(initialReport.diagnostics);
@@ -70,33 +145,12 @@ export async function runCleanseCommand(options: CleanseCommandOptions = {}): Pr
 		process.stdout.write(
 			`Found ${initialReport.diagnostics.length} diagnostic${initialReport.diagnostics.length === 1 ? "" : "s"} across ${fileCount} file${fileCount === 1 ? "" : "s"}; launching ${agentCount} subagent${agentCount === 1 ? "" : "s"}.\n`,
 		);
-		process.stdout.write(`Resolving model ${model}...\n`);
-		const activeRuntime = await createCleanseAgentRuntime({
-			cwd,
-			model,
-			hooks: {
-				onStart(name, assignment) {
-					if (progress.interactive) return;
-					process.stdout.write(
-						`[start] ${name}: ${formatAssignmentFiles(assignment)} (weight ${assignment.weight})\n`,
-					);
-				},
-				onFinish(outcome) {
-					progress.complete();
-					if (progress.interactive) {
-						if (!outcome.success) interactiveFailures.push(outcome);
-						return;
-					}
-					printAgentOutcome(outcome);
-				},
-			},
-		});
-		runtime = activeRuntime;
-		process.stdout.write(`Model: ${activeRuntime.model}\nSession: ${shortenPath(activeRuntime.sessionFile)}\n`);
+		const activeRuntime = await ensureRuntime();
+		const activeSuite = suite;
 		loopResult = await runCleanseLoop(
 			{ maxAgents, initialReport, signal: abortController.signal },
 			{
-				collect: signal => suite.run(signal),
+				collect: signal => activeSuite.run(signal),
 				dispatch: (batch, wave, report, signal) => activeRuntime.dispatch(batch, wave, report, signal),
 				onWave(_wave, batch) {
 					process.stdout.write(

package/src/cleanse/parsers.ts

@@ -3,26 +3,40 @@ import { isRecord, sanitizeText } from "@oh-my-pi/pi-utils";
 import type { CleanseDiagnostic, CleanseSeverity } from "./types";
 
 /** Machine and fallback output formats understood by cleanse. */
-export type CleanseParserKind =
-	| "rust"
-	| "rust-test"
-	| "go"
-	| "go-test"
-	| "ruff"
-	| "pyright"
-	| "eslint"
-	| "biome"
-	| "rubocop"
-	| "phpstan"
-	| "psalm"
-	| "swiftlint"
-	| "dart"
-	| "credo"
-	| "shellcheck"
-	| "hlint"
-	| "terraform"
-	| "tflint"
-	| "generic";
+export const CLEANSE_PARSER_KINDS = [
+	"rust",
+	"rust-test",
+	"go",
+	"go-test",
+	"staticcheck",
+	"golangci",
+	"ruff",
+	"pyright",
+	"mypy",
+	"pylint",
+	"flake8",
+	"ty",
+	"eslint",
+	"biome",
+	"oxlint",
+	"deno-lint",
+	"stylelint",
+	"rubocop",
+	"phpstan",
+	"psalm",
+	"swiftlint",
+	"dart",
+	"credo",
+	"shellcheck",
+	"hlint",
+	"terraform",
+	"tflint",
+	"actionlint",
+	"generic",
+] as const;
+
+/** One machine or fallback output format understood by cleanse. */
+export type CleanseParserKind = (typeof CLEANSE_PARSER_KINDS)[number];
 
 /** Captured checker process output passed to a format parser. */
 export interface CleanseParserInput {
@@ -63,14 +77,32 @@ export function parseCleanseDiagnostics(kind: CleanseParserKind, input: CleanseP
 				return parseGo(input);
 			case "go-test":
 				return parseGoTest(input);
+			case "staticcheck":
+				return parseStaticcheck(input);
+			case "golangci":
+				return parseGolangci(input);
 			case "ruff":
 				return parseRuff(input);
 			case "pyright":
 				return parsePyright(input);
+			case "mypy":
+				return parseGeneric(input);
+			case "pylint":
+				return parsePylint(input);
+			case "flake8":
+				return parseFlake8(input);
+			case "ty":
+				return parseTy(input);
 			case "eslint":
 				return parseEslint(input);
 			case "biome":
 				return parseBiome(input);
+			case "oxlint":
+				return parseUnixFormat(input);
+			case "deno-lint":
+				return parseDenoLint(input);
+			case "stylelint":
+				return parseStylelint(input);
 			case "rubocop":
 				return parseRubocop(input);
 			case "phpstan":
@@ -91,6 +123,8 @@ export function parseCleanseDiagnostics(kind: CleanseParserKind, input: CleanseP
 				return parseTerraform(input);
 			case "tflint":
 				return parseTflint(input);
+			case "actionlint":
+				return parseActionlint(input);
 			case "generic":
 				return parseGeneric(input);
 		}
@@ -326,6 +360,44 @@ function parseGoTest(input: CleanseParserInput): CleanseDiagnostic[] {
 	return diagnostics.length > 0 ? diagnostics : parseGeneric(input);
 }
 
+function parseStaticcheck(input: CleanseParserInput): CleanseDiagnostic[] {
+	const diagnostics: CleanseDiagnostic[] = [];
+	for (const value of allJsonValues(input)) {
+		const record = toRecord(value);
+		const location = nestedRecord(record, "location");
+		const end = nestedRecord(record, "end");
+		addDiagnostic(diagnostics, input, {
+			file: stringField(location, "file"),
+			line: numberField(location, "line"),
+			column: numberField(location, "column"),
+			endLine: numberField(end, "line"),
+			endColumn: numberField(end, "column"),
+			code: stringField(record, "code"),
+			severity: stringField(record, "severity") ?? "warning",
+			message: stringField(record, "message"),
+		});
+	}
+	return diagnostics;
+}
+
+function parseGolangci(input: CleanseParserInput): CleanseDiagnostic[] {
+	const diagnostics: CleanseDiagnostic[] = [];
+	const text = sanitizeText(`${input.stdout}\n${input.stderr}`);
+	for (const line of text.split("\n")) {
+		const match = /^(.+?):(\d+):(\d+):\s+(.*?)\s+\(([A-Za-z0-9_-]+)\)$/.exec(line.trim());
+		if (!match) continue;
+		addDiagnostic(diagnostics, input, {
+			file: match[1],
+			line: Number.parseInt(match[2], 10),
+			column: Number.parseInt(match[3], 10),
+			code: match[5],
+			severity: "warning",
+			message: match[4],
+		});
+	}
+	return diagnostics;
+}
+
 function parseRuff(input: CleanseParserInput): CleanseDiagnostic[] {
 	const diagnostics: CleanseDiagnostic[] = [];
 	for (const root of allJsonValues(input)) {
@@ -374,6 +446,62 @@ function parsePyright(input: CleanseParserInput): CleanseDiagnostic[] {
 	return diagnostics;
 }
 
+function parsePylint(input: CleanseParserInput): CleanseDiagnostic[] {
+	const diagnostics: CleanseDiagnostic[] = [];
+	for (const root of allJsonValues(input)) {
+		for (const value of toArray(root)) {
+			const record = toRecord(value);
+			addDiagnostic(diagnostics, input, {
+				file: stringField(record, "path"),
+				line: numberField(record, "line"),
+				column: zeroBased(numberField(record, "column")),
+				endLine: numberField(record, "endLine"),
+				endColumn: zeroBased(numberField(record, "endColumn")),
+				code: stringField(record, "symbol") ?? stringField(record, "message-id"),
+				severity: stringField(record, "type"),
+				message: stringField(record, "message"),
+			});
+		}
+	}
+	return diagnostics;
+}
+
+function parseFlake8(input: CleanseParserInput): CleanseDiagnostic[] {
+	const diagnostics: CleanseDiagnostic[] = [];
+	const text = sanitizeText(`${input.stdout}\n${input.stderr}`);
+	for (const line of text.split("\n")) {
+		const match = /^(.+?):(\d+):(\d+):\s+([A-Z]+\d+)\s+(.*)$/.exec(line.trim());
+		if (!match) continue;
+		addDiagnostic(diagnostics, input, {
+			file: match[1],
+			line: Number.parseInt(match[2], 10),
+			column: Number.parseInt(match[3], 10),
+			code: match[4],
+			severity: match[4].startsWith("F") || match[4].startsWith("E9") ? "error" : "warning",
+			message: match[5],
+		});
+	}
+	return diagnostics;
+}
+
+function parseTy(input: CleanseParserInput): CleanseDiagnostic[] {
+	const diagnostics: CleanseDiagnostic[] = [];
+	const text = sanitizeText(`${input.stdout}\n${input.stderr}`);
+	for (const line of text.split("\n")) {
+		const match = /^(.+?):(\d+):(\d+):\s+(error|warning|info)\[([^\]]+)\]\s+(.*)$/.exec(line.trim());
+		if (!match) continue;
+		addDiagnostic(diagnostics, input, {
+			file: match[1],
+			line: Number.parseInt(match[2], 10),
+			column: Number.parseInt(match[3], 10),
+			code: match[5],
+			severity: match[4],
+			message: match[6],
+		});
+	}
+	return diagnostics;
+}
+
 function zeroBased(value: number | undefined): number | undefined {
 	return value === undefined ? undefined : value + 1;
 }
@@ -424,6 +552,83 @@ function parseBiome(input: CleanseParserInput): CleanseDiagnostic[] {
 	return diagnostics;
 }
 
+function parseUnixFormat(input: CleanseParserInput): CleanseDiagnostic[] {
+	const diagnostics: CleanseDiagnostic[] = [];
+	const text = sanitizeText(`${input.stdout}\n${input.stderr}`);
+	for (const line of text.split("\n")) {
+		const match = /^(.+?):(\d+):(\d+):\s+(.*?)\s+\[(Error|Warning)\/([^\]]+)\]$/i.exec(line.trim());
+		if (!match) continue;
+		addDiagnostic(diagnostics, input, {
+			file: match[1],
+			line: Number.parseInt(match[2], 10),
+			column: Number.parseInt(match[3], 10),
+			code: match[6],
+			severity: match[5],
+			message: match[4],
+		});
+	}
+	return diagnostics;
+}
+
+function parseDenoLint(input: CleanseParserInput): CleanseDiagnostic[] {
+	const diagnostics: CleanseDiagnostic[] = [];
+	for (const root of allJsonValues(input)) {
+		const record = toRecord(root);
+		if (!record) continue;
+		for (const value of toArray(record.diagnostics)) {
+			const entry = toRecord(value);
+			const range = nestedRecord(entry, "range");
+			const start = nestedRecord(range, "start");
+			const end = nestedRecord(range, "end");
+			addDiagnostic(diagnostics, input, {
+				file: stringField(entry, "filename"),
+				line: numberField(start, "line"),
+				column: zeroBased(numberField(start, "col")),
+				endLine: numberField(end, "line"),
+				endColumn: zeroBased(numberField(end, "col")),
+				code: stringField(entry, "code"),
+				severity: "warning",
+				message: stringField(entry, "message"),
+				suggestion: stringField(entry, "hint"),
+			});
+		}
+		for (const value of toArray(record.errors)) {
+			const entry = toRecord(value);
+			addDiagnostic(diagnostics, input, {
+				file: stringField(entry, "file_path"),
+				severity: "error",
+				message: stringField(entry, "message"),
+			});
+		}
+	}
+	return diagnostics;
+}
+
+function parseStylelint(input: CleanseParserInput): CleanseDiagnostic[] {
+	const diagnostics: CleanseDiagnostic[] = [];
+	for (const root of allJsonValues(input)) {
+		for (const value of toArray(root)) {
+			const record = toRecord(value);
+			const source = stringField(record, "source");
+			if (!source) continue;
+			for (const warning of toArray(record?.warnings)) {
+				const entry = toRecord(warning);
+				addDiagnostic(diagnostics, input, {
+					file: source,
+					line: numberField(entry, "line"),
+					column: numberField(entry, "column"),
+					endLine: numberField(entry, "endLine"),
+					endColumn: numberField(entry, "endColumn"),
+					code: stringField(entry, "rule"),
+					severity: stringField(entry, "severity"),
+					message: stringField(entry, "text"),
+				});
+			}
+		}
+	}
+	return diagnostics;
+}
+
 function parseRubocop(input: CleanseParserInput): CleanseDiagnostic[] {
 	const diagnostics: CleanseDiagnostic[] = [];
 	for (const rootValue of allJsonValues(input)) {
@@ -654,6 +859,24 @@ function parseTflint(input: CleanseParserInput): CleanseDiagnostic[] {
 	return diagnostics;
 }
 
+function parseActionlint(input: CleanseParserInput): CleanseDiagnostic[] {
+	const diagnostics: CleanseDiagnostic[] = [];
+	for (const root of allJsonValues(input)) {
+		for (const value of toArray(root)) {
+			const record = toRecord(value);
+			addDiagnostic(diagnostics, input, {
+				file: stringField(record, "filepath"),
+				line: numberField(record, "line"),
+				column: numberField(record, "column"),
+				code: stringField(record, "kind"),
+				severity: "error",
+				message: stringField(record, "message"),
+			});
+		}
+	}
+	return diagnostics;
+}
+
 function parseGeneric(input: CleanseParserInput): CleanseDiagnostic[] {
 	const diagnostics: CleanseDiagnostic[] = [];
 	const text = sanitizeText(`${input.stdout}\n${input.stderr}`);

package/src/cleanse/prompts/discovery.md

@@ -0,0 +1,74 @@
+<critical>
+- NEVER edit project files — read-and-verify discovery only.
+- MUST run each proposed command once.
+- Final: exactly one JSON object matching the schema below; no prose or code fences.
+</critical>
+
+# Checker Discovery
+
+User requested `omp cleanse` detect and repair: **{{request}}**
+
+Identify project command(s) surfacing exactly these diagnostics for orchestrator execution, output parsing, and repair-agent dispatch.
+
+<workflow>
+1. Inspect manifests, configs, lockfiles, and scripts for relevant tooling.
+2. Determine exact command and working directory. Prefer project-local binaries (`node_modules/.bin`, `.venv/bin`, wrappers like `gradlew`) over global tools.
+3. Prefer machine-readable output matching a known parser below. Otherwise use gcc-style `file:line:col: severity: message` output and parser `generic`.
+4. Run once: verify execution and output matches the chosen parser. Non-zero exit with parseable diagnostics: fine; crash or usage error: not.
+5. If multiple commands cover the request, return one entry per command.
+</workflow>
+
+## Known parsers
+
+|id|expected output|
+|---|---|
+|`rust`|`cargo … --message-format=json`|
+|`rust-test`|`cargo test … --message-format=json`|
+|`go`|`go vet -json`|
+|`go-test`|`go test -json`|
+|`staticcheck`|`staticcheck -f json`|
+|`golangci`|golangci-lint default text output|
+|`ruff`|`ruff check --output-format=json`|
+|`pyright`|`pyright`/`basedpyright` `--outputjson`|
+|`mypy`|mypy default text output|
+|`pylint`|`pylint --output-format=json`|
+|`flake8`|flake8 default text output|
+|`ty`|`ty check --output-format concise`|
+|`eslint`|`eslint --format=json`|
+|`biome`|`biome check --reporter=json`|
+|`oxlint`|unix-format lines `file:line:col: message [Error/rule]` (`--format=unix`)|
+|`deno-lint`|`deno lint --json`|
+|`stylelint`|`stylelint --formatter json`|
+|`rubocop`|`rubocop --format json`|
+|`phpstan`|`phpstan analyse --error-format=json`|
+|`psalm`|`psalm --output-format=json`|
+|`swiftlint`|`swiftlint lint --reporter json`|
+|`dart`|`dart analyze --format machine`|
+|`credo`|`mix credo --format=json`|
+|`shellcheck`|`shellcheck --format=json1`|
+|`hlint`|`hlint --json`|
+|`terraform`|`terraform validate -json`|
+|`tflint`|`tflint --format=json`|
+|`actionlint`|actionlint with its JSON `-format` template|
+|`generic`|gcc-style `file:line:col: severity: message` lines (tsc/tsgo `--pretty false`, mypy, clang, zig, MSVC-style)|
+
+## Output schema
+
+```json
+{
+	"checkers": [
+		{
+			"label": "tsc (packages/app)",
+			"language": "TypeScript",
+			"cwd": "packages/app",
+			"command": ["tsc", "--noEmit", "--pretty", "false"],
+			"parser": "generic"
+		}
+	]
+}
+```
+
+- `command`: argv array; first element: binary name or project-relative path. NEVER shell-wrap.
+- `cwd`: project-relative working directory; omit for project root.
+- `parser`: known parser id; omit for `generic`.
+- Return `"checkers": []` only if nothing in this project produces the requested diagnostics.

package/src/cli/args.ts

@@ -48,6 +48,7 @@ export interface Args {
 	serviceTier?: ServiceTierOpenAISettingValue;
 	hideThinking?: boolean;
 	advisor?: boolean;
+	externalThinking?: boolean;
 	continue?: boolean;
 	resume?: string | true;
 	fromClaude?: boolean;
@@ -255,6 +256,8 @@ export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { ty
 			result.hideThinking = true;
 		} else if (arg === "--advisor") {
 			result.advisor = true;
+		} else if (arg === "--external-thinking") {
+			result.externalThinking = true;
 		} else if (arg === "--prewalk") {
 			result.prewalk = true;
 		} else if (arg === "--no-prewalk") {

package/src/cli/cleanse-picker.ts

@@ -0,0 +1,86 @@
+/**
+ * Standalone TUI pickers for `omp cleanse`.
+ *
+ * Mirrors {@link ./setup-model-picker.ts}: one-shot {@link TUI} instances over a
+ * {@link SelectList} or {@link Input}, resolved on select/submit/cancel and torn
+ * down immediately so the command can keep writing plain stdout afterwards.
+ */
+import { Input, ProcessTerminal, type SelectItem, SelectList, TUI } from "@oh-my-pi/pi-tui";
+import type { CleanseCheckerDescriptor } from "../cleanse/checkers";
+import { getSelectListTheme } from "../modes/theme/theme";
+
+/** Outcome of the interactive cleanse target picker. */
+export type CleanseTargetChoice =
+	| { kind: "all" }
+	| { kind: "checker"; id: string }
+	| { kind: "request"; request: string }
+	| { kind: "cancel" };
+
+/** Pick between running every discovered checker, one specific checker, or a free-form request. */
+export async function pickCleanseTarget(checkers: readonly CleanseCheckerDescriptor[]): Promise<CleanseTargetChoice> {
+	const items: SelectItem[] = [
+		{
+			value: "all",
+			label: `Run all ${checkers.length} discovered checker${checkers.length === 1 ? "" : "s"}`,
+		},
+		...checkers.map(checker => ({
+			value: `checker:${checker.id}`,
+			label: checker.label,
+			description: `${checker.language} — ${checker.command}`,
+		})),
+		{
+			value: "request",
+			label: "Describe what to fix…",
+			description: "A discovery agent figures out the command to run",
+		},
+	];
+	const selection = await selectOne("Select what to cleanse:", items);
+	if (selection === null) return { kind: "cancel" };
+	if (selection === "all") return { kind: "all" };
+	if (selection === "request") {
+		const request = await promptCleanseRequest();
+		return request === null ? { kind: "cancel" } : { kind: "request", request };
+	}
+	return { kind: "checker", id: selection.slice("checker:".length) };
+}
+
+/** One-shot text prompt for a free-form cleanse request; `null` when cancelled or left empty. */
+export async function promptCleanseRequest(): Promise<string | null> {
+	const { promise, resolve } = Promise.withResolvers<string | null>();
+	const ui = new TUI(new ProcessTerminal());
+	let resolved = false;
+	const finish = (value: string | null): void => {
+		if (resolved) return;
+		resolved = true;
+		ui.stop();
+		resolve(value);
+	};
+	const input = new Input();
+	input.onSubmit = value => finish(value.trim() || null);
+	input.onEscape = () => finish(null);
+	process.stdout.write('Describe what to detect and fix (e.g. "ts errors"):\n');
+	ui.addChild(input);
+	ui.setFocus(input);
+	ui.start();
+	return promise;
+}
+
+async function selectOne(title: string, items: SelectItem[]): Promise<string | null> {
+	const { promise, resolve } = Promise.withResolvers<string | null>();
+	const ui = new TUI(new ProcessTerminal());
+	let resolved = false;
+	const finish = (value: string | null): void => {
+		if (resolved) return;
+		resolved = true;
+		ui.stop();
+		resolve(value);
+	};
+	const list = new SelectList(items, Math.min(items.length, 12), getSelectListTheme());
+	list.onSelect = item => finish(item.value);
+	list.onCancel = () => finish(null);
+	process.stdout.write(`${title}\n`);
+	ui.addChild(list);
+	ui.setFocus(list);
+	ui.start();
+	return promise;
+}

package/src/cli/command-help.ts

@@ -34,6 +34,10 @@ export const completionsHelp = {
 
 export const completeHelp = { hidden: true } satisfies CommandMetadata;
 
+export const compressHelp = {
+	description: "Rewrite a text file into the dense prompt register, reporting what it drops",
+} satisfies CommandMetadata;
+
 export const configHelp = { description: "Manage configuration settings" } satisfies CommandMetadata;
 
 export const dryBalanceHelp = {