@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/cli/text-layout.ts

@@ -0,0 +1,112 @@
+/**
+ * Width-aware layout for the plain-stdout CLI surfaces.
+ *
+ * The TUI measures the terminal on every frame; the command-line surfaces did
+ * not measure it at all. `clio-coder configure --list` and the first-run runtime
+ * menu wrote fixed-width rows assuming roughly 88 columns, so at 80, the
+ * oldest default there is, the model column ran past the edge and the terminal
+ * wrapped it into a second line that no longer lined up with anything. The
+ * first thing a new user sees was the surface that handled width worst.
+ *
+ * Everything here operates on ASCII runtime ids, labels, and summaries, so
+ * `length` is the display width. The TUI keeps its own grapheme-aware
+ * measurement for content that can carry anything.
+ */
+
+/** Columns to lay out for, with a floor that keeps arithmetic non-negative. */
+export function terminalColumns(
+	stream: { columns?: number | undefined } = process.stdout,
+	env: { COLUMNS?: string | undefined } = process.env,
+): number {
+	const columns = stream.columns;
+	if (typeof columns === "number" && Number.isFinite(columns)) return Math.max(20, Math.floor(columns));
+	// A pipe reports no width, and the fallback used to end there: `clio-coder
+	// targets | less` was pinned to 80 with no way to widen it, which cut the
+	// port off every url and ellipsized the model column, the two the table
+	// exists to tell apart. $COLUMNS is what a shell exports for exactly this,
+	// so an operator or a CI job can say how wide the capture is.
+	const declared = Number(env.COLUMNS);
+	if (Number.isFinite(declared) && declared > 0) return Math.max(20, Math.floor(declared));
+	// 80 is the conventional answer and is also the width the fixed-width rows
+	// were implicitly written for.
+	return 80;
+}
+
+/** Shorten to `width`, marking the cut so a truncated value never reads as complete. */
+export function truncate(text: string, width: number): string {
+	if (width <= 0) return "";
+	if (text.length <= width) return text;
+	if (width === 1) return "…";
+	return `${text.slice(0, width - 1)}…`;
+}
+
+/** Pad to exactly `width`, truncating anything longer so the next column still starts where it should. */
+export function column(text: string, width: number): string {
+	return truncate(text, width).padEnd(width);
+}
+
+/**
+ * Wrap on whitespace to `width`, indenting every line after the first by
+ * `hangingIndent`. A single word longer than the available room is emitted
+ * whole rather than split, because runtime ids and URLs are worse broken.
+ */
+export function wrapPlain(text: string, width: number, hangingIndent = 0): string[] {
+	const words = text.split(/\s+/).filter((word) => word.length > 0);
+	if (words.length === 0) return [""];
+	const indent = " ".repeat(hangingIndent);
+	const lines: string[] = [];
+	// `width` is the room for text on every line. The indent is added only when
+	// a line is emitted, so it never eats into the budget the next word is
+	// measured against.
+	let current = "";
+	const emit = (line: string): void => {
+		lines.push(lines.length === 0 ? line : `${indent}${line}`);
+	};
+	for (const word of words) {
+		if (current.length === 0) {
+			current = word;
+			continue;
+		}
+		if (current.length + 1 + word.length <= width) {
+			current = `${current} ${word}`;
+			continue;
+		}
+		emit(current);
+		current = word;
+	}
+	emit(current);
+	return lines;
+}
+
+export interface TwoColumnOptions {
+	/** Leading spaces before the left column. */
+	indent: number;
+	/** Width reserved for the left column, including its trailing gap. */
+	leftWidth: number;
+	width: number;
+	/** Below this much room for the right column, stack instead of aligning. */
+	minRight?: number;
+}
+
+/**
+ * A label beside its description, degrading to the label on its own line with
+ * the description indented beneath when the terminal cannot hold both.
+ */
+export function twoColumnRow(left: string, right: string, options: TwoColumnOptions): string[] {
+	const { indent, leftWidth, width } = options;
+	const minRight = options.minRight ?? 24;
+	const pad = " ".repeat(indent);
+	const rightRoom = width - indent - leftWidth;
+	if (rightRoom >= minRight) {
+		const wrapped = wrapPlain(right, rightRoom, indent + leftWidth);
+		const [first = "", ...rest] = wrapped;
+		return [`${pad}${column(left, leftWidth)}${first}`, ...rest];
+	}
+	const stackIndent = indent + 2;
+	return [
+		`${pad}${left}`,
+		...wrapPlain(right, Math.max(8, width - stackIndent), stackIndent).map((line, index) =>
+			index === 0 ? `${" ".repeat(stackIndent)}${line}` : line,
+		),
+	];
+}

