@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/cli/tools.ts

@@ -0,0 +1,321 @@
+import { describeYaziProfile, inspectCurrentYaziProfile, resetYaziProfile } from "../domains/mux/index.js";
+import {
+	describeFloorRejection,
+	describeResolution,
+	findPinnedTool,
+	installedToolVersions,
+	installRemedy,
+	installTool,
+	PINNED_TOOLS,
+	removeTool,
+	type ToolStatus,
+	toolStatus,
+	toolStatuses,
+} from "../domains/toolchain/index.js";
+import { formatColumns, printError, printOk } from "./shared.js";
+
+const HELP = `clio-coder tools <command>
+
+Manage the external terminal programs Clio can drive. Every one of them is
+optional: Clio works without them and only uses one when it is present. Each is
+pinned to an exact upstream version and checksum, and a copy already on PATH
+wins over Clio's own as long as it clears the pinned minimum.
+
+Commands:
+  clio-coder tools list [--json]           the pinned table and where each resolves
+  clio-coder tools status <id> [--json] [--reset-profile]  one tool in detail
+  clio-coder tools install <id> [--force] [--json]  download, verify, and vendor a tool
+  clio-coder tools remove <id>|--all [--json]  delete every vendored version of a tool
+
+Downloads happen only here. Nothing on a startup path fetches anything.
+
+An install keeps one version directory per tool: once the pinned version is in
+place, versions it superseded are pruned, along with any staging directory left
+by an install that was killed. Removal touches nothing outside <data>/tools/<id>
+and needs no confirmation, since every byte under it is re-downloadable from the
+checksum-pinned registry. "remove --all" sweeps every tool in the table.
+`;
+
+interface Parsed {
+	command?: string;
+	positional: string[];
+	json: boolean;
+	force: boolean;
+	all: boolean;
+	resetProfile: boolean;
+	help: boolean;
+}
+
+export async function runToolsCommand(argv: ReadonlyArray<string> = []): Promise<number> {
+	let parsed: Parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		process.stderr.write(HELP);
+		return 2;
+	}
+	if (parsed.help || parsed.command === undefined) {
+		process.stdout.write(HELP);
+		return parsed.help ? 0 : 2;
+	}
+
+	// `--all` belongs to `remove` alone. Silently ignoring it elsewhere would let
+	// `tools install --all` read as a request that was honored.
+	if (parsed.all && parsed.command !== "remove") {
+		printError("--all is only valid with `tools remove`");
+		return 2;
+	}
+
+	switch (parsed.command) {
+		case "list":
+			if (parsed.resetProfile) return invalidResetProfile();
+			return listTools(parsed.json);
+		case "status":
+			return statusTool(parsed.positional[0], parsed.json, parsed.resetProfile);
+		case "install":
+			if (parsed.resetProfile) return invalidResetProfile();
+			return installOne(parsed.positional[0], parsed.force, parsed.json);
+		case "remove":
+			if (parsed.resetProfile) return invalidResetProfile();
+			return parsed.all ? removeAll(parsed.positional[0], parsed.json) : removeOne(parsed.positional[0], parsed.json);
+		default:
+			printError(`unknown tools command: ${parsed.command}`);
+			process.stderr.write(HELP);
+			return 2;
+	}
+}
+
+function parse(argv: ReadonlyArray<string>): Parsed {
+	const out: Parsed = { positional: [], json: false, force: false, all: false, resetProfile: false, help: false };
+	for (const arg of argv) {
+		if (!out.command && !arg.startsWith("-")) {
+			out.command = arg;
+			continue;
+		}
+		switch (arg) {
+			case "--json":
+				out.json = true;
+				break;
+			case "--force":
+			case "-f":
+				out.force = true;
+				break;
+			case "--all":
+				out.all = true;
+				break;
+			case "--reset-profile":
+				out.resetProfile = true;
+				break;
+			case "--help":
+			case "-h":
+				out.help = true;
+				break;
+			default:
+				if (arg.startsWith("-")) throw new Error(`unknown flag: ${arg}`);
+				out.positional.push(arg);
+		}
+	}
+	return out;
+}
+
+function listTools(json: boolean): number {
+	const statuses = toolStatuses();
+	if (json) {
+		process.stdout.write(`${JSON.stringify(statuses.map(jsonShape), null, 2)}\n`);
+		return 0;
+	}
+	const rows = statuses.map((status) => [
+		status.id,
+		status.version,
+		status.license,
+		status.resolution.source,
+		describeResolution(status),
+	]);
+	process.stdout.write(formatColumns([["TOOL", "PIN", "LICENSE", "SOURCE", "RESOLVED"], ...rows]));
+	return 0;
+}
+
+function invalidResetProfile(): number {
+	printError("--reset-profile is only valid with `tools status yazi`");
+	return 2;
+}
+
+/**
+ * The one refusal an unknown id gets, from every verb.
+ *
+ * It names the tools that do exist, because the whole error an operator makes
+ * here is a name: `tools remove herd` and `tools remove tmux` want different
+ * answers, and the registry list gives both of them one.
+ */
+function unknownTool(id: string): number {
+	printError(`unknown tool: ${id} (known: ${PINNED_TOOLS.map((row) => row.id).join(", ")})`);
+	return 2;
+}
+
+function statusTool(id: string | undefined, json: boolean, resetProfile: boolean): number {
+	if (id === undefined) {
+		printError("usage: clio-coder tools status <id>");
+		return 2;
+	}
+	const entry = findPinnedTool(id);
+	if (entry === null) {
+		return unknownTool(id);
+	}
+	if (resetProfile && id !== "yazi") return invalidResetProfile();
+	if (resetProfile) resetYaziProfile();
+	const status = toolStatus(entry);
+	const profile = id === "yazi" ? inspectCurrentYaziProfile() : null;
+	if (json) {
+		process.stdout.write(
+			`${JSON.stringify({ ...jsonShape(status), ...(profile ? { profile, profileReset: resetProfile } : {}) }, null, 2)}\n`,
+		);
+		return 0;
+	}
+	const rejection = describeFloorRejection(status);
+	const installedVersions = installedToolVersions(entry.id);
+	const lines = [
+		`${entry.id} ${entry.version} (${entry.license})`,
+		`  ${entry.summary}`,
+		`  homepage    ${entry.homepage}`,
+		`  binaries    ${entry.binaries.join(", ")}`,
+		`  PATH floor  ${entry.minimumVersion}`,
+		`  platform    ${status.platform ?? `${process.platform}-${process.arch}`}${status.supported ? "" : " (no pinned asset)"}`,
+		`  vendor dir  ${status.installDir}${status.installed ? "" : " (not installed)"}`,
+		`  vendored    ${installedVersions.length === 0 ? "nothing" : installedVersions.join(", ")}`,
+		`  resolves to ${describeResolution(status)}`,
+		// Spelled out on its own line as well as inside the resolution sentence,
+		// because a rejected PATH copy is the one thing an operator reads this
+		// command to understand and the sentence above may be about something else.
+		...(rejection === null
+			? []
+			: [
+					`  floor       rejected: ${rejection}`,
+					...(status.resolution.source === "none" && status.supported ? [`  remedy      ${installRemedy(entry.id)}`] : []),
+				]),
+		...(profile
+			? [
+					`  profile     ${describeYaziProfile(profile)}`,
+					...(resetProfile ? ["  profile reset; next open regenerates it"] : []),
+				]
+			: []),
+	];
+	process.stdout.write(`${lines.join("\n")}\n`);
+	return 0;
+}
+
+async function installOne(id: string | undefined, force: boolean, json: boolean): Promise<number> {
+	if (id === undefined) {
+		printError("usage: clio-coder tools install <id>");
+		return 2;
+	}
+	if (findPinnedTool(id) === null) {
+		return unknownTool(id);
+	}
+	const result = await installTool(id, {
+		force,
+		...(json ? {} : { onProgress: (message: string) => process.stderr.write(`  ${message}\n`) }),
+	});
+	if (json) {
+		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+		return result.ok ? 0 : 1;
+	}
+	if (!result.ok) {
+		printError(result.message);
+		return 1;
+	}
+	printOk(result.message);
+	for (const path of result.documents) process.stdout.write(`  license  ${path}\n`);
+	for (const version of result.pruned) process.stdout.write(`  pruned   ${id} ${version}\n`);
+	return 0;
+}
+
+/**
+ * Delete a tool's vendored install.
+ *
+ * The two answers an operator can act on are "there was nothing there" and
+ * "these versions are gone", and both are exit 0: the state they asked for
+ * holds either way. Only an id the registry does not know is a usage error,
+ * because that is the one case where nothing was inspected at all.
+ */
+function removeOne(id: string | undefined, json: boolean): number {
+	if (id === undefined) {
+		printError("usage: clio-coder tools remove <id>");
+		return 2;
+	}
+	if (findPinnedTool(id) === null) return unknownTool(id);
+	const result = removeTool(id);
+	if (json) {
+		process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+		return result.ok ? 0 : 1;
+	}
+	if (!result.ok) {
+		printError(result.message);
+		return 1;
+	}
+	printOk(result.message);
+	if (result.removed.length > 0) {
+		process.stdout.write(`  reinstall with \`${installRemedy(id)}\`\n`);
+	}
+	return 0;
+}
+
+/**
+ * Delete every pinned tool's vendored install.
+ *
+ * Each tool is swept independently and the exit code is the worst of them, so
+ * one directory that resists deletion does not hide the two that came off
+ * cleanly. Tools that had nothing installed are counted rather than listed:
+ * on the machine this verb is for, most of the registry is usually absent, and
+ * three lines of "nothing to remove" would bury the one line that matters.
+ */
+function removeAll(id: string | undefined, json: boolean): number {
+	if (id !== undefined) {
+		printError("`tools remove --all` takes no tool id; drop the id or drop --all");
+		return 2;
+	}
+	const results = PINNED_TOOLS.map((entry) => removeTool(entry.id));
+	if (json) {
+		process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+		return results.every((result) => result.ok) ? 0 : 1;
+	}
+	for (const result of results) {
+		if (!result.ok) printError(result.message);
+		else if (result.removed.length > 0 || result.staleStaging.length > 0) printOk(result.message);
+	}
+	const touched = results.filter((result) => result.ok && result.removed.length > 0);
+	const untouched = results.filter((result) => result.ok && result.removed.length === 0);
+	if (touched.length > 0) {
+		process.stdout.write(`  reinstall with \`clio-coder tools install <id>\`\n`);
+	}
+	if (untouched.length > 0) {
+		process.stdout.write(`  ${untouched.length} of ${results.length} had nothing vendored\n`);
+	}
+	return results.every((result) => result.ok) ? 0 : 1;
+}
+
+/** The JSON surface, flattened so a script does not have to walk the resolution. */
+function jsonShape(status: ToolStatus): Record<string, unknown> {
+	return {
+		id: status.id,
+		version: status.version,
+		license: status.license,
+		platform: status.platform,
+		supported: status.supported,
+		installed: status.installed,
+		installDir: status.installDir,
+		source: status.resolution.source,
+		binaryPath: status.resolution.binaryPath,
+		foundVersion: status.resolution.version,
+		minimumVersion: status.resolution.entry?.minimumVersion ?? null,
+		pathCandidate: status.resolution.pathCandidate,
+		// A script deciding whether to warn about a floor rejection should not have
+		// to parse `detail` for it, so the rejection and the command that answers
+		// it are their own fields. `remedy` is null exactly where installing would
+		// change nothing: already vendored, or no asset for this platform.
+		floorRejection: describeFloorRejection(status),
+		remedy: status.resolution.source === "none" && status.supported ? installRemedy(status.id) : null,
+		installedVersions: installedToolVersions(status.id),
+		detail: describeResolution(status),
+	};
+}

