magus-cli 0.0.0-placeholder → 7.0.0

package/src/cli/live.ts

@@ -0,0 +1,374 @@
+/**
+ * live.ts — an in-place animated block that leaves its record in scrollback.
+ *
+ * `magus update` spends most of its wall clock inside three calls that print
+ * nothing: git pulls over the network, a catalog read, then serial binary
+ * probes. Then the apply loop prints one line per plugin, each only once that
+ * plugin has finished installing. The terminal sat frozen for the slow parts,
+ * which reads as a hang.
+ *
+ * This is the fix, and it is deliberately NOT a renderer. Two channels:
+ *
+ *   - `note()` writes a PERMANENT line. It is the record, it scrolls, and it is
+ *     printed in every mode including a pipe. Anything a user might paste into
+ *     a bug report goes here.
+ *   - `start(render)` drives a TRANSIENT block under that record, repainted on
+ *     a timer so a spinner keeps moving while an await is outstanding. It is
+ *     erased before the next note and again on `stop()`.
+ *
+ * The split is what lets the same command be both animated and pipeable. In a
+ * pipe, in CI, or under NO_COLOR the transient block is simply never painted;
+ * the notes still print, in order, exactly as before.
+ *
+ * ## Why the region hijacks `console`
+ *
+ * Anything printed while the region is live must go through `note()`. A bare
+ * `console.log` lands inside the block, and the next repaint's cursor-up count
+ * is then short by however many rows it wrote — so the erase starts partway
+ * INTO the block, leaves orphaned rows on screen, and scrolls the message that
+ * caused it out of reach.
+ *
+ * That was documented as a rule and it was not enough. `getAvailablePlugins`
+ * reaches `plugin-manager.ts`'s stale-marketplace advisory through two call
+ * layers, and it printed with a bare `console.log` from inside the catalog
+ * step: the advisory was erased unread and the frame smeared, every time a
+ * marketplace clone was stale. A rule that has to hold across a call graph this
+ * file does not own is not a rule, it is a hope.
+ *
+ * So the region CAPTURES `console` for as long as it is painting, and routes
+ * every write through the same erase-write-repaint path `note()` uses. The
+ * invariant is now a mechanism. Streams are preserved: `log`/`info` keep going
+ * to stdout and `warn`/`error` to stderr, because stderr is legitimately
+ * redirected on its own and silently moving it to stdout would break that.
+ */
+
+import { format } from "node:util";
+import { colorEnabled, truncate, width } from "./ansi.js";
+
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+/** Erase from the cursor to the end of the display. */
+const ERASE_BELOW = "\x1b[0J";
+
+/**
+ * Cursor visibility and a patched `console` are process-global state, so
+ * restoring them is too.
+ *
+ * A region killed by Ctrl+C or a crash without this leaves the user typing
+ * blind in their shell — a genuinely hostile failure they have to fix with
+ * `reset`. Registered once, on first use, and never removed.
+ */
+let restoreHooked = false;
+const liveRegions = new Set<LiveRegion>();
+
+function hookRestore(): void {
+	if (restoreHooked) return;
+	restoreHooked = true;
+	const restore = () => {
+		for (const region of liveRegions) region.forceRestore();
+	};
+	process.on("exit", restore);
+	// 128 + signum is the shell convention: SIGINT 130, SIGTERM 143, SIGHUP 129.
+	// Reporting 130 for all three told a CI runner "interrupted" when it had
+	// actually sent SIGTERM.
+	for (const [signal, signum] of [
+		["SIGINT", 2],
+		["SIGTERM", 15],
+		["SIGHUP", 1],
+	] as const) {
+		process.on(signal, () => {
+			restore();
+			process.exit(128 + signum);
+		});
+	}
+}
+
+export interface LiveOptions {
+	stream?: NodeJS.WriteStream;
+	/** Stderr sink for captured `console.warn`/`console.error`. */
+	errorStream?: NodeJS.WriteStream;
+	/** Repaints per second. 12 reads as motion without strobing the spinner. */
+	fps?: number;
+	/** Force the transient block on or off. Default: TTY and colour capable. */
+	animate?: boolean;
+	/**
+	 * Capture `console` while painting. On by default — see the file header.
+	 * Off only for tests that need to assert on the real console.
+	 */
+	captureConsole?: boolean;
+}
+
+/** A frame, rebuilt from scratch each repaint. `tick` advances once per frame. */
+export type RenderFrame = (tick: number) => string[];
+
+type ConsoleMethod = "log" | "info" | "warn" | "error";
+
+export class LiveRegion {
+	private readonly stream: NodeJS.WriteStream;
+	private readonly errorStream: NodeJS.WriteStream;
+	private readonly interval: number;
+	private readonly wantsConsoleCapture: boolean;
+	/** Rows the transient block currently occupies. 0 means nothing is painted. */
+	private painted = 0;
+	private timer: ReturnType<typeof setInterval> | null = null;
+	private render: RenderFrame | null = null;
+	private tick = 0;
+	private cursorHidden = false;
+	/** True between `pause()` and `resume()`: something else owns the terminal. */
+	private paused = false;
+	private restoreConsole: (() => void) | null = null;
+	private onResize: (() => void) | null = null;
+
+	/** Whether the transient block is painted at all. */
+	readonly animated: boolean;
+
+	constructor(opts: LiveOptions = {}) {
+		this.stream = opts.stream ?? process.stdout;
+		this.errorStream = opts.errorStream ?? process.stderr;
+		this.interval = Math.max(1, Math.round(1000 / (opts.fps ?? 12)));
+		this.wantsConsoleCapture = opts.captureConsole ?? true;
+		this.animated =
+			opts.animate ?? (this.stream.isTTY === true && colorEnabled());
+		liveRegions.add(this);
+	}
+
+	/** Begin animating `render`. Replaces any frame already running. */
+	start(render: RenderFrame): void {
+		this.render = render;
+		if (!this.animated) return;
+		this.hideCursor();
+		this.captureConsole();
+		this.watchResize();
+		this.paint();
+		this.startTimer();
+	}
+
+	/** Repaint now rather than waiting for the next tick, after a state change. */
+	refresh(): void {
+		if (this.animated && this.render && !this.paused) this.paint();
+	}
+
+	/**
+	 * Write permanent lines above the block: the scrollback record.
+	 *
+	 * Erase, write, repaint — in that order. Writing first would put the line
+	 * below the block, where the next repaint's cursor-up arithmetic would
+	 * count it as part of the frame and start eating the record.
+	 */
+	note(...lines: string[]): void {
+		this.writeThrough(this.stream, lines);
+	}
+
+	/** The same, on stderr — for captured `console.warn` / `console.error`. */
+	noteError(...lines: string[]): void {
+		this.writeThrough(this.errorStream, lines);
+	}
+
+	/**
+	 * Hand the terminal to something else — a readline prompt, or a subprocess
+	 * inheriting stdio. Both move the cursor themselves, so the block has to be
+	 * gone and the cursor visible before either starts.
+	 *
+	 * `console` goes back to normal here too: whatever now owns the terminal is
+	 * writing to it directly, so routing through a region that is not painting
+	 * would reorder its output.
+	 */
+	pause(): void {
+		this.paused = true;
+		this.stopTimer();
+		this.erase();
+		this.releaseConsole();
+		this.showCursor();
+	}
+
+	/** Take the terminal back after `pause()`. */
+	resume(): void {
+		this.paused = false;
+		if (!this.animated || !this.render) return;
+		this.hideCursor();
+		this.captureConsole();
+		this.paint();
+		this.startTimer();
+	}
+
+	/**
+	 * Stop animating. `final` is written as a permanent record — the transient
+	 * frame is erased first, so the last thing on screen is the record and not a
+	 * spinner frozen mid-rotation.
+	 */
+	stop(final: string[] = []): void {
+		this.stopTimer();
+		this.erase();
+		this.render = null;
+		this.paused = false;
+		this.releaseConsole();
+		this.unwatchResize();
+		for (const line of final) this.stream.write(`${line}\n`);
+		this.showCursor();
+		liveRegions.delete(this);
+	}
+
+	/** Exit hook only: put global state back without touching anything else. */
+	forceRestore(): void {
+		this.releaseConsole();
+		this.showCursor();
+	}
+
+	// -- internals -------------------------------------------------------------
+
+	private startTimer(): void {
+		if (this.timer) return;
+		this.timer = setInterval(() => {
+			this.tick++;
+			this.paint();
+		}, this.interval);
+		// Never let the repaint timer be the reason the process stays alive.
+		this.timer.unref?.();
+	}
+
+	private stopTimer(): void {
+		if (this.timer) {
+			clearInterval(this.timer);
+			this.timer = null;
+		}
+	}
+
+	/** Erase, write the lines to `to`, repaint. The one safe write order. */
+	private writeThrough(to: NodeJS.WriteStream, lines: string[]): void {
+		if (lines.length === 0) return;
+		this.erase();
+		for (const line of lines) to.write(`${line}\n`);
+		// Never repaint while paused: something else owns the terminal, and a
+		// frame drawn under its output is both corrupt and in the way.
+		if (this.animated && this.render && !this.paused) this.paint();
+	}
+
+	/**
+	 * Route `console` through this region for as long as it is painting.
+	 *
+	 * Multi-line and format-string calls are handled by `util.format`, then
+	 * split, so `console.log("a\nb")` becomes two permanent rows rather than one
+	 * row containing a newline the erase arithmetic cannot see.
+	 */
+	private captureConsole(): void {
+		if (this.restoreConsole || !this.animated || !this.wantsConsoleCapture)
+			return;
+		const original: Record<ConsoleMethod, (...args: unknown[]) => void> = {
+			log: console.log,
+			info: console.info,
+			warn: console.warn,
+			error: console.error,
+		};
+		const route =
+			(method: ConsoleMethod, toStderr: boolean) =>
+			(...args: unknown[]) => {
+				if (this.paused || !this.render) {
+					original[method](...args);
+					return;
+				}
+				const lines = format(...args).split("\n");
+				if (toStderr) this.noteError(...lines);
+				else this.note(...lines);
+			};
+		console.log = route("log", false);
+		console.info = route("info", false);
+		console.warn = route("warn", true);
+		console.error = route("error", true);
+		this.restoreConsole = () => {
+			console.log = original.log;
+			console.info = original.info;
+			console.warn = original.warn;
+			console.error = original.error;
+			this.restoreConsole = null;
+		};
+	}
+
+	private releaseConsole(): void {
+		this.restoreConsole?.();
+	}
+
+	/**
+	 * A resize invalidates `painted`.
+	 *
+	 * `painted` is a row count measured at the OLD width, so after a narrowing
+	 * the block occupies more rows than it says and the cursor-up erase lands
+	 * inside it. There is no way to recover the true count, so the old frame is
+	 * abandoned where it stands — one stale block left in scrollback, once —
+	 * rather than mis-erased on every subsequent frame.
+	 */
+	private watchResize(): void {
+		if (this.onResize || typeof this.stream.on !== "function") return;
+		this.onResize = () => {
+			this.painted = 0;
+			if (this.animated && this.render && !this.paused) this.paint();
+		};
+		this.stream.on("resize", this.onResize);
+	}
+
+	private unwatchResize(): void {
+		if (!this.onResize) return;
+		this.stream.off?.("resize", this.onResize);
+		this.onResize = null;
+	}
+
+	private hideCursor(): void {
+		if (this.cursorHidden || !this.animated) return;
+		this.stream.write(HIDE_CURSOR);
+		this.cursorHidden = true;
+		// Only now is there global state worth restoring on the way out.
+		hookRestore();
+	}
+
+	private showCursor(): void {
+		if (!this.cursorHidden) return;
+		this.stream.write(SHOW_CURSOR);
+		this.cursorHidden = false;
+	}
+
+	private erase(): void {
+		if (this.painted === 0) return;
+		this.stream.write(`\x1b[${this.painted}A${ERASE_BELOW}`);
+		this.painted = 0;
+	}
+
+	/**
+	 * Repaint the block.
+	 *
+	 * Two clamps, both load-bearing. Lines are clipped one column short of the
+	 * terminal width, because a line that reaches the last column auto-wraps in
+	 * most terminals and then occupies two rows while `painted` still counts it
+	 * as one — the block smears a row further down the screen every frame. And
+	 * the block is capped one row short of the terminal height, because a block
+	 * taller than the viewport scrolls the terminal and moves the rows the next
+	 * cursor-up was aiming at.
+	 */
+	private paint(): void {
+		if (!this.animated || !this.render) return;
+		const cols = Math.max(20, this.stream.columns ?? 80);
+		const rows = Math.max(4, this.stream.rows ?? 24);
+		let lines = this.render(this.tick).map((l) =>
+			width(l) > cols - 1 ? truncate(l, cols - 1) : l,
+		);
+		if (lines.length > rows - 1) lines = lines.slice(0, rows - 1);
+		this.erase();
+		if (lines.length === 0) return;
+		this.stream.write(`${lines.join("\n")}\n`);
+		this.painted = lines.length;
+	}
+}
+
+/**
+ * Run `work` with the terminal handed back — for readline and for subprocesses
+ * that inherit stdio. Always resumes, including when `work` throws.
+ */
+export async function withPaused<T>(
+	region: LiveRegion,
+	work: () => Promise<T>,
+): Promise<T> {
+	region.pause();
+	try {
+		return await work();
+	} finally {
+		region.resume();
+	}
+}