package/src/cli/trace.ts

@@ -0,0 +1,322 @@
+import { existsSync } from "node:fs";
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { clioStatePath } from "../core/xdg.js";
+import {
+	TRACE_EVENT_POLL_LIMIT,
+	type TraceEventRow,
+	type TracePhaseRow,
+	type TraceProcessRow,
+	TraceReader,
+	type TraceRunRow,
+	traceDatabasePath,
+} from "../domains/observability/trace-store.js";
+
+const HELP = `Usage:
+  clio-coder trace runs [--db PATH] [--limit N] [--json]
+  clio-coder trace phases <runId> [--db PATH]
+  clio-coder trace tail <runId> [--follow] [--db PATH]
+  clio-coder trace procs <runId> [--db PATH]
+  clio-coder trace sql <SELECT query> [--db PATH]
+  clio-coder trace ui [--db PATH] [--port N]        source checkout only
+
+The viewer ships with the repository, not the npm package, so from an installed
+Clio the subcommands above are the way in. They read the same database.
+`;
+
+interface ParsedTraceArgs {
+	positional: string[];
+	db: string;
+	/** True when --db named the path, so a miss is the operator's path, not the default. */
+	dbExplicit: boolean;
+	follow: boolean;
+	limit: number;
+	port: number;
+	json: boolean;
+}
+
+function parseTraceArgs(args: string[]): ParsedTraceArgs {
+	const positional: string[] = [];
+	let db = traceDatabasePath(clioStatePath());
+	let dbExplicit = false;
+	let follow = false;
+	let limit = 50;
+	let port = 0;
+	let json = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--follow") follow = true;
+		else if (arg === "--json") json = true;
+		else if (arg === "--db" || arg === "--limit" || arg === "--port") {
+			const value = args[index + 1];
+			if (value === undefined) throw new Error(`${arg} requires a value`);
+			index += 1;
+			if (arg === "--db") {
+				db = resolve(value);
+				dbExplicit = true;
+			} else if (arg === "--limit") limit = parseInteger(value, "--limit", 1, 500);
+			else port = parseInteger(value, "--port", 0, 65_535);
+		} else if (arg?.startsWith("--db=")) {
+			db = resolve(arg.slice(5));
+			dbExplicit = true;
+		} else if (arg?.startsWith("--limit=")) limit = parseInteger(arg.slice(8), "--limit", 1, 500);
+		else if (arg?.startsWith("--port=")) port = parseInteger(arg.slice(7), "--port", 0, 65_535);
+		else if (arg?.startsWith("-")) throw new Error(`unknown trace flag: ${arg}`);
+		else if (arg !== undefined) positional.push(arg);
+	}
+	return { positional, db, dbExplicit, follow, limit, port, json };
+}
+
+/** Every subcommand `trace` answers to. Anything else is a usage error. */
+const TRACE_COMMANDS = new Set(["runs", "phases", "tail", "procs", "sql", "ui"]);
+
+/** The subcommands whose first positional is a run id. */
+const TRACE_COMMANDS_NEEDING_RUN_ID = new Set(["phases", "tail", "procs"]);
+
+/**
+ * Reject a malformed invocation before the database is consulted.
+ *
+ * The no-database path below is a courtesy that exits 0, because a state tree
+ * nothing has written to is the empty state rather than a failure. Running it
+ * ahead of this check meant that on a fresh install every typed subcommand
+ * succeeded: `trace bogus`, `trace phases` with no run id, and `trace sql` with
+ * no query all exited 0 with the same "no trace database yet" line, so a CI step
+ * gated on one of them went on to the next line. The same invocations against a
+ * home that had a database exited 2, which is the documented behavior.
+ */
+function invocationError(command: string, runId: string | undefined): number | null {
+	if (!TRACE_COMMANDS.has(command)) {
+		process.stderr.write(`unknown trace command: ${command}\n${HELP}`);
+		return 2;
+	}
+	if (TRACE_COMMANDS_NEEDING_RUN_ID.has(command) && !runId) return missingRunId(command);
+	return null;
+}
+
+export async function runTraceCommand(args: string[]): Promise<number> {
+	// Asking for help is not a usage error. Every other subcommand answers
+	// `--help` on stdout with status 0; this one reported `unknown trace flag:
+	// --help` on stderr and exited 2, so the one thing a lost user reliably
+	// types was the one thing that looked broken.
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	let parsed: ParsedTraceArgs;
+	try {
+		parsed = parseTraceArgs(args);
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n${HELP}`);
+		return 2;
+	}
+	const [command, runId] = parsed.positional;
+	if (!command || command === "help") {
+		process.stdout.write(HELP);
+		return command === "help" ? 0 : 2;
+	}
+	const sqlQuery = parsed.positional.slice(1).join(" ");
+	const usageError = invocationError(command, runId);
+	if (usageError !== null) return usageError;
+	if (command === "sql" && !sqlQuery) {
+		process.stderr.write("trace sql requires a SELECT query\n");
+		return 2;
+	}
+
+	if (command === "ui") return runTraceUi(parsed.db, parsed.port);
+
+	// A database that was never written is the empty state, not a failure. Handing
+	// the absent path to node:sqlite produced "unable to open database file",
+	// which named neither the file nor a next step, and loading the module leaked
+	// its ExperimentalWarning onto the user's stderr on a fresh install. A path
+	// the operator typed is a different claim, so a --db that is not there stays
+	// an error and says which path it means.
+	if (!existsSync(parsed.db)) return missingDatabase(parsed);
+
+	let reader: TraceReader;
+	try {
+		reader = new TraceReader(parsed.db);
+	} catch (error) {
+		process.stderr.write(`trace database: ${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	}
+	try {
+		// Every case below is reachable only after `invocationError` accepted the
+		// command and its required positional, so the run id is present wherever
+		// this reads one.
+		switch (command) {
+			case "runs": {
+				const rows = reader.runs(parsed.limit);
+				if (parsed.json) process.stdout.write(`${JSON.stringify(rows, jsonBigInt, 2)}\n`);
+				else printRuns(rows);
+				return 0;
+			}
+			case "phases":
+				printPhases(reader.phases(runId ?? ""));
+				return 0;
+			case "tail":
+				await tail(reader, runId ?? "", parsed.follow);
+				return 0;
+			case "procs":
+				printProcesses(reader.processes(runId ?? ""));
+				return 0;
+			case "sql": {
+				// The database opened cleanly above, so anything the store objects to
+				// here is the query the operator typed: a mutating statement, more
+				// than one statement, or SQL that will not parse. All three are usage
+				// errors. Refusing `DELETE FROM runs` with exit 1 said "the command
+				// failed" when the truth is "that is not a query this accepts", and
+				// the exit-code contract puts a mutation keyword at 2.
+				let rows: unknown;
+				try {
+					rows = reader.select(sqlQuery);
+				} catch (error) {
+					process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+					return 2;
+				}
+				process.stdout.write(`${JSON.stringify(rows, jsonBigInt, 2)}\n`);
+				return 0;
+			}
+			default:
+				process.stderr.write(`unknown trace command: ${command}\n${HELP}`);
+				return 2;
+		}
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+		return 1;
+	} finally {
+		reader.close();
+	}
+}
+
+async function tail(reader: TraceReader, runId: string, follow: boolean): Promise<void> {
+	let cursor = 0;
+	let idleTerminalPolls = 0;
+	for (;;) {
+		const rows = reader.events(runId, cursor, TRACE_EVENT_POLL_LIMIT);
+		for (const row of rows) {
+			process.stdout.write(`${formatEvent(row)}\n`);
+			cursor = Math.max(cursor, row.rowid);
+		}
+		if (!follow) return;
+		const status = reader.run(runId)?.status;
+		idleTerminalPolls = rows.length === 0 && status !== "queued" && status !== "running" ? idleTerminalPolls + 1 : 0;
+		if (idleTerminalPolls >= 2) return;
+		await new Promise<void>((resolveWait) => setTimeout(resolveWait, 500));
+	}
+}
+
+function formatEvent(row: TraceEventRow): string {
+	const duration =
+		row.ended_at === null ? "" : ` ${Math.max(0, Date.parse(row.ended_at) - Date.parse(row.started_at))}ms`;
+	return `${row.rowid.toString().padStart(6)} ${row.started_at} ${row.type.padEnd(18)} ${row.name}${duration}`;
+}
+
+function printRuns(rows: TraceRunRow[]): void {
+	process.stdout.write("STATUS   STARTED                      TOKENS       COST RUN\n");
+	for (const row of rows) {
+		process.stdout.write(
+			`${row.status.padEnd(8)} ${row.started_at.padEnd(28)} ${formatNumber(row.total_tokens).padStart(8)} ${formatCost(row.total_cost_usd).padStart(10)} ${row.run_id}\n`,
+		);
+	}
+}
+
+function printPhases(rows: TracePhaseRow[]): void {
+	process.stdout.write("STATUS   TRY OWNER              TOKENS       COST PHASE\n");
+	for (const row of rows) {
+		process.stdout.write(
+			`${row.status.padEnd(8)} ${String(row.attempt + 1).padStart(3)} ${row.owner.slice(0, 18).padEnd(18)} ${formatNumber(row.total_tokens).padStart(8)} ${formatCost(row.total_cost_usd).padStart(10)} ${row.name}\n`,
+		);
+	}
+}
+
+function printProcesses(rows: TraceProcessRow[]): void {
+	process.stdout.write("STATE  PID      KIND         NAME                 COMMAND\n");
+	for (const row of rows) {
+		process.stdout.write(
+			`${(row.ended_at === null ? "live" : "ended").padEnd(6)} ${String(row.pid).padEnd(8)} ${row.kind.padEnd(12)} ${row.name.slice(0, 20).padEnd(20)} ${row.command}\n`,
+		);
+	}
+}
+
+async function runTraceUi(db: string, port: number): Promise<number> {
+	const candidates = [
+		fileURLToPath(new URL("../apps/trace-viewer/server.mjs", import.meta.url)),
+		fileURLToPath(new URL("../../apps/trace-viewer/server.mjs", import.meta.url)),
+	];
+	const entry = await firstExisting(candidates);
+	if (entry === null) {
+		process.stderr.write(
+			"trace viewer is available only from a source checkout; apps/trace-viewer/server.mjs was not found\n" +
+				"  the npm package does not carry the viewer, so an installed clio cannot start it\n" +
+				`  the same run is readable here: clio-coder trace runs --db ${db}\n` +
+				"  from a checkout of the repository: npm run trace:ui\n",
+		);
+		return 1;
+	}
+	const module = (await import(pathToFileURL(entry).href)) as {
+		startTraceViewer(options: { db: string; port: number }): Promise<{ url: string; close(): Promise<void> }>;
+	};
+	const server = await module.startTraceViewer({ db, port });
+	process.stdout.write(`Trace viewer: ${server.url}\n`);
+	await new Promise<void>((resolveStop) => {
+		const stop = (): void => {
+			process.off("SIGINT", stop);
+			process.off("SIGTERM", stop);
+			void server.close().finally(resolveStop);
+		};
+		process.on("SIGINT", stop);
+		process.on("SIGTERM", stop);
+	});
+	return 0;
+}
+
+async function firstExisting(paths: string[]): Promise<string | null> {
+	for (const path of paths) {
+		try {
+			await access(path);
+			return path;
+		} catch {
+			// Try the next source-checkout location.
+		}
+	}
+	return null;
+}
+
+function parseInteger(value: string, flag: string, min: number, max: number): number {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < min || parsed > max)
+		throw new Error(`${flag} must be an integer in [${min}, ${max}]`);
+	return parsed;
+}
+
+function missingDatabase(parsed: ParsedTraceArgs): number {
+	if (parsed.dbExplicit) {
+		process.stderr.write(
+			`trace database not found: ${parsed.db}\n` +
+				`  --db named this path. omit it to read the default at ${traceDatabasePath(clioStatePath())}\n`,
+		);
+		return 1;
+	}
+	process.stdout.write(
+		`no trace database yet at ${parsed.db}. rows are recorded when a dispatch executes or an interactive turn runs; run \`clio-coder run "<task>"\` or start a session to create one.\n`,
+	);
+	return 0;
+}
+
+function missingRunId(command: string): number {
+	process.stderr.write(`trace ${command} requires a run id\n`);
+	return 2;
+}
+
+function formatNumber(value: number | null): string {
+	return value === null ? "—" : value.toLocaleString("en-US");
+}
+
+function formatCost(value: number | null): string {
+	return value === null ? "—" : `$${value.toFixed(value < 0.01 ? 4 : 2)}`;
+}
+
+function jsonBigInt(_key: string, value: unknown): unknown {
+	return typeof value === "bigint" ? value.toString() : value;
+}