package/src/cli/trace-inspect.ts

@@ -0,0 +1,252 @@
+/**
+ * Fixed machine-readable projection of recent durable trace runs and phases.
+ *
+ * `trace runs --json` is an operator-directed terminal surface: it takes a
+ * database path and a limit, and it emits `SELECT *`, which includes the
+ * request text the operator typed. The GUI cannot reuse that transport. This
+ * command accepts no identifier, path, or limit, opens only the default trace
+ * database, selects a bounded newest-first window itself, and emits accounting
+ * facts with no prompt text, no free-form description or error, and no path.
+ *
+ * It is deliberately a separate read from `fleet inspect --json` even though
+ * both are keyed by run id. The ledger and the trace database are different
+ * durable stores with different failure modes: an installation that never
+ * enabled tracing has no trace database at all, and that must be an empty
+ * answer here rather than a failure of the run journal.
+ */
+
+import { existsSync } from "node:fs";
+import { clioStatePath } from "../core/xdg.js";
+import { TraceReader, traceDatabasePath } from "../domains/observability/trace-store.js";
+import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
+import { truncateToWidth } from "../engine/tui-primitives.js";
+
+export const TRACE_INSPECT_MAX_RUNS = 8;
+export const TRACE_INSPECT_MAX_PHASES = 16;
+export const TRACE_INSPECT_MAX_EVENT_KINDS = 12;
+export const TRACE_INSPECT_MAX_PROCESS_KINDS = 8;
+
+const IDENTITY_WIDTH = 128;
+const STATUS_WIDTH = 64;
+
+export interface TraceInspectPhase {
+	readonly name: string;
+	readonly kind: string;
+	readonly owner: string;
+	readonly status: string;
+	readonly attempt: number;
+	readonly retries: number;
+	/** Whether the phase recorded an error, without the error text itself. */
+	readonly failed: boolean;
+	readonly elapsedMs: number | null;
+	readonly totalTokens: number | null;
+	readonly totalCostUsd: number | null;
+}
+
+/**
+ * What a run's events were, in aggregate.
+ *
+ * Deliberately shapes and not rows. A trace event carries `payload_json` and a
+ * free-form name, which are the class of value this boundary keeps host-side,
+ * so the tail itself stays in the terminal and what crosses is how many events
+ * of each kind there were and the span they cover. The counts come out of SQL,
+ * so the payloads are not read on the way to counting them.
+ */
+export interface TraceInspectEvents {
+	readonly total: number;
+	readonly firstAt: string | null;
+	readonly lastAt: string | null;
+	readonly kinds: readonly { readonly kind: string; readonly count: number }[];
+	readonly kindsTruncated: boolean;
+}
+
+/**
+ * What a run's child processes were, in aggregate.
+ *
+ * Same rule, applied harder: a process row carries the command line, the pid,
+ * and the host. None of that is needed to say a run spawned four workers and
+ * one is still alive, and none of it crosses.
+ */
+export interface TraceInspectProcesses {
+	readonly total: number;
+	readonly running: number;
+	readonly kinds: readonly { readonly kind: string; readonly total: number; readonly running: number }[];
+	readonly kindsTruncated: boolean;
+}
+
+export interface TraceInspectRun {
+	readonly runId: string;
+	readonly agent: string;
+	readonly target: string;
+	readonly model: string;
+	readonly runtime: string;
+	readonly node: string | null;
+	readonly status: string;
+	readonly startedAt: string;
+	readonly elapsedMs: number | null;
+	readonly totalTokens: number | null;
+	readonly totalCostUsd: number | null;
+	readonly phases: readonly TraceInspectPhase[];
+	readonly phasesTruncated: boolean;
+	readonly events: TraceInspectEvents;
+	readonly processes: TraceInspectProcesses;
+}
+
+export interface TraceInspectSnapshot {
+	readonly version: 1;
+	readonly generatedAt: string;
+	/**
+	 * False when this installation has no trace database. That is the ordinary
+	 * state of an installation that never enabled tracing, and it has to stay
+	 * distinguishable from a database that exists and holds no runs.
+	 */
+	readonly available: boolean;
+	readonly runs: readonly TraceInspectRun[];
+	readonly truncated: boolean;
+}
+
+function bounded(value: string, width: number): string {
+	const sanitized = sanitizeCallTargetText(value);
+	if (sanitized.length === 0) return "unavailable";
+	return sanitizeCallTargetText(truncateToWidth(sanitized, width, "…", false));
+}
+
+function nullableBounded(value: string | null, width: number): string | null {
+	return value === null ? null : bounded(value, width);
+}
+
+/** A finite non-negative count, or null when the store recorded none. */
+function tally(value: number | null): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.trunc(value) : null;
+}
+
+/** A finite non-negative cost, or null. Kept as a number so the GUI formats it. */
+function cost(value: number | null): number | null {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/**
+ * Wall time between two stamps. Null rather than zero when either is missing or
+ * unparseable, because "still running" and "took no time" are different facts.
+ */
+function elapsed(startedAt: string | null, endedAt: string | null): number | null {
+	if (startedAt === null || endedAt === null) return null;
+	const start = Date.parse(startedAt);
+	const end = Date.parse(endedAt);
+	if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+	return Math.max(0, end - start);
+}
+
+function eventSummary(reader: TraceReader, runId: string): TraceInspectEvents {
+	const span = reader.eventSpan(runId);
+	const all = reader.eventKindCounts(runId);
+	const visible = all.slice(0, TRACE_INSPECT_MAX_EVENT_KINDS);
+	return {
+		total: tally(span.total) ?? 0,
+		firstAt: span.firstAt,
+		lastAt: span.lastAt,
+		kinds: visible.map((entry) => ({ kind: bounded(entry.type, STATUS_WIDTH), count: tally(entry.count) ?? 0 })),
+		kindsTruncated: all.length > visible.length,
+	};
+}
+
+function processSummary(reader: TraceReader, runId: string): TraceInspectProcesses {
+	const all = reader.processKindCounts(runId);
+	const visible = all.slice(0, TRACE_INSPECT_MAX_PROCESS_KINDS);
+	return {
+		total: all.reduce((sum, entry) => sum + (tally(entry.total) ?? 0), 0),
+		running: all.reduce((sum, entry) => sum + (tally(entry.running) ?? 0), 0),
+		kinds: visible.map((entry) => ({
+			kind: bounded(entry.kind, STATUS_WIDTH),
+			total: tally(entry.total) ?? 0,
+			running: tally(entry.running) ?? 0,
+		})),
+		kindsTruncated: all.length > visible.length,
+	};
+}
+
+/** Pure payload builder, exported so the fixed contract is testable without subprocess capture. */
+export function traceInspectSnapshot(
+	now: () => number = Date.now,
+	databasePath: string = traceDatabasePath(clioStatePath()),
+): TraceInspectSnapshot {
+	const generatedAt = new Date(now()).toISOString();
+	if (!existsSync(databasePath)) {
+		return { version: 1, generatedAt, available: false, runs: [], truncated: false };
+	}
+	let reader: TraceReader;
+	try {
+		reader = new TraceReader(databasePath);
+	} catch {
+		// A database that exists but will not open is not an empty installation,
+		// and it is not this command's job to diagnose it. Report it as present
+		// with nothing readable rather than inventing either extreme.
+		return { version: 1, generatedAt, available: true, runs: [], truncated: false };
+	}
+	try {
+		const selected = reader.runs(TRACE_INSPECT_MAX_RUNS + 1);
+		const window = selected.slice(0, TRACE_INSPECT_MAX_RUNS);
+		const runs = window.map((row): TraceInspectRun => {
+			const allPhases = reader.phases(row.run_id);
+			const visible = allPhases.slice(0, TRACE_INSPECT_MAX_PHASES);
+			return {
+				runId: bounded(row.run_id, IDENTITY_WIDTH),
+				agent: bounded(row.agent, IDENTITY_WIDTH),
+				target: bounded(row.target, IDENTITY_WIDTH),
+				model: bounded(row.model, IDENTITY_WIDTH),
+				runtime: bounded(row.runtime, IDENTITY_WIDTH),
+				node: nullableBounded(row.node, IDENTITY_WIDTH),
+				status: bounded(row.status, STATUS_WIDTH),
+				startedAt: row.started_at,
+				elapsedMs: elapsed(row.started_at, row.ended_at),
+				totalTokens: tally(row.total_tokens),
+				totalCostUsd: cost(row.total_cost_usd),
+				phases: visible.map(
+					(phase): TraceInspectPhase => ({
+						name: bounded(phase.name, IDENTITY_WIDTH),
+						kind: bounded(phase.kind, STATUS_WIDTH),
+						owner: bounded(phase.owner, IDENTITY_WIDTH),
+						status: bounded(phase.status, STATUS_WIDTH),
+						attempt: tally(phase.attempt) ?? 0,
+						retries: tally(phase.retries) ?? 0,
+						// The error text can quote a path, a URL, or a model reply, so only
+						// the fact that one was recorded crosses.
+						failed: phase.error !== null && phase.error !== "",
+						elapsedMs: elapsed(phase.started_at, phase.ended_at),
+						totalTokens: tally(phase.total_tokens),
+						totalCostUsd: cost(phase.total_cost_usd),
+					}),
+				),
+				phasesTruncated: allPhases.length > visible.length,
+				events: eventSummary(reader, row.run_id),
+				processes: processSummary(reader, row.run_id),
+			};
+		});
+		return {
+			version: 1,
+			generatedAt,
+			available: true,
+			runs,
+			truncated: selected.length > window.length,
+		};
+	} finally {
+		reader.close();
+	}
+}
+
+/**
+ * `clio-coder trace inspect --json`, and nothing else.
+ *
+ * `fixed` is false as soon as the caller supplied a database, a limit, a follow,
+ * or any other positional. The whole point of this command is that its argv is
+ * not a surface: a GUI host can invoke it and be certain the process it started
+ * cannot be steered into reading a different file or a wider window.
+ */
+export function runTraceInspect(fixed: boolean): number {
+	if (!fixed) {
+		process.stderr.write("clio-coder trace inspect: usage: clio-coder trace inspect --json\n");
+		return 2;
+	}
+	process.stdout.write(`${JSON.stringify(traceInspectSnapshot(), null, 2)}\n`);
+	return 0;
+}