reposets 2.0.4 → 3.1.0

package/cli/commands/doctor.js

@@ -2,11 +2,12 @@ import { SettingsGroupSchema } from "../../schemas/config.js";
 import { profileOwner } from "../../schemas/credentials.js";
 import { CONFIG_FILENAME, CREDENTIALS_FILENAME, ReposetsConfigFile, ReposetsCredentialsFile } from "../../services/ConfigFiles.js";
 import { Invocation } from "../../services/Invocation.js";
+import { STATE_DB_FILENAME } from "../../store/files.js";
 import { OP_SERVICE_ACCOUNT_TOKEN, OnePasswordClientLive } from "../../services/OnePasswordClient.js";
 import { CredentialResolver, CredentialResolverLive } from "../../services/CredentialResolver.js";
 import { ConfigFlag } from "../flags.js";
 import { Config, Console, Effect, FileSystem, Layer, Option, Path, Result } from "effect";
-import { SchemaIssueRenderer } from "@effected/cli";
+import { CliMessage, Doc, SchemaIssueRenderer, Status } from "@effected/cli";
 import { Command } from "effect/cli";
 import { AppDirs } from "@effected/xdg";
 import { GitHubClient } from "@effected/github";
@@ -234,10 +235,15 @@ const isRecord = (value) => typeof value === "object" && value !== null && !Arra
 * never resolves a reference, so there is no value in scope to leak.
 *
 * The report — failing sections included — is the command's output and goes to
-* stdout in one piece, so `reposets doctor > report.txt` captures all of it.
-* Only the three early stops (no config, unreadable, unparseable) are
-* diagnostics on stderr. `doctor` always exits 0: it describes, it does not
-* gate — `validate` is the gate.
+* stdout, so `reposets doctor > report.txt` captures all of it. It is a `Doc`
+* of sections (files, schema, config keys, credentials, the live token check,
+* required permissions) printed with `Doc.print`: plain text for an agent,
+* painted with status glyphs for a person, folded groups under GitHub Actions.
+* The file-only sections are printed before the live check, so a slow GitHub
+* never holds them back. Only the three early stops (no config, unreadable,
+* unparseable) go to stderr, as `CliMessage.failure` lines no log level can
+* hide. `doctor` always exits 0: it describes, it does not gate — `validate`
+* is the gate.
 *
 * @public
 */
