@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/cli/reset.ts

@@ -1,16 +1,17 @@
-import { type Dirent, existsSync, readdirSync } from "node:fs";
+import { type Dirent, readdirSync } from "node:fs";
 import { join } from "node:path";
 
 import { initializeClioHome } from "../core/init.js";
 import { resetXdgCache, resolveClioDirs } from "../core/xdg.js";
+import { createLifecyclePresenter, type LifecycleItem, measurePath } from "./lifecycle-presenter.js";
 import { type RemovalFailure, removePath, reportRemovalFailures } from "./removal.js";
-import { printError, printHeader, printOk } from "./shared.js";
-import { terminalColumns, wrapPlain } from "./text-layout.js";
+import { printError } from "./shared.js";
 
-const HELP = `clio-coder reset [--state|--data|--cache|--auth|--config|--all] [--dry-run] [--force]
+const HELP = `clio-coder reset [--state|--data|--cache|--auth|--config|--all] [--dry-run] [--force] [--json]
 
-Recover or wipe Clio Coder state while keeping the clio binary installed.
-Each level clears exactly the root (or file) it names and nothing else.
+Recover or wipe Clio Coder state while keeping the clio-coder launcher installed.
+Each level clears exactly the root (or file) it names and nothing else, then the
+empty roots are recreated so the next run has somewhere to write.
 
 Levels (combinable except --all):
   --state       state root only (default). Holds every session transcript, so a
@@ -19,34 +20,24 @@ Levels (combinable except --all):
   --cache       cache root only
   --auth        credentials.yaml only
   --config      settings.yaml only
-  --all         all four roots: config, data, state, and cache
-
-Every run reads each selected root and lists what is inside it before removing
-anything, so what a level covers is read off that listing rather than off this
-text. --dry-run prints the same listing and changes nothing.
+  --all         all four roots whole: config (settings, credentials, and anything
+                else under it), data, state, and cache
 
 Safety:
-  --force       required for destructive execution
+  --force, -f   required for destructive execution in non-interactive environments
   --dry-run     print what would be reset without changing anything