package/src/cli/models.ts

@@ -0,0 +1,297 @@
+/**
+ * `magus models list | use <preset> | status | off`
+ *
+ * The user-facing half of per-subagent model routing. Everything it prints is
+ * derived from `services/models-manager.ts`; this file owns wording and exit
+ * codes only.
+ *
+ * Exit codes: 1 for an unknown preset or a config that fails validation, 0
+ * otherwise. An unknown preset LISTS the valid names rather than near-matching
+ * one — `fable-lead` and `fable-advisor` differ by which model leads, and
+ * silently picking the closer string would route every subagent differently
+ * from what was asked.
+ */
+
+import {
+	BUILT_IN_PRESETS,
+	DEFAULT_PRESET,
+	presetLabel,
+	presetNames,
+} from "../data/models-presets.js";
+import {
+	loadMateCatalog,
+	stalenessNote,
+	unknownBindings,
+} from "../services/mate-catalog.js";
+import {
+	GRADES,
+	type ModelsConfig,
+	type ModelsState,
+	boundModel,
+	isMate,
+	mateEffort,
+	matesInUse,
+	sameRouting,
+} from "../services/models-core.js";
+import {
+	applyModelPreset,
+	clearModels,
+	configPath,
+	readModelsConfig,
+	readModelsStatus,
+} from "../services/models-manager.js";
+import { ensureManifest } from "./bootstrap.js";
+
+const HEADLINE: Record<ModelsState, string> = {
+	off: "off — no .claude/models.json, subagents inherit the session model",
+	on: "on",
+	invalid: "invalid — nothing is routed",
+	unhooked: "unhooked — the config is there, but nothing runs it",
+};
+
+/**
+ * `opus (medium)`, or `opus` when no effort is set.
+ *
+ * A mate prints the SLOT and what it is bound to — `mate1 → grok-4.6` — because both are
+ * answers to different questions the reader has: which role this tier plays, and which model
+ * plays it. The slot alone was all that could be printed before the `mates` block existed,
+ * and a bare `kangaroo` in a column of `opus (xhigh)` read as a model id nobody recognises.
+ *
+ * An effort on a mate is qualified `(declared)`, for the reason spelled out at
+ * `DECLARED_SUFFIX`: magus writes it for claudish and nothing applies it yet, so printing
+ * a bare `(high)` beside a tier where `(high)` IS in force would claim they do the same
+ * thing.
+ */
+function describeSpec(
+	config: ModelsConfig,
+	spec: { model: string; effort?: string },
+): string {
+	if (isMate(spec.model)) {
+		const bound = boundModel(config, spec.model);
+		const effort = spec.effort ?? mateEffort(config, spec.model);
+		const target = bound ?? "unbound";
+		const note = effort ? `${effort} declared, via claudish` : "via claudish";
+		return `${spec.model} → ${target} (${note})`;
+	}
+	return spec.effort ? `${spec.model} (${spec.effort})` : spec.model;
+}
+
+/**
+ * A preset headed by what a person would call it, with the id beside it.
+ *
+ * Both, deliberately: the label is what you choose between ("Opus with Fable help" says which
+ * model leads and which helps), and the id is what you TYPE into `models use` and what lands
+ * in the committed config. Printing only the label would leave the command unguessable.
+ */
+function printPreset(preset: ModelsConfig, active: boolean): void {
+	const mark = active ? "●" : " ";
+	const isDefault = preset.preset === DEFAULT_PRESET ? "  (default)" : "";
+	console.log(
+		`${mark} ${presetLabel(preset.preset)}  —  ${preset.preset}${isDefault}`,
+	);
+	console.log(`    main       ${describeSpec(preset, preset.main)}`);
+	for (const grade of GRADES) {
+		console.log(
+			`    ${grade.padEnd(10)} ${describeSpec(preset, preset.grades[grade])}`,
+		);
+	}
+}
+
+async function runList(projectPath: string): Promise<number> {
+	const { config } = await readModelsConfig(projectPath);
+
+	// Has the project diverged from the built-in it NAMES?
+	//
+	// The test used to be "does it name a preset the built-ins do not", which misses the
+	// ordinary case: `magus models use opus-lead` writes that name, and every hand edit
+	// afterwards leaves it in place. So a config with a `mates` block was reported as the
+	// built-in `opus-lead`, and the `●` sat on a preset that is not what runs. Compared by
+	// CONTENT, shared with the TUI through `sameRouting` so the two cannot disagree about
+	// which routing is in force.
+	const builtInNamed = BUILT_IN_PRESETS.find(
+		(preset) => preset.preset === config?.preset,
+	);
+	const diverged =
+		config !== null && (!builtInNamed || !sameRouting(config, builtInNamed));
+
+	console.log("\nModel tiers:\n");
+	for (const preset of BUILT_IN_PRESETS) {
+		printPreset(preset, !diverged && config?.preset === preset.preset);
+		console.log();
+	}
+	if (config && diverged) {
+		// The project's own config gets its tiers PRINTED, not just its name.
+		//
+		// It is the routing actually in force, and it is the only config here that can name a
+		// mate — no built-in does — so printing the name alone hid the one line a reader came
+		// for. The built-ins above are shown in full; showing the active one in less detail
+		// than the ones it replaced was backwards.
+		printPreset(config, true);
+		console.log("    (this project's own, not a built-in)\n");
+	}
+
+	// Which agents leave Claude Code entirely.
+	//
+	// `models list` prints tiers, never agents, so a mate assigned per-agent — the ordinary
+	// way to use one — appears nowhere else in this command's output. It is also the one
+	// routing decision here that magus does not carry out itself, which makes it exactly
+	// the thing worth naming rather than leaving to be discovered in the file.
+	const mated = Object.entries(config?.agents ?? {}).filter(
+		([, assignment]) =>
+			typeof assignment !== "string" && isMate(assignment.model),
+	);
+	if (config && mated.length > 0) {
+		console.log("Routed outside Claude Code, through claudish:\n");
+		for (const [agent, assignment] of mated) {
+			const slot =
+				typeof assignment === "string" ? assignment : assignment.model;
+			// The SLOT and the model it names. The slot is what the file says and what the
+			// reader greps for; the bound id is what actually runs. Printing only the slot was
+			// the CLI's version of the screen's `mate1 mate1 —` — a role where a model belongs.
+			const bound = isMate(slot) ? boundModel(config, slot) : null;
+			const target = bound ?? "unbound — add it to the mates block";
+			console.log(`    ${agent.padEnd(28)} ${slot.padEnd(10)} ${target}`);
+		}
+		console.log();
+
+		// The staleness advisory, on the same terms as everywhere else: ADVISORY, and silent
+		// when the catalogue could not be read. `unknownBindings` returns nothing for an empty
+		// catalogue, so a machine without claudish prints no note rather than flagging every
+		// binding it cannot check.
+		const bound = matesInUse(config)
+			.map((mate) => boundModel(config, mate))
+			.filter((id): id is string => id !== null);
+		const note = stalenessNote(unknownBindings(bound, await loadMateCatalog()));
+		if (note) console.log(`⚠ ${note}\n`);
+	}
+
+	console.log(
+		"Tiers name what a subagent is FOR: `smart` takes the judgement calls, `cheap`",
+	);
+	console.log(
+		"the searching. Which model serves each is the preset's call. Apply one with\n`magus models use <name>`.\n",
+	);
+	return 0;
+}
+
+async function runStatus(projectPath: string): Promise<number> {
+	const status = await readModelsStatus(projectPath);
+	console.log(`\nModel tiers: ${HEADLINE[status.state]}`);
+	if (status.preset)
+		console.log(
+			`Preset:      ${presetLabel(status.preset)} (${status.preset})`,
+		);
+	console.log(`Config:      ${configPath(projectPath)}`);
+
+	if (status.drift.length > 0) {
+		console.log(status.state === "invalid" ? "\nErrors:" : "\nDrift:");
+		for (const line of status.drift) console.log(`  ✗ ${line}`);
+		if (status.state === "unhooked") console.log("\n  Fix: magus doctor --fix");
+	}
+	for (const warning of status.warnings) console.log(`\n⚠ ${warning}`);
+	console.log();
+	return status.state === "invalid" ? 1 : 0;
+}
+
+async function runUse(projectPath: string, name?: string): Promise<number> {
+	if (!name) {
+		console.error("Usage: magus models use <preset>");
+		console.error(`Available: ${presetNames().join(", ")}`);
+		return 1;
+	}
+	if (!presetNames().includes(name)) {
+		// Never near-match. See the file header.
+		console.error(`Unknown preset "${name}".`);
+		console.error(`Available: ${presetNames().join(", ")}`);
+		return 1;
+	}
+
+	let result: Awaited<ReturnType<typeof applyModelPreset>>;
+	try {
+		result = await applyModelPreset({
+			projectPath,
+			preset: name,
+			ensureManifest: (p) => ensureManifest(p),
+		});
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+
+	console.log(`\n✓ Applied preset "${name}".`);
+	console.log(`  ${configPath(projectPath)}`);
+	console.log(`  ${result.settingsPath}`);
+	for (const [key, value] of Object.entries(result.wrote)) {
+		console.log(`    ${key} = ${JSON.stringify(value)}`);
+	}
+	console.log(
+		`  hook: ${result.hook === "registered" ? "registered at user scope" : "already registered"}`,
+	);
+
+	if (result.recordedInManifest && result.profile) {
+		console.log(
+			`\nRecorded in .claude/profiles.json under profiles.${result.profile}.`,
+		);
+		console.log("Commit .claude/profiles.json to share this with the team.");
+	} else {
+		console.log(
+			"\nNo active profile — written straight to .claude/models.json, which is",
+		);
+		console.log(
+			"generated and gitignored. Run `magus install` to adopt a profile if the",
+		);
+		console.log("team should share this routing.");
+	}
+	console.log();
+	return 0;
+}
+
+async function runOff(projectPath: string): Promise<number> {
+	await clearModels(projectPath);
+	console.log(
+		"\n✓ Model tiers off. Subagents inherit the session model again.",
+	);
+	console.log(
+		"  The hook stays registered — it is a no-op without a models.json.\n",
+	);
+	return 0;
+}
+
+function printUsage(): void {
+	console.log(`Usage: magus models <command>
+
+  list            Show the built-in tier presets; ● marks the active one
+  use <preset>    Apply a preset to this project and register the hook
+  status          What is routed right now, and any drift
+  off             Turn model tiers off (removes the config, keeps the hook)
+
+Available presets: ${presetNames().join(", ")}`);
+}
+
+/**
+ * `projectPath` defaults to the cwd, which is what the router passes. It is a
+ * parameter so tests can drive a temp project without moving the process —
+ * `cli/profile.ts` takes the same shape for the same reason.
+ */
+export async function runModelsCommand(
+	args: string[],
+	projectPath: string = process.cwd(),
+): Promise<number> {
+	const [command, ...rest] = args;
+
+	switch (command) {
+		case undefined:
+		case "status":
+			return runStatus(projectPath);
+		case "list":
+			return runList(projectPath);
+		case "use":
+			return runUse(projectPath, rest[0]);
+		case "off":
+			return runOff(projectPath);
+		default:
+			console.error(`Unknown models command "${command}".`);
+			printUsage();
+			return 1;
+	}
+}