@@ -293,39 +299,47 @@ const doctorHandler = (configFlag) => Effect.gen(function* () {
 	const validationIssue = discovered._tag === "Failure" ? discovered.failure.issue : void 0;
 	const configPath = sources[0]?.path ?? (yield* locateConfig(fs, path, appDirs, configFlag, invocation.cwd));
 	if (configPath === void 0) {
-		yield* Effect.logError("No config found. Run 'reposets init' to create one.");
+		yield* CliMessage.failure("No config found. Run 'reposets init' to create one.");
 		return;
 	}
-	yield* Console.log(`Config: ${configPath}`);
+	const credentialDiscovery = yield* credentialsFile.discover.pipe(Effect.result);
+	const credentialSources = credentialDiscovery._tag === "Success" ? credentialDiscovery.success : [];
+	const credentialsLine = credentialDiscovery._tag === "Failure" ? Doc.text("(failed to load — the Credentials section names the file)", "failure") : credentialSources.length === 0 ? [Doc.file(path.join(appDirs.dirs.config, CREDENTIALS_FILENAME)), Doc.text(" (not created yet)", "muted")] : Doc.file(credentialSources[0]?.path ?? "");
+	const files = Doc.section("Files", [Doc.lines([
+		["Version: ", invocation.version],
+		["Config: ", Doc.file(configPath)],
+		["Credentials file: ", ...Array.isArray(credentialsLine) ? credentialsLine : [credentialsLine]],
+		["State database: ", Doc.file(path.join(appDirs.dirs.state, STATE_DB_FILENAME))]
+	])]);
 	const text = yield* fs.readFileString(configPath).pipe(Effect.option);
 	if (text._tag === "None") {
-		yield* Effect.logError(`Could not read ${configPath}`);
+		yield* Doc.print([files]);
+		yield* CliMessage.failure(`Could not read ${configPath}`);
 		return;
 	}
 	const parsed = Toml.parseResult(text.value);
 	if (Result.isFailure(parsed)) {
-		yield* Effect.logError(`TOML parse error: ${String(parsed.failure)}`);
+		yield* Doc.print([files]);
+		yield* CliMessage.failure(`TOML parse error: ${String(parsed.failure)}`);
 		return;
 	}
 	const raw = isRecord(parsed.success) ? parsed.success : {};
-	let warnings = 0;
-	const checkKeys = (target, known, where) => Effect.gen(function* () {
+	const warnings = [];
+	const checkKeys = (target, known, where) => {
 		if (!isRecord(target)) return;
 		for (const key of Object.keys(target)) {
 			if (known.has(key)) continue;
 			const removedFrom = REMOVED_KEYS[where === "" ? key : `${key} (in groups)`] ?? REMOVED_KEYS[key];
 			if (removedFrom !== void 0) {
-				yield* Console.log(`Warning: '${key}'${where} ${removedFrom}`);
-				warnings += 1;
+				warnings.push(`'${key}'${where} ${removedFrom}`);
 				continue;
 			}
 			const suggestion = findClosestMatch(key, known);
 			const hint = suggestion === void 0 ? "" : ` — did you mean '${suggestion}'?`;
-			yield* Console.log(`Warning: unknown key '${key}'${where}${hint}`);
-			warnings += 1;
+			warnings.push(`unknown key '${key}'${where}${hint}`);
 		}
-	});
-	yield* checkKeys(raw, KNOWN_CONFIG_KEYS, "");
+	};
+	checkKeys(raw, KNOWN_CONFIG_KEYS, "");
 	const settingsSection = isRecord(raw.settings) ? raw.settings : {};
 	for (const [groupName, body] of Object.entries(settingsSection)) {
 		if (!isRecord(body)) continue;
@@ -333,37 +347,33 @@ const doctorHandler = (configFlag) => Effect.gen(function* () {
 			if (KNOWN_SETTINGS_FIELDS.has(field)) continue;
 			const suggestion = findClosestMatch(field, KNOWN_SETTINGS_FIELDS);
 			const hint = suggestion === void 0 ? " — it will be sent to GitHub as-is, which ignores fields it does not recognise" : ` — did you mean '${suggestion}'?`;
-			yield* Console.log(`Warning: unrecognised setting '${field}' in settings.${groupName}${hint}`);
-			warnings += 1;
+			warnings.push(`unrecognised setting '${field}' in settings.${groupName}${hint}`);
 		}
 	}
 	const groups = raw.groups;
 	if (isRecord(groups)) for (const [groupName, group] of Object.entries(groups)) {
-		yield* checkKeys(group, KNOWN_GROUP_KEYS, ` in groups.${groupName}`);
+		checkKeys(group, KNOWN_GROUP_KEYS, ` in groups.${groupName}`);
 		if (!isRecord(group)) continue;
 		const cleanup = group.cleanup;
 		if (!isRecord(cleanup)) continue;
 		const prefix = `groups.${groupName}.cleanup`;
-		yield* checkKeys(cleanup, KNOWN_CLEANUP_KEYS, ` in ${prefix}`);
-		yield* checkKeys(cleanup.secrets, KNOWN_CLEANUP_SECRETS_KEYS, ` in ${prefix}.secrets`);
-		yield* checkKeys(cleanup.variables, KNOWN_CLEANUP_VARIABLES_KEYS, ` in ${prefix}.variables`);
+		checkKeys(cleanup, KNOWN_CLEANUP_KEYS, ` in ${prefix}`);
+		checkKeys(cleanup.secrets, KNOWN_CLEANUP_SECRETS_KEYS, ` in ${prefix}.secrets`);
+		checkKeys(cleanup.variables, KNOWN_CLEANUP_VARIABLES_KEYS, ` in ${prefix}.variables`);
 	}
-	if (schemaValid) yield* Console.log("Schema validation: passed");
-	else {
-		yield* Console.log("Schema validation: FAILED — these values are rejected, not ignored");
-		for (const line of SchemaIssueRenderer.render(validationIssue)) yield* Console.log(`  ${line}`);
-	}
-	yield* Console.log("");
+	const issueLines = schemaValid ? [] : SchemaIssueRenderer.render(validationIssue);
+	const schema = Doc.section("Schema", [schemaValid ? Doc.paragraph(Doc.status(Status.core, "success"), " Schema validation: passed") : Doc.paragraph(Doc.status(Status.core, "failure"), " Schema validation: FAILED — these values are rejected, not ignored"), ...issueLines.length === 0 ? [] : [Doc.verbatim(issueLines.join("\n"), { indent: 2 })]]);
+	const keys = Doc.section("Config keys", [...warnings.length === 0 ? [] : [Doc.list(warnings.map((warning) => Doc.paragraph(Doc.status(Status.core, "warning"), " ", warning)), { compact: true })], warnings.length === 0 ? Doc.paragraph(Doc.status(Status.core, "success"), " No unknown keys detected.") : Doc.paragraph(`${warnings.length} warning(s) found.`)]);
 	const loaded = yield* credentialsFile.loadOrDefault({ profiles: {} }).pipe(Effect.result);
 	const credentials = loaded._tag === "Success" ? loaded.success : { profiles: {} };
 	const profileNames = Object.keys(credentials.profiles);
-	if (loaded._tag === "Failure") {
-		yield* Console.log(`Credentials: FAILED to load — ${String(loaded.failure.message ?? loaded.failure)}`);
-		yield* Console.log("  Unknown keys are rejected. `op_service_account_token` was removed — that token now comes from OP_SERVICE_ACCOUNT_TOKEN in the environment.");
-	} else if (profileNames.length === 0) yield* Console.log("Credentials: no profiles configured");
+	const credentialBlocks = [];
+	if (loaded._tag === "Failure") credentialBlocks.push(Doc.paragraph(Doc.status(Status.core, "failure"), ` Credentials: FAILED to load — ${String(loaded.failure.message ?? loaded.failure)}`), Doc.paragraph("Unknown keys are rejected. `op_service_account_token` was removed — that token now comes from OP_SERVICE_ACCOUNT_TOKEN in the environment."));
+	else if (profileNames.length === 0) credentialBlocks.push(Doc.paragraph("Credentials: no profiles configured"));
 	else {
-		yield* Console.log(`Credentials: ${profileNames.length} profile(s)`);
+		credentialBlocks.push(Doc.paragraph(`Credentials: ${profileNames.length} profile(s)`));
 		let usesOnePassword = false;
+		const profileLines = [];
 		for (const [name, profile] of Object.entries(credentials.profiles)) {
 			const token = "op" in profile.github_token ? `op ${profile.github_token.op}` : `env ${profile.github_token.env}`;
 			if ("op" in profile.github_token) usesOnePassword = true;
@@ -380,45 +390,45 @@ const doctorHandler = (configFlag) => Effect.gen(function* () {
 				}
 			}
 			const resolveSummary = sections.length === 0 ? "" : `, resolve ${sections.join(" ")}`;
-			yield* Console.log(`  [${name}] github_token: ${token}${resolveSummary}`);
+			profileLines.push(Doc.paragraph(`[${name}] github_token: ${token}${resolveSummary}`));
 		}
+		credentialBlocks.push(Doc.list(profileLines, { compact: true }));
 		const hasServiceAccount = Option.isSome(yield* Config.option(Config.String(OP_SERVICE_ACCOUNT_TOKEN)).pipe(Effect.orElseSucceed(() => Option.none())));
-		if (usesOnePassword) yield* Console.log(hasServiceAccount ? `  ${OP_SERVICE_ACCOUNT_TOKEN}: set` : `  ${OP_SERVICE_ACCOUNT_TOKEN}: NOT SET — op:// references cannot be resolved`);
+		if (usesOnePassword) credentialBlocks.push(hasServiceAccount ? Doc.paragraph(Doc.status(Status.core, "success"), ` ${OP_SERVICE_ACCOUNT_TOKEN}: set`) : Doc.paragraph(Doc.status(Status.core, "warning"), ` ${OP_SERVICE_ACCOUNT_TOKEN}: NOT SET — op:// references cannot be resolved`));
 	}
-	yield* Console.log("");
-	yield* Console.log(`Version: ${invocation.version}`);
-	const credentialDiscovery = yield* credentialsFile.discover.pipe(Effect.result);
-	const credentialSources = credentialDiscovery._tag === "Success" ? credentialDiscovery.success : [];
-	const credentialsLine = credentialDiscovery._tag === "Failure" ? "(failed to load — the error above names the file)" : credentialSources.length === 0 ? `${path.join(appDirs.dirs.config, CREDENTIALS_FILENAME)} (not created yet)` : credentialSources[0]?.path ?? "";
-	yield* Console.log(`Credentials file: ${credentialsLine}`);
-	yield* Console.log(`State database: ${path.join(appDirs.dirs.state, "store.db")}`);
-	yield* Console.log("");
+	yield* Doc.print([Doc.section(void 0, [
+		files,
+		schema,
+		keys,
+		Doc.section("Credentials", credentialBlocks)
+	])]);
+	const tokenLines = [];
 	for (const [name, profile] of Object.entries(credentials.profiles)) {
 		const resolverLayer = Layer.provide(CredentialResolverLive, OnePasswordClientLive);
 		const resolved = yield* Effect.gen(function* () {
 			return yield* (yield* CredentialResolver).resolveGitHubToken(profile);
 		}).pipe(Effect.provide(resolverLayer), Effect.result);
 		if (resolved._tag === "Failure") {
-			yield* Console.log(`Token [${name}]: could not resolve — ${String(resolved.failure)}`);
+			tokenLines.push(Doc.paragraph(Doc.status(Status.core, "failure"), ` Token [${name}]: could not resolve — ${String(resolved.failure)}`));
 			continue;
 		}
 		const identity = yield* Effect.gen(function* () {
 			return yield* (yield* GitHubClient).request("GET /user", {});
 		}).pipe(Effect.provide(GitHubClient.layerFromToken({ token: resolved.success })), Effect.result);
 		if (identity._tag !== "Success") {
-			yield* Console.log(`Token [${name}]: resolved but REJECTED by GitHub — ${String(identity.failure)}`);
+			tokenLines.push(Doc.paragraph(Doc.status(Status.core, "failure"), ` Token [${name}]: resolved but REJECTED by GitHub — ${String(identity.failure)}`));
 			continue;
 		}
 		const line = describeIdentity(name, profile, identity.success.login);
-		yield* Console.log(line.text);
+		tokenLines.push(Doc.paragraph(Doc.status(Status.core, line.ok ? "success" : "failure"), " ", line.text));
 	}
+	const permissions = Doc.section("Required fine-grained token permissions", [
+		Doc.list(REQUIRED_PERMISSIONS.map(([scope, permission, why]) => Doc.paragraph(`${scope} > ${permission} — ${why}`)), { compact: true }),
+		Doc.paragraph(Doc.text("(Metadata: Read is mandatory and granted automatically)", "muted")),
+		Doc.callout("note", [Doc.paragraph("These are NOT verified — GitHub does not expose a fine-grained token's own scopes.")])
+	]);
 	yield* Console.log("");
-	yield* Console.log("Required fine-grained token permissions:");
-	for (const [scope, permission, why] of REQUIRED_PERMISSIONS) yield* Console.log(`  ${scope} > ${permission} — ${why}`);
-	yield* Console.log("  (Metadata: Read is mandatory and granted automatically)");
-	yield* Console.log("  These are NOT verified — GitHub does not expose a fine-grained token's own scopes.");
-	yield* Console.log("");
-	yield* Console.log(warnings === 0 ? "No unknown keys detected." : `${warnings} warning(s) found.`);
+	yield* Doc.print([Doc.section(void 0, tokenLines.length === 0 ? [permissions] : [Doc.section("Token check", tokenLines), permissions])]);
 });
 /**
 * `reposets doctor`.

package/cli/commands/drift.js

@@ -27,6 +27,10 @@ import { Command, Flag } from "effect/cli";
 *
 * Exits non-zero when drift is found, so it works as a CI gate without a flag.
 *
+* Being the same handler, it shows progress the same way: a live footer for a
+* person at a terminal, labelled as a dry run, and a static summary line for
+* a pipe, an agent or CI.
+*
 * @public
 */
 const driftCommand = Command.make("drift", {

package/cli/commands/history.js

@@ -1,6 +1,8 @@
 import { SyncJournal } from "../../store/SyncJournal.js";
-import { Console, Effect } from "effect";
+import { Effect, Option } from "effect";
+import { CliInteractive, CliMessage, Doc, Fmt, Status } from "@effected/cli";
 import { CliError, Command, Flag } from "effect/cli";
+import { CliUi, Select } from "@effected/cli/ui";
 
 //#region src/cli/commands/history.ts
 const limitFlag = Flag.Int("limit").pipe(Flag.withDefault(20), Flag.withDescription("How many runs to show, newest first"));
@@ -35,38 +37,103 @@ const formatOutcome = (summary) => {
 	if (summary.outcome !== null) return summary.outcome;
 	return summary.finishedAt === null ? "interrupted" : "unknown";
 };
-/** Pad, but never truncate — a long group name is worth more than the alignment. */
-const pad = (value, width) => value.padEnd(width);
 /**
-* Render the table, sizing each column to its widest cell.
+* The status glyph an outcome is drawn with.
 *
 * @remarks
-* Computed rather than fixed because group names and repository names are
-* user-supplied and unbounded. Each line is written verbatim to stdout, so
-* alignment computed here survives to the terminal.
-*/
-const renderRows = (summaries) => {
-	const all = [{
-		id: "RUN",
-		when: "WHEN (UTC)",
-		outcome: "OUTCOME",
-		mode: "MODE",
-		group: "GROUP",
-		changes: "CHANGES",
-		took: "TOOK"
-	}, ...summaries.map((summary) => ({
-		id: summary.id.slice(0, 8),
-		when: formatWhen(summary.startedAt),
-		outcome: formatOutcome(summary),
-		mode: summary.dryRun === 1 ? "dry-run" : "applied",
-		group: summary.group ?? "(all)",
-		changes: String(summary.changes),
-		took: formatDuration(summary)
-	}))];
-	const width = (key) => Math.max(...all.map((row) => row[key].length));
-	return all.map((row) => `${pad(row.id, width("id"))}  ${pad(row.when, width("when"))}  ${pad(row.outcome, width("outcome"))}  ${pad(row.mode, width("mode"))}  ${pad(row.group, width("group"))}  ${row.changes.padStart(width("changes"))}  ${row.took}`);
+* `interrupted` is a failure, not a skip: the process died mid-run, which is
+* more alarming than a recorded failure, and must not read as benign. Only an
+* outcome this code does not recognise is drawn as `skip`.
+*/
+const outcomeStatus = (outcome) => outcome === "success" ? "success" : outcome === "partial" ? "warning" : outcome === "failed" || outcome === "interrupted" ? "failure" : "skip";
+const formatMode = (summary) => summary.dryRun === 1 ? "dry-run" : "applied";
+/** The fewest characters a displayed run id is cut to. */
+const MIN_ID_LENGTH = 8;
+/** How many leading characters two strings share. */
+const commonPrefixLength = (a, b) => {
+	let i = 0;
+	while (i < a.length && i < b.length && a[i] === b[i]) i += 1;
+	return i;
+};
+/**
+* The handle `history show` takes: each run id cut to the shortest prefix no
+* other run in the journal shares, and never shorter than eight characters.
+*
+* @remarks
+* Without a printed id the two commands do not compose: the table was the only
+* place a run id could come from, so there was no way to name a run.
+*
+* A fixed eight characters was the first answer and it was wrong. Run ids are
+* UUIDv7, whose leading 48 bits are a millisecond timestamp, so the first eight
+* hex digits only change about every 65 seconds — two runs a minute apart
+* printed the same id, and `show --run` with it was refused as ambiguous. The
+* advertised handle did not work for exactly the runs someone just made.
+*
+* So this is git's abbreviated-hash rule: eight characters while that is
+* enough, longer where it is not. In sorted order the id sharing the longest
+* prefix with any id is one of its two neighbours, so one sort and one pass
+* give every id its length. `ids` must be **every** run in the journal, not the
+* page being printed: a prefix unique within twenty rows can still match a
+* twenty-first run, and `show` matches against the journal, not the page.
+* A hyphen never ends an abbreviation — UUID hyphens sit at fixed positions,
+* so they are always shared and the first differing character is a digit.
+*/
+const abbreviator = (ids) => {
+	const sorted = [...new Set(ids)].sort();
+	const lengths = /* @__PURE__ */ new Map();
+	sorted.forEach((id, i) => {
+		const before = i > 0 ? commonPrefixLength(sorted[i - 1], id) : 0;
+		const after = i < sorted.length - 1 ? commonPrefixLength(id, sorted[i + 1]) : 0;
+		lengths.set(id, Math.max(MIN_ID_LENGTH, Math.max(before, after) + 1));
+	});
+	return (id) => id.slice(0, lengths.get(id) ?? MIN_ID_LENGTH);
 };
 /**
+* The {@link abbreviator} for this journal.
+*
+* @remarks
+* The runs about to be printed are folded in alongside the journal's ids, so a
+* run that lands between the two reads still gets a length rather than the
+* eight-character fallback.
+*/
+const journalAbbreviator = (journal, shown) => journal.runIds().pipe(Effect.map((ids) => abbreviator([...ids, ...shown.map((run) => run.id)])));
+/**
+* The run table, as a document.
+*
+* @remarks
+* A `Doc.table` sizes each column to its widest cell, which matters because
+* group and repository names are user-supplied and unbounded; it pads but never
+* truncates, so a long group name is worth more than the alignment. Plain for
+* an agent, painted for a person.
+*/
+const runTable = (summaries, abbreviate) => Doc.table([
+	{ header: "RUN" },
+	{ header: "WHEN (UTC)" },
+	{ header: "OUTCOME" },
+	{ header: "MODE" },
+	{ header: "GROUP" },
+	{
+		header: "CHANGES",
+		align: "right"
+	},
+	{ header: "TOOK" }
+], summaries.map((summary) => {
+	const outcome = formatOutcome(summary);
+	return [
+		abbreviate(summary.id),
+		formatWhen(summary.startedAt),
+		[
+			Doc.status(Status.core, outcomeStatus(outcome)),
+			" ",
+			outcome
+		],
+		formatMode(summary),
+		summary.group ?? "(all)",
+		String(summary.changes),
+		formatDuration(summary)
+	];
+}));
+/**
 * `reposets history` — what previous runs did.
 *
 * @remarks
@@ -82,15 +149,17 @@ const renderRows = (summaries) => {
 * @public
 */
 const historyHandler = (input) => Effect.gen(function* () {
-	const summaries = yield* (yield* SyncJournal).history({
+	const journal = yield* SyncJournal;
+	const summaries = yield* journal.history({
 		limit: input.limit,
 		...input.repo === void 0 ? {} : { repo: input.repo }
 	});
 	if (summaries.length === 0) {
-		yield* Console.log(input.repo === void 0 ? "No runs recorded yet. The journal fills in as you sync." : `No recorded run has touched ${input.repo}.`);
+		yield* CliMessage.info(input.repo === void 0 ? "No runs recorded yet. The journal fills in as you sync." : `No recorded run has touched ${input.repo}.`);
 		return;
 	}
-	for (const line of renderRows(summaries)) yield* Console.log(line);
+	const abbreviate = yield* journalAbbreviator(journal, summaries);
+	yield* Doc.print([runTable(summaries, abbreviate)]);
 	if (summaries.length === input.limit) yield* Effect.log(`Showing the most recent ${input.limit}. Pass --limit for more.`);
 });
 /**
@@ -102,53 +171,131 @@ const historyHandler = (input) => Effect.gen(function* () {
 * `would `. Only the three verbs that describe a write are rewritten.
 */
 const wouldForm = (action) => action === "created" ? "create" : action === "updated" ? "update" : action === "deleted" ? "delete" : action;
+/** The token an action is painted with: what it did to the resource, at a glance. */
+const actionToken = (action, dryRun) => dryRun ? "info" : action === "created" ? "success" : action === "deleted" ? "failure" : action === "drift-overwritten" ? "warning" : action === "unchanged" ? "muted" : "info";
+/**
+* The refusal for a missing `--run` where nobody can be asked.
+*
+* @remarks
+* A usage error (exit 64) naming the flag, and the command that lists the ids
+* to pass to it — the same answer a person gets from the picker, spelled out
+* for a script.
+*/
+const runRequired = () => new CliError.UserError({ cause: "Pass --run <id> (a run id or a unique prefix); `reposets history` lists them." });
+/**
+* How many recent runs the picker offers.
+*
+* @remarks
+* The question it answers is "what did that run just now do", so the newest
+* runs are the ones worth scrolling; an older run is still reachable by
+* `--run` with its id from `reposets history --limit`.
+*/
+const PICKER_RUNS = 50;
+/**
+* Which run to show, when `--run` was not given.
+*
+* @remarks
+* Interactive, a `Select` over the recent runs, each labelled the way the
+* table names it — short id, when, outcome, group — with mode, change count and
+* duration as detail. Esc is the kit's `Cancelled`, left to propagate so
+* `CliRuntime.main` prints its one line and exits 130; a cancelled question is
+* not a successful answer.
+*
+* Called only for an interactive run: `showHandler` refuses a
+* non-interactive one (an agent, CI, a pipe) before reaching here, exactly as a
+* missing required flag would — exit 64, naming `--run`.
+*/
+const pickRun = (runs, abbreviate) => Effect.gen(function* () {
+	return yield* CliUi.prompt(Select.screen({
+		message: "Which run?",
+		choices: runs.slice(0, PICKER_RUNS).map((run) => {
+			const outcome = formatOutcome(run);
+			return {
+				label: `${abbreviate(run.id)} · ${formatWhen(run.startedAt)} · ${outcome} · ${Fmt.sanitize(run.group ?? "(all)")}`,
+				detail: `${formatMode(run)} · ${run.changes} change${run.changes === 1 ? "" : "s"} · ${formatDuration(run)}`,
+				value: run
+			};
+		})
+	})).pipe(Effect.catchTag("NotInteractive", () => Effect.fail(runRequired())));
+});
+/**
+* Resolve a prefix to exactly one run, or refuse.
+*
+* @remarks
+* Both refusals are usage errors — the user named a run that is not there, or
+* not uniquely — so they fail with `UserError` and exit 64. `Command.runWith`
+* prints the message once, on stderr.
+*/
+const matchRun = (runs, prefix) => {
+	const matches = runs.filter((run) => run.id.startsWith(prefix));
+	if (matches.length === 0) return Effect.fail(new CliError.UserError({ cause: `No run matches '${prefix}'.` }));
+	if (matches.length > 1) {
+		const candidates = matches.slice(0, 5).map((run) => `  ${run.id}  ${formatWhen(run.startedAt)}`);
+		return Effect.fail(new CliError.UserError({ cause: [`'${prefix}' matches ${matches.length} runs. Use more of the id:`, ...candidates].join("\n") }));
+	}
+	return Effect.succeed(matches[0]);
+};
 /**
-* `reposets history show <run>` — every resource one run touched.
+* `reposets history show [--run <id>]` — every resource one run touched.
 *
 * @remarks
 * The journal has recorded these from the start and nothing surfaced them, so
 * `12 changes` was a number with no way to ask *which twelve*.
 *
 * The id may be given in full or as a unique prefix, because nobody is going to
-* retype a UUID from a table.
+* retype a UUID from a table. Without `--run`, a person at a terminal picks
+* from the recent runs and anyone else is refused with exit 64 (see
+* {@link pickRun}). The refusal comes first and does not look at the journal,
+* so a script's `history show` without `--run` is exit 64 whether or not any
+* run is recorded. Only a person with an empty journal is told "No runs
+* recorded yet" and exits 0 — there is nothing to pick, as `reposets history`
+* says.
+*
+* The report is a `Doc` — the run header, its error, then the changes grouped
+* by repository — printed for whoever is reading.
 */
 const showHandler = (prefix) => Effect.gen(function* () {
 	const journal = yield* SyncJournal;
-	const matches = (yield* journal.history({ limit: 1e3 }).pipe(Effect.orElseSucceed(() => []))).filter((run) => run.id.startsWith(prefix));
-	if (matches.length === 0) return yield* Effect.fail(new CliError.UserError({ cause: `No run matches '${prefix}'.` }));
-	if (matches.length > 1) {
-		const candidates = matches.slice(0, 5).map((run) => `  ${run.id}  ${formatWhen(run.startedAt)}`);
-		return yield* Effect.fail(new CliError.UserError({ cause: [`'${prefix}' matches ${matches.length} runs. Use more of the id:`, ...candidates].join("\n") }));
-	}
-	const run = matches[0];
+	const runs = yield* journal.history({ limit: 1e3 }).pipe(Effect.orElseSucceed(() => []));
+	let run;
+	if (prefix === void 0) {
+		if (!(yield* CliInteractive)) return yield* Effect.fail(runRequired());
+		if (runs.length === 0) {
+			yield* CliMessage.info("No runs recorded yet. The journal fills in as you sync.");
+			return;
+		}
+		const abbreviate = yield* journalAbbreviator(journal, runs).pipe(Effect.orElseSucceed(() => abbreviator(runs.map((r) => r.id))));
+		run = yield* pickRun(runs, abbreviate);
+	} else run = yield* matchRun(runs, prefix);
 	const changes = yield* journal.changesFor(run.id).pipe(Effect.orElseSucceed(() => []));
-	yield* Console.log(`run ${run.id}`);
-	yield* Console.log(`  ${formatWhen(run.startedAt)} · ${run.dryRun === 1 ? "dry-run" : "applied"} · ${run.outcome ?? "unfinished"} · ${formatDuration(run)}`);
-	yield* Console.log("");
-	if (run.error !== null && run.error !== "") {
-		yield* Console.log(`  error: ${run.error}`);
-		yield* Console.log("");
-	}
-	if (changes.length === 0) {
-		yield* Console.log(run.error !== null && run.error !== "" ? "  No resources changed." : "  No resources changed (nothing to do).");
-		return;
-	}
-	const byRepo = /* @__PURE__ */ new Map();
-	for (const change of changes) {
-		const existing = byRepo.get(change.repo);
-		if (existing === void 0) byRepo.set(change.repo, [change]);
-		else existing.push(change);
-	}
-	for (const [repo, records] of byRepo) {
-		yield* Console.log(`  ${repo}`);
-		for (const record of records) {
+	const outcome = run.outcome ?? "unfinished";
+	const failed = run.error !== null && run.error !== "";
+	const body = [Doc.paragraph(Doc.status(Status.core, outcomeStatus(run.outcome ?? "interrupted")), " ", `${formatWhen(run.startedAt)} · ${formatMode(run)} · ${outcome} · ${formatDuration(run)}`)];
+	if (failed) body.push(Doc.paragraph(Doc.text("error: ", "failure"), run.error ?? ""));
+	if (changes.length === 0) body.push(Doc.paragraph(failed ? "No resources changed." : "No resources changed (nothing to do)."));
+	else {
+		const byRepo = /* @__PURE__ */ new Map();
+		for (const change of changes) {
+			const existing = byRepo.get(change.repo);
+			if (existing === void 0) byRepo.set(change.repo, [change]);
+			else existing.push(change);
+		}
+		const dryRun = run.dryRun === 1;
+		body.push(Doc.list([...byRepo].map(([repo, records]) => Doc.section(repo, [Doc.lines(records.map((record) => {
 			const detail = record.detail === void 0 || record.detail === null ? "" : ` — ${record.detail}`;
 			const what = record.kind === record.name ? record.kind : `${record.kind} ${record.name}`;
-			const action = run.dryRun === 1 ? `would ${wouldForm(record.action)}` : record.action;
-			yield* Console.log(`    ${action.padEnd(18)} ${what}${detail}`);
-		}
+			const action = dryRun ? `would ${wouldForm(record.action)}` : record.action;
+			return [
+				Doc.text(action.padEnd(18), actionToken(record.action, dryRun)),
+				" ",
+				what,
+				detail
+			];
+		}))])), { compact: true }));
 	}
+	yield* Doc.print([Doc.section(`run ${run.id}`, body)]);
 });
+const UNTOUCHED = "Applied state and the cache are untouched — drift detection still works.";
 /**
 * `reposets history prune|clear` — the journal, and only the journal.
 *
@@ -158,16 +305,23 @@ const showHandler = (prefix) => Effect.gen(function* () {
 * against; deleting those does not tidy anything, it disarms the check, so the
 * next run reports a first sync where an out-of-band edit actually happened.
 * A command that quietly did both would be the most dangerous thing in this CLI.
+*
+* The result is a `CliMessage` line, and so is the statement that the
+* baselines survived: said every time, because the sentence matters as much as
+* the deletion.
 */
 const pruneHandler = (keep) => Effect.gen(function* () {
 	const removed = yield* (yield* SyncJournal).prune(keep).pipe(Effect.orElseSucceed(() => 0));
-	yield* Console.log(removed === 0 ? `Nothing to prune; ${keep} or fewer runs are recorded.` : `Pruned ${removed} run${removed === 1 ? "" : "s"}, keeping the newest ${keep}.`);
-	yield* Console.log("Applied state and the cache are untouched — drift detection still works.");
+	yield* removed === 0 ? CliMessage.info(`Nothing to prune; ${keep} or fewer runs are recorded.`) : CliMessage.success(`Pruned ${removed} run${removed === 1 ? "" : "s"}, keeping the newest ${keep}.`);
+	yield* CliMessage.info(UNTOUCHED);
 });
+/**
+* `reposets history clear` — every run, and nothing else; see {@link pruneHandler}.
+*/
 const clearHandler = () => Effect.gen(function* () {
 	const removed = yield* (yield* SyncJournal).clear().pipe(Effect.orElseSucceed(() => 0));
-	yield* Console.log(`Cleared ${removed} run${removed === 1 ? "" : "s"} from the journal.`);
-	yield* Console.log("Applied state and the cache are untouched — drift detection still works.");
+	yield* CliMessage.success(`Cleared ${removed} run${removed === 1 ? "" : "s"} from the journal.`);
+	yield* CliMessage.info(UNTOUCHED);
 });
 /**
 * `reposets history`.
@@ -181,7 +335,7 @@ const historyCommand = Command.make("history", {
 	limit,
 	repo: repo._tag === "Some" ? repo.value : void 0
 })).pipe(Command.withDescription("Show what previous sync runs did, newest first"), Command.withSubcommands([
-	Command.make("show", { run: Flag.String("run").pipe(Flag.withDescription("A run id, or a unique prefix")) }, ({ run }) => showHandler(run)).pipe(Command.withDescription("Show every resource one run touched")),
+	Command.make("show", { run: Flag.String("run").pipe(Flag.optional, Flag.withDescription("A run id, or a unique prefix; omitted, a terminal picks from recent runs")) }, ({ run }) => showHandler(Option.getOrUndefined(run))).pipe(Command.withDescription("Show every resource one run touched")),
 	Command.make("prune", { keep: Flag.Int("keep").pipe(Flag.withDefault(50), Flag.withDescription("How many of the newest runs to keep")) }, ({ keep }) => pruneHandler(keep)).pipe(Command.withDescription("Delete all but the newest runs from the journal")),
 	Command.make("clear", {}, () => clearHandler()).pipe(Command.withDescription("Delete every run from the journal"))
 ]));