+  --json        emit machine-readable JSON output
+  --help, -h    show this message
 `;
 
-/**
- * What losing a root costs, printed under it in the same listing the removal
- * works from.
- *
- * `--data` carried this and `--state` did not, which is backwards: `--state` is
- * what a bare `clio-coder reset` selects, so the one scope that runs without being
- * asked for by name was the one that explained nothing before taking every
- * transcript on the machine.
- */
-const ROOT_NOTES: Readonly<Record<string, string>> = {
-	state:
-		"the state root holds every session transcript and the audit trail beside it; resume and /view lose their history",
-	// Vendored tools are named because they are the one durable product a reset
-	// cannot regenerate from anything local: getting them back is a download.
-	data:
-		"the data root holds durable products (memory, evidence, evals, and any vendored external tools, which a reinstall re-downloads)",
-};
+const ROOT_NOTES = {
+	state: "State holds every session transcript and the audit trail; resume and /view lose their history.",
+	data: "Data holds memory, evidence, evals, and vendored tools; the tools have to be downloaded again.",
+	config: "Settings return to their defaults.",
+	auth: "Saved API keys are gone; each target has to be authenticated again.",
+	cache: "Cache is disposable and rebuilds itself.",
+	all: "Everything goes: settings, credentials, memory, evidence, transcripts, and caches. A clean install remains.",
+} as const;
 
 interface ParsedResetArgs {
 	state: boolean;
@@ -57,6 +48,7 @@ interface ParsedResetArgs {
 	all: boolean;
 	force: boolean;
 	dryRun: boolean;
+	json: boolean;
 	help: boolean;
 }
 
@@ -70,6 +62,7 @@ function parseResetArgs(argv: ReadonlyArray<string>): ParsedResetArgs {
 		all: false,
 		force: false,
 		dryRun: false,
+		json: false,
 		help: false,
 	};
 	for (const arg of argv) {
@@ -99,6 +92,9 @@ function parseResetArgs(argv: ReadonlyArray<string>): ParsedResetArgs {
 			case "--dry-run":
 				parsed.dryRun = true;
 				break;
+			case "--json":
+				parsed.json = true;
+				break;
 			case "--help":
 			case "-h":
 				parsed.help = true;
@@ -117,49 +113,26 @@ function parseResetArgs(argv: ReadonlyArray<string>): ParsedResetArgs {
 	return parsed;
 }
 
-function report(label: string, path: string): void {
-	process.stdout.write(`  ${label.padEnd(12)} ${path}${existsSync(path) ? "" : "  (absent)"}\n`);
-}
-
 /**
- * The immediate children of `path`, each directory carrying how many entries
- * are inside it. Empty for a file, an absent path, or an unreadable one.
- *
- * This is the inventory, read off the disk on the run that is about to remove
- * it. `--help` used to carry a remembered one, "sessions, audit, receipts,
- * runs, install metadata", which named five things and omitted `interviews/`,
- * `scratch/`, and every dispatch artifact written since that sentence was
- * typed. A list nobody has to maintain cannot drift from what the removal takes.
+ * What sits directly under a root, named so the operator recognizes what the
+ * reset takes. Directories keep their trailing slash; the list is capped so one
+ * crowded root cannot push the decision off the screen.
  */
-function rootContents(path: string): string[] {
+function rootContents(path: string, limit = 4): string | undefined {
 	let entries: Dirent[];
 	try {
 		entries = readdirSync(path, { withFileTypes: true });
 	} catch {
-		return [];
+		return undefined;
 	}
-	return entries
-		.map((entry) => {
-			if (!entry.isDirectory()) return entry.name;
-			let count: number;
-			try {
-				count = readdirSync(join(path, entry.name)).length;
-			} catch {
-				return `${entry.name}/`;
-			}
-			return `${entry.name}/ (${count})`;
-		})
+	if (entries.length === 0) return undefined;
+	const names = entries
+		.map((entry) => (entry.isDirectory() ? `${entry.name}/` : entry.name))
 		.sort((left, right) => left.localeCompare(right));
+	const shown = names.slice(0, limit).join(", ");
+	return names.length > limit ? `${shown}, +${names.length - limit} more` : shown;
 }
 
-/** Write `text` indented under a root line, wrapped to the terminal. */
-function writeIndented(text: string, indent: number): void {
-	const [first = "", ...rest] = wrapPlain(text, Math.max(20, terminalColumns() - indent), indent);
-	process.stdout.write(`${" ".repeat(indent)}${first}\n`);
-	for (const line of rest) process.stdout.write(`${line}\n`);
-}
-
-/** Reconstruct the invocation to rerun after a partial failure. */
 function resetInvocation(args: ParsedResetArgs): string {
 	const levels = (
 		[
@@ -176,81 +149,230 @@ function resetInvocation(args: ParsedResetArgs): string {
 	return `clio-coder reset ${levels.join(" ")} --force`;
 }
 
-export function runResetCommand(argv: ReadonlyArray<string>): number {
+export async function runResetCommand(argv: ReadonlyArray<string>): Promise<number> {
 	let args: ParsedResetArgs;
 	try {
 		args = parseResetArgs(argv);
 	} catch (error) {
 		printError(error instanceof Error ? error.message : String(error));
-		process.stdout.write(HELP);
+		process.stderr.write(HELP);
 		return 2;
 	}
 	if (args.help) {
 		process.stdout.write(HELP);
 		return 0;
 	}
-	if (!args.dryRun && !args.force) {
-		printError("`clio-coder reset` requires --force unless you are using --dry-run");
-		process.stdout.write(HELP);
+
+	// One sentence, and nothing on stdout: a caller that piped this run is
+	// parsing stdout, and a help dump there is indistinguishable from output.
+	const isInteractive = Boolean(process.stdin.isTTY);
+	if (!args.dryRun && !args.force && !isInteractive) {
+		printError("`clio-coder reset` needs a terminal to confirm; pass --force to skip the prompt");
 		return 2;
 	}
 
 	const dirs = resolveClioDirs();
 	const settingsPath = join(dirs.config, "settings.yaml");
 	const credentialsPath = join(dirs.config, "credentials.yaml");
+	const presenter = createLifecyclePresenter({ json: args.json });
+
+	presenter.header("Reset Clio Coder", "reset");
 
-	printHeader("Clio Coder reset");
-
-	// Announce every selected path first, then delete. A failure partway
-	// through therefore never leaves the operator guessing which paths the
-	// command had reached, and the dry run prints the identical list.
-	const selected: Array<{ label: string; path: string }> = args.all
-		? [
-				{ label: "config", path: dirs.config },
-				{ label: "data", path: dirs.data },
-				{ label: "state", path: dirs.state },
-				{ label: "cache", path: dirs.cache },
-			]
+	// Determine scopes to clear
+	const resetData = args.all || args.data;
+	const resetState = args.all || args.state;
+	const resetCache = args.all || args.cache;
+
+	const configSize = measurePath(dirs.config);
+	const dataSize = measurePath(dirs.data);
+	const stateSize = measurePath(dirs.state);
+	const cacheSize = measurePath(dirs.cache);
+
+	const items: LifecycleItem[] = [];
+
+	// State
+	if (resetState) {
+		items.push({
+			label: "State",
+			path: dirs.state,
+			bytes: stateSize.bytes,
+			status: stateSize.exists ? "remove" : "absent",
+			detail: rootContents(dirs.state),
+		});
+	} else {
+		items.push({
+			label: "State",
+			path: dirs.state,
+			bytes: stateSize.bytes,
+			status: stateSize.exists ? "keep" : "absent",
+			detail: stateSize.exists ? "survives" : undefined,
+		});
+	}
+
+	// Data
+	if (resetData) {
+		items.push({
+			label: "Data",
+			path: dirs.data,
+			bytes: dataSize.bytes,
+			status: dataSize.exists ? "remove" : "absent",
+		});
+	} else {
+		items.push({
+			label: "Data",
+			path: dirs.data,
+			bytes: dataSize.bytes,
+			status: dataSize.exists ? "keep" : "absent",
+			detail: dataSize.exists ? "survives" : undefined,
+		});
+	}
+
+	// Config / settings / auth
+	if (args.all) {
+		items.push({
+			label: "Config",
+			path: dirs.config,
+			bytes: configSize.bytes,
+			status: configSize.exists ? "remove" : "absent",
+		});
+	} else {
+		const stSettings = measurePath(settingsPath);
+		if (args.config) {
+			items.push({
+				label: "Settings",
+				path: settingsPath,
+				bytes: stSettings.bytes,
+				status: stSettings.exists ? "remove" : "absent",
+			});
+		} else {
+			items.push({
+				label: "Settings",
+				path: settingsPath,
+				bytes: stSettings.bytes,
+				status: stSettings.exists ? "keep" : "absent",
+				detail: stSettings.exists ? "survives" : undefined,
+			});
+		}
+
+		const stCreds = measurePath(credentialsPath);
+		if (args.auth) {
+			items.push({
+				label: "Credentials",
+				path: credentialsPath,
+				bytes: stCreds.bytes,
+				status: stCreds.exists ? "remove" : "absent",
+			});
+		} else {
+			items.push({
+				label: "Credentials",
+				path: credentialsPath,
+				bytes: stCreds.bytes,
+				status: stCreds.exists ? "keep" : "absent",
+				detail: stCreds.exists ? "survives" : undefined,
+			});
+		}
+	}
+
+	// Cache
+	if (resetCache) {
+		items.push({
+			label: "Cache",
+			path: dirs.cache,
+			bytes: cacheSize.bytes,
+			status: cacheSize.exists ? "remove" : "absent",
+		});
+	} else {
+		items.push({
+			label: "Cache",
+			path: dirs.cache,
+			bytes: cacheSize.bytes,
+			status: cacheSize.exists ? "keep" : "absent",
+			detail: cacheSize.exists ? "survives" : undefined,
+		});
+	}
+
+	// The launcher is not listed. Reset never touches it, and a row for a path a
+	// command cannot act on is one more line between the operator and the four
+	// that decide whether to go ahead.
+	presenter.listItems("The following will be cleared", items);
+
+	// One consequence line, not one per scope. `--all` states the whole outcome,
+	// so the per-root notes underneath it would only repeat it.
+	const notes: string[] = args.all
+		? [ROOT_NOTES.all]
 		: [
-				...(args.config ? [{ label: "settings", path: settingsPath }] : []),
-				...(args.auth ? [{ label: "credentials", path: credentialsPath }] : []),
-				...(args.data ? [{ label: "data", path: dirs.data }] : []),
-				...(args.state ? [{ label: "state", path: dirs.state }] : []),
-				...(args.cache ? [{ label: "cache", path: dirs.cache }] : []),
-			];
-
-	// The note is a property of the root, not of the flag that selected it, so
-	// `--all` and the named scope say the same thing about the same directory.
-	for (const entry of selected) {
-		report(entry.label, entry.path);
-		const contents = rootContents(entry.path);
-		if (contents.length > 0) writeIndented(contents.join(", "), 4);
-		const note = ROOT_NOTES[entry.label];
-		if (note) writeIndented(`note: ${note}`, 2);
+				resetState ? ROOT_NOTES.state : null,
+				resetData ? ROOT_NOTES.data : null,
+				args.config ? ROOT_NOTES.config : null,
+				args.auth ? ROOT_NOTES.auth : null,
+			].filter((note): note is NonNullable<typeof note> => note !== null);
+	for (const note of notes) presenter.note(note);
+
+	// Only when something actually survives. On `--all` the note above already
+	// says nothing does, and on a scoped reset over an empty home every row is
+	// absent, which is not the same claim as "it was there and it is going".
+	const surviving = items.filter((item) => item.status === "keep").map((item) => item.label);
+	if (surviving.length > 0) presenter.note(`Survives: ${surviving.join(", ")}`);
+
+	if (args.dryRun) {
+		presenter.warn("Dry run: no changes made");
+		presenter.done("Done");
+		return 0;
+	}
+
+	if (!args.force) {
+		const confirmed = await presenter.confirm("Are you sure you want to reset the selected state?", false);
+		if (!confirmed) {
+			presenter.warn("Reset cancelled");
+			presenter.done("Cancelled");
+			return 0;
+		}
 	}
 
+	const toRemove: Array<{ label: string; path: string }> = [];
+	if (args.all) {
+		toRemove.push(
+			{ label: "Config", path: dirs.config },
+			{ label: "Data", path: dirs.data },
+			{ label: "State", path: dirs.state },
+			{ label: "Cache", path: dirs.cache },
+		);
+	} else {
+		if (args.config) toRemove.push({ label: "Settings", path: settingsPath });
+		if (args.auth) toRemove.push({ label: "Credentials", path: credentialsPath });
+		if (args.data) toRemove.push({ label: "Data", path: dirs.data });
+		if (args.state) toRemove.push({ label: "State", path: dirs.state });
+		if (args.cache) toRemove.push({ label: "Cache", path: dirs.cache });
+	}
+
+	// `removePath` returns null both for a path it deleted and for one that was
+	// never there, so presence is asked here. Announcing "Reset Cache" over an
+	// absent cache is the one result line an operator cannot check.
 	const failures: RemovalFailure[] = [];
-	for (const entry of selected) {
-		const failure = removePath(entry.label, entry.path, args.dryRun);
+	let cleared = 0;
+	for (const entry of toRemove) {
+		const existed = measurePath(entry.path).exists;
+		const failure = removePath(entry.label, entry.path, false);
 		if (failure) failures.push(failure);
+		else if (existed) {
+			presenter.completedStep(`Cleared ${entry.label}`);
+			cleared += 1;
+		}
 	}
+	if (failures.length === 0 && cleared === 0)
+		presenter.completedStep("Nothing to clear; every selected root was already empty");
 
 	resetXdgCache();
-	// Bootstrapping runs even after a partial failure: the roots that were
-	// removed still need their skeleton back, and it is idempotent for the ones
-	// that survived.
-	if (!args.dryRun) initializeClioHome();
+	initializeClioHome();
+	presenter.completedStep("Recreated the empty roots");
 
 	if (failures.length > 0) {
-		printError("reset did not remove everything");
+		presenter.fail("reset did not clear everything");
 		reportRemovalFailures(resetInvocation(args), failures);
+		presenter.finish();
 		return 1;
 	}
 
-	if (args.dryRun) {
-		printOk(args.all ? "reset --all preview complete" : "reset preview complete");
-	} else {
-		printOk(args.all ? "reset config, data, state, and cache" : "reset complete");
-	}
+	presenter.done("Done");
 	return 0;
 }

package/src/cli/run.ts

@@ -29,7 +29,11 @@ import { SafetyDomainModule } from "../domains/safety/index.js";
 import { SchedulingDomainModule } from "../domains/scheduling/index.js";
 import { SessionDomainModule } from "../domains/session/index.js";
 import type { ImageContent } from "../engine/types.js";
-import { assistantTextFromEvent, receiptResponseModelIdObservationLabel } from "../tools/dispatch-event-text.js";
+import {
+	assistantTextFromEvent,
+	receiptGatewayRoutingLabel,
+	receiptResponseModelIdObservationLabel,
+} from "../tools/dispatch-event-text.js";
 import { isToolProfileName } from "../tools/profiles.js";
 import { parseRunCliArgs, type RunCliArgs } from "./args.js";
 import { runClioCommand } from "./clio.js";
@@ -261,7 +265,7 @@ export async function runClioRun(
 				// A mistyped slash command is a usage error, not a task. Refusing it
 				// here keeps it from booting a session and spending a model turn on a
 				// command that was never run, which is what the TUI has always done
-				// and what docs/extensions-and-sharing.md documents for both surfaces.
+				// and what docs/guide/extensions-and-sharing.md documents for both surfaces.
 				const slashRefusal = await unknownSlashCommandRefusal(assembled.prompt);
 				if (slashRefusal !== null) {
 					process.stderr.write(`clio-coder run: ${slashRefusal}\n`);
@@ -372,7 +376,7 @@ async function runDispatch(
 	]);
 	const config = loaded.getContract<ConfigContract>("config");
 	const baseSettings = config?.get() ?? readSettings();
-	// Install `panes.journal` the same way the interactive composition root
+	// Install `fleet.history.journal` the same way the interactive composition root
 	// does. The journal never reads settings.yaml itself: it sits on the
 	// dispatch event path, where a settings read would be both a cost and a
 	// throw site.
@@ -562,7 +566,8 @@ function formatReceipt(r: RunReceipt): string {
 		typeof r.reasoningTokenCount === "number" && r.reasoningTokenCount > 0 ? ` reasoning=${r.reasoningTokenCount}` : "";
 	const failure = r.failureMessage ? ` error=${r.failureMessage}` : "";
 	const responseModelIdObservation = receiptResponseModelIdObservationLabel(r);
-	return `receipt: ${r.runId} agent=${r.agentId} exit=${r.exitCode} target=${r.targetId} requested_model_id=${r.wireModelId}${responseModelIdObservation ? ` ${responseModelIdObservation}` : ""} tokens=${r.tokenCount}${reasoning}${failure} start=${r.startedAt} end=${r.endedAt}`;
+	const gatewayRouting = receiptGatewayRoutingLabel(r);
+	return `receipt: ${r.runId} agent=${r.agentId} exit=${r.exitCode} target=${r.targetId} requested_model_id=${r.wireModelId}${responseModelIdObservation ? ` ${responseModelIdObservation}` : ""}${gatewayRouting ? ` ${gatewayRouting}` : ""} tokens=${r.tokenCount}${reasoning}${failure} start=${r.startedAt} end=${r.endedAt}`;
 }
 
 function mapExitCode(r: RunReceipt): number {