@wahack/pi-coding-agent 15.11.0

package/src/cli.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env bun
+// Strip macOS malloc-stack-logging vars in the parent entrypoint, before any
+// subprocess/worker spawn. libmalloc reads MallocStackLogging /
+// MallocStackLoggingNoCompact during malloc bootstrap (pre-main) in every child
+// and warns when they're present but set to "off"; a child cannot suppress its
+// own warning, so the only fix is to keep them out of the inherited env here.
+// (They must be unset, not set — presence is the trigger.)
+try {
+	delete process.env.MallocStackLogging;
+	delete process.env.MallocStackLoggingNoCompact;
+} catch {}
+
+/**
+ * CLI entry point — registers all commands explicitly and delegates to the
+ * lightweight CLI runner from pi-utils.
+ */
+import type { CliConfig } from "@oh-my-pi/pi-utils/cli";
+import { APP_NAME, MIN_BUN_VERSION, VERSION } from "@oh-my-pi/pi-utils/dirs";
+import { declareWorkerHostEntry } from "@oh-my-pi/pi-utils/env";
+
+if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
+	process.stderr.write(
+		`error: Bun runtime must be >= ${MIN_BUN_VERSION} (found v${Bun.version}). Please upgrade: bun upgrade\n`,
+	);
+	process.exit(1);
+}
+
+process.title = APP_NAME;
+
+// Declare this module as the worker-host entry: Worker threads and worker
+// subprocesses re-enter `Bun.main` with a hidden argv selector instead of
+// loading separate worker entrypoints (single-entry contract across source,
+// npm bundle, and compiled binary).
+declareWorkerHostEntry();
+
+async function showHelp(config: CliConfig): Promise<void> {
+	const { renderRootHelp } = await import("@oh-my-pi/pi-utils/cli");
+	const { getExtraHelpText } = await import("./cli/args");
+	renderRootHelp(config);
+	const extra = getExtraHelpText();
+	if (extra.trim().length > 0) {
+		process.stdout.write(`\n${extra}\n`);
+	}
+}
+/**
+ * Smoke-test entry. Spawns bundled workers, serves the stats dashboard once,
+ * pings everything, then exits.
+ *
+ * Purpose: catch the silent worker-load and bundled-asset regressions that hit
+ * compiled binaries and the npm CLI bundle. Version/help paths do not spawn
+ * worker modules or serve dashboard assets on a fresh install, so this probe is
+ * the minimal end-to-end test that proves those distribution-only paths work.
+ * Wired into `scripts/install-tests/run-ci.sh` so binary / source-link /
+ * tarball installs all exercise it on every CI run.
+ */
+async function runSmokeTest(): Promise<void> {
+	const { smokeTestSyncWorker, startServer } = await import("@oh-my-pi/omp-stats");
+	const { smokeTestTinyTitleWorker } = await import("./tiny/title-client");
+	await smokeTestSyncWorker();
+
+	const statsServer = await startServer(0);
+	try {
+		const response = await fetch(`http://127.0.0.1:${statsServer.port}/`);
+		if (!response.ok) throw new Error(`stats dashboard smoke failed: HTTP ${response.status}`);
+		const html = await response.text();
+		if (!html.includes('<div id="root"></div>') || !html.includes("index.js")) {
+			throw new Error("stats dashboard smoke failed: dashboard HTML was not served");
+		}
+	} finally {
+		statsServer.stop();
+	}
+
+	await smokeTestTinyTitleWorker();
+	process.stdout.write("smoke-test: ok\n");
+}
+
+const TINY_WORKER_ARGS = new Set(["--tiny-worker", "__tiny_worker"]);
+const STATS_SYNC_WORKER_ARG = "__omp_stats_sync_worker";
+const TAB_WORKER_ARG = "__omp_tab_worker";
+const JS_EVAL_WORKER_ARG = "__omp_js_eval_worker";
+
+async function runWorkerEntrypoint(arg: string | undefined): Promise<boolean> {
+	if (arg === STATS_SYNC_WORKER_ARG) {
+		// The sync worker handles messages via `self.onmessage`, assigned during
+		// this *async* dynamic import. Bun flushes the worker's initial message
+		// buffer when the entry module's top-level evaluation finishes — before
+		// this dispatch completes — so anything the parent posted right after
+		// spawning (the smoke ping, the first parse request) would be dropped.
+		// Park early events and replay them once the module's handler is live.
+		// (The tab/eval workers are immune: `parentPort.on("message")` queues
+		// until a listener attaches.)
+		const scope = globalThis as unknown as { onmessage: ((event: MessageEvent) => void) | null };
+		const pending: MessageEvent[] = [];
+		const buffer = (event: MessageEvent): void => {
+			pending.push(event);
+		};
+		scope.onmessage = buffer;
+		await import("@oh-my-pi/omp-stats/sync-worker");
+		const handler = scope.onmessage;
+		if (handler && handler !== buffer) {
+			for (const event of pending) handler.call(scope, event);
+		}
+		return true;
+	}
+	if (arg === TAB_WORKER_ARG) {
+		await import("./tools/browser/tab-worker-entry");
+		return true;
+	}
+	if (arg === JS_EVAL_WORKER_ARG) {
+		await import("./eval/js/worker-entry");
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Hidden subcommand that boots the tiny-model worker inside this process
+ * over the parent's IPC channel. The agent's main process spawns the same
+ * binary with this flag so `onnxruntime-node` (loaded transitively by
+ * `@huggingface/transformers`) lives in a child address space. The parent
+ * `SIGKILL`s the child on shutdown so the NAPI finalizer never runs in
+ * either process — that finalizer segfaults Bun on Windows (issue #1606).
+ */
+async function runTinyWorker(): Promise<void> {
+	const { startTinyTitleWorker } = await import("./tiny/worker");
+	const { promise: shuttingDown, resolve: shutdown } = Promise.withResolvers<void>();
+	const send = (message: unknown): void => {
+		// `process.send` only exists when spawned with an IPC channel; the
+		// parent always spawns us that way. If it's missing, the parent
+		// vanished and there's no one to talk to.
+		const sender = (process as NodeJS.Process & { send?: (m: unknown) => boolean }).send;
+		if (!sender) {
+			shutdown();
+			return;
+		}
+		try {
+			sender.call(process, message);
+		} catch {
+			shutdown();
+		}
+	};
+	startTinyTitleWorker({
+		send,
+		onMessage(handler) {
+			const wrap = (data: unknown): void => handler(data as never);
+			process.on("message", wrap);
+			return () => {
+				process.off("message", wrap);
+			};
+		},
+	});
+	const keepalive = setInterval(() => {}, 2 ** 30);
+	// Parent went away (crashed, SIGKILL, etc.) — commit suicide so we don't
+	// linger as an orphan. SIGKILL via `process.kill` keeps us symmetrical
+	// with the parent's hard-kill on shutdown: skip every JS/native finalizer.
+	process.on("disconnect", () => shutdown());
+	try {
+		await shuttingDown;
+	} finally {
+		clearInterval(keepalive);
+	}
+	process.kill(process.pid, "SIGKILL");
+}
+
+/** Run the CLI with the given argv (no `process.argv` prefix). */
+export async function runCli(argv: string[]): Promise<void> {
+	if (argv[0] === "--smoke-test") {
+		await runSmokeTest();
+		return;
+	}
+	if (TINY_WORKER_ARGS.has(argv[0] ?? "")) {
+		await runTinyWorker();
+		return;
+	}
+	if (await runWorkerEntrypoint(argv[0])) {
+		return;
+	}
+	const [{ run }, { commands, resolveCliArgv }] = await Promise.all([
+		import("@oh-my-pi/pi-utils/cli"),
+		import("./cli-commands"),
+	]);
+	// --help and --version are handled by run() directly, don't rewrite those.
+	// Everything else that isn't a known subcommand routes to "launch".
+	const resolved = resolveCliArgv(argv);
+	if ("error" in resolved) {
+		process.stderr.write(`error: ${resolved.error}\n`);
+		process.exitCode = 1;
+		return;
+	}
+	return run({ bin: APP_NAME, version: VERSION, argv: resolved.argv, commands, help: showHelp });
+}
+
+// Floating call instead of top-level await: TLA forces `--bytecode` (CJS
+// lowering) builds to fail, and the entrypoint needs nothing after this.
+// The catch mirrors what an unhandled TLA rejection produced: error dump to
+// stderr, exit code 1. Success paths resolve without touching the exit code.
+runCli(process.argv.slice(2)).catch((err: unknown) => {
+	process.stderr.write(`${Bun.inspect(err, { colors: process.stderr.isTTY === true })}\n`);
+	process.exit(1);
+});

package/src/commands/acp.ts

@@ -0,0 +1,24 @@
+/**
+ * Run Oh My Pi as an ACP (Agent Client Protocol) server over stdio.
+ *
+ * Thin wrapper around the launch flow that forces `mode: "acp"` unless the
+ * ACP terminal-auth flag asks the same command to open the interactive TUI.
+ */
+import { Command } from "@oh-my-pi/pi-utils/cli";
+import { parseArgs } from "../cli/args";
+import { runRootCommand } from "../main";
+import { prepareAcpTerminalAuthArgs } from "../modes/acp/terminal-auth";
+
+export default class Acp extends Command {
+	static description = "Run Oh My Pi as an ACP (Agent Client Protocol) server over stdio";
+	static strict = false;
+
+	async run(): Promise<void> {
+		const { args, terminalAuth } = prepareAcpTerminalAuthArgs(this.argv);
+		const parsed = parseArgs(args);
+		if (!terminalAuth) {
+			parsed.mode = "acp";
+		}
+		await runRootCommand(parsed, args);
+	}
+}

package/src/commands/agents.ts

@@ -0,0 +1,57 @@
+/**
+ * Manage bundled task agents.
+ */
+import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
+import { type AgentsAction, type AgentsCommandArgs, runAgentsCommand } from "../cli/agents-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: AgentsAction[] = ["unpack"];
+
+export default class Agents extends Command {
+	static description = "Manage bundled task agents";
+
+	static args = {
+		action: Args.string({
+			description: "Agents action",
+			required: false,
+			options: ACTIONS,
+		}),
+	};
+
+	static flags = {
+		force: Flags.boolean({ char: "f", description: "Overwrite existing agent files" }),
+		json: Flags.boolean({ description: "Output JSON" }),
+		dir: Flags.string({ description: "Output directory (overrides --user/--project)" }),
+		user: Flags.boolean({ description: "Write to ~/.omp/agent/agents (default)" }),
+		project: Flags.boolean({ description: "Write to ./.omp/agents" }),
+	};
+
+	static examples = [
+		"# Export bundled agents into user config (default)\n  omp agents unpack",
+		"# Export bundled agents into project config\n  omp agents unpack --project",
+		"# Overwrite existing local agent files\n  omp agents unpack --project --force",
+		"# Export into a custom directory\n  omp agents unpack --dir ./tmp/agents --json",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Agents);
+		if (!args.action) {
+			renderCommandHelp("omp", "agents", Agents);
+			return;
+		}
+
+		const cmd: AgentsCommandArgs = {
+			action: args.action as AgentsAction,
+			flags: {
+				force: flags.force,
+				json: flags.json,
+				dir: flags.dir,
+				user: flags.user,
+				project: flags.project,
+			},
+		};
+
+		await initTheme();
+		await runAgentsCommand(cmd);
+	}
+}

package/src/commands/auth-broker.ts

@@ -0,0 +1,99 @@
+/**
+ * `omp auth-broker` — manage the omp credential vault.
+ */
+import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
+import {
+	AUTH_BROKER_ACTIONS,
+	type AuthBrokerAction,
+	type AuthBrokerCommandArgs,
+	runAuthBrokerCommand,
+} from "../cli/auth-broker-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class AuthBroker extends Command {
+	static description = "Manage the omp auth-broker (credential vault)";
+
+	static args = {
+		action: Args.string({
+			description: "Sub-command",
+			required: false,
+			options: [...AUTH_BROKER_ACTIONS],
+		}),
+		// Second positional: provider id (login/logout) or filesystem path (import).
+		source: Args.string({
+			description: "OAuth provider id (login/logout) or path (import)",
+			required: false,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+		bind: Flags.string({ description: "Bind address for `serve` (host:port)", char: "b" }),
+		regenerate: Flags.boolean({ description: "Regenerate the bearer token" }),
+		via: Flags.string({
+			description: "SSH user@host for remote login (login --via=user@host)",
+		}),
+		provider: Flags.string({
+			description: "Override provider id for `import` (e.g. when JSON `type` is unrecognized)",
+		}),
+		"include-disabled": Flags.boolean({
+			description: "Import credentials whose JSON has `disabled: true` (import)",
+		}),
+		"from-local": Flags.boolean({
+			description: "migrate source: local SQLite + env vars (required for `migrate`)",
+		}),
+		"include-env": Flags.boolean({
+			description: "Capture env-var API keys for providers not yet on broker (migrate)",
+		}),
+		"include-oauth": Flags.boolean({
+			description: "Also upload OAuth from local SQLite during migrate (default skips them)",
+		}),
+		"dry-run": Flags.boolean({ description: "Print actions without executing (import / login --via / migrate)" }),
+	};
+
+	static examples = [
+		"# Boot the broker against the local SQLite store\n  omp auth-broker serve",
+		"# Boot on a non-default port\n  omp auth-broker serve --bind=127.0.0.1:9000",
+		"# Print the bearer token\n  omp auth-broker token",
+		"# Rotate the bearer token\n  omp auth-broker token --regenerate",
+		"# List supported OAuth providers\n  omp auth-broker list",
+		"# Local login (run on the broker host)\n  omp auth-broker login anthropic",
+		"# Interactive provider selection\n  omp auth-broker login",
+		"# Remote login over SSH tunnel\n  omp auth-broker login anthropic --via=user@broker",
+		"# Log out of a provider (interactive without provider arg)\n  omp auth-broker logout anthropic",
+		"# Import a CLIProxyAPI auth dump\n  omp auth-broker import ~/.cliproxy/auth",
+		"# Import a single CLIProxyAPI JSON, overriding the provider mapping\n  omp auth-broker import ~/.cliproxy/auth/claude-foo.json --provider anthropic",
+		"# Preview a migration from local store + env vars to the configured broker\n  omp auth-broker migrate --from-local --include-env --dry-run",
+		"# Apply the migration\n  omp auth-broker migrate --from-local --include-env",
+		"# Health-check the configured remote broker\n  omp auth-broker status",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(AuthBroker);
+		if (!args.action) {
+			renderCommandHelp("omp", "auth-broker", AuthBroker);
+			return;
+		}
+		const action = args.action as AuthBrokerAction;
+		const cmd: AuthBrokerCommandArgs = {
+			action,
+			flags: {
+				json: flags.json,
+				bind: flags.bind,
+				regenerate: flags.regenerate,
+				via: flags.via,
+				// `login`/`logout` reuse the legacy `provider` slot; `import` keeps `source` separate
+				// so `provider` flag (used as an override) is unambiguous.
+				provider: action === "import" ? flags.provider : (args.source ?? flags.provider),
+				source: args.source,
+				includeDisabled: flags["include-disabled"],
+				fromLocal: flags["from-local"],
+				includeEnv: flags["include-env"],
+				includeOauth: flags["include-oauth"],
+				dryRun: flags["dry-run"],
+			},
+		};
+		await initTheme();
+		await runAuthBrokerCommand(cmd);
+	}
+}

package/src/commands/auth-gateway.ts

@@ -0,0 +1,69 @@
+/**
+ * `omp auth-gateway` — run a forward proxy that injects auth from the broker.
+ */
+import { Args, Command, Flags, renderCommandHelp } from "@oh-my-pi/pi-utils/cli";
+import {
+	AUTH_GATEWAY_ACTIONS,
+	type AuthGatewayAction,
+	type AuthGatewayCommandArgs,
+	runAuthGatewayCommand,
+} from "../cli/auth-gateway-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class AuthGateway extends Command {
+	static description = "Run an auth-gateway forward proxy backed by the configured broker";
+
+	static args = {
+		action: Args.string({
+			description: "Sub-command",
+			required: false,
+			options: [...AUTH_GATEWAY_ACTIONS],
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON (token/status/check)" }),
+		bind: Flags.string({ description: "Bind address for `serve` (host:port)", char: "b" }),
+		regenerate: Flags.boolean({ description: "Regenerate the gateway bearer token (token)" }),
+		"no-auth": Flags.boolean({
+			description:
+				"Disable inbound bearer-token auth (serve). Useful when bound to loopback — any caller is allowed.",
+		}),
+		strict: Flags.boolean({
+			description:
+				"For `check`: additionally probe each credential against its provider's chat-completion endpoint. Slower; consumes a tiny amount of quota per credential.",
+		}),
+	};
+
+	static examples = [
+		"# Boot the gateway against the configured broker\n  omp auth-gateway serve",
+		"# Boot on a non-default port\n  omp auth-gateway serve --bind=127.0.0.1:4000",
+		"# Print the gateway bearer token (creates one on first run)\n  omp auth-gateway token",
+		"# Rotate the gateway bearer token\n  omp auth-gateway token --regenerate",
+		"# Run on loopback without any bearer (anyone on this host can call)\n  omp auth-gateway serve --no-auth",
+		"# Show local gateway + broker config status\n  omp auth-gateway status",
+		"# Probe each broker credential to see which one is producing 401s\n  omp auth-gateway check",
+		"# Same, machine-readable for scripts\n  omp auth-gateway check --json",
+		"# Strict check — also exercises each credential with a real chat-completion ping\n  omp auth-gateway check --strict",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(AuthGateway);
+		if (!args.action) {
+			renderCommandHelp("omp", "auth-gateway", AuthGateway);
+			return;
+		}
+		const cmd: AuthGatewayCommandArgs = {
+			action: args.action as AuthGatewayAction,
+			flags: {
+				json: flags.json,
+				bind: flags.bind,
+				regenerate: flags.regenerate,
+				noAuth: flags["no-auth"],
+				strict: flags.strict,
+			},
+		};
+		await initTheme();
+		await runAuthGatewayCommand(cmd);
+	}
+}

package/src/commands/commit.ts

@@ -0,0 +1,46 @@
+/**
+ * Generate and optionally push a commit with changelog updates.
+ */
+import { postmortem } from "@oh-my-pi/pi-utils";
+import { Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { runCommitCommand } from "../commit";
+import type { CommitCommandArgs } from "../commit/types";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Commit extends Command {
+	static description = "Generate a commit message and update changelogs";
+
+	static flags = {
+		push: Flags.boolean({ description: "Push after committing" }),
+		"dry-run": Flags.boolean({ description: "Preview without committing" }),
+		"no-changelog": Flags.boolean({ description: "Skip changelog updates" }),
+		legacy: Flags.boolean({ description: "Use legacy deterministic pipeline" }),
+		context: Flags.string({ char: "c", description: "Additional context for the model" }),
+		model: Flags.string({ char: "m", description: "Override model selection" }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Commit);
+
+		const cmd: CommitCommandArgs = {
+			push: flags.push ?? false,
+			dryRun: flags["dry-run"] ?? false,
+			noChangelog: flags["no-changelog"] ?? false,
+			legacy: flags.legacy,
+			context: flags.context,
+			model: flags.model,
+		};
+
+		await initTheme();
+		// The agentic commit flow opens keep-alive sockets to the model provider
+		// and spins up an AgentSession with background async-job + extension
+		// machinery. `session.dispose()` releases what it can, but Bun's fetch
+		// keeps idle connections warm and a few timers (Settings autosave, OAuth
+		// refresh) stay armed long enough to pin the event loop after the commit
+		// is already written. Mirror the `runPrintMode` exit pattern from
+		// `main.ts` so the CLI returns to the shell instead of stranding the user
+		// on Ctrl+C (issue #1041).
+		await runCommitCommand(cmd);
+		await postmortem.quit(0);
+	}
+}

package/src/commands/complete.ts

@@ -0,0 +1,66 @@
+/**
+ * `omp __complete <kind> [-- <prefix>]` — dynamic completion candidates.
+ *
+ * Hidden helper invoked by the generated shell completion scripts to resolve
+ * values that can't be baked into the script: the live model catalog and
+ * on-disk sessions. Output is one `value\tdescription` line per candidate
+ * (tab-separated); shells that show descriptions parse the tab, bash uses the
+ * first field. The import surface is kept deliberately narrow so a TAB press
+ * doesn't pay for the full agent boot.
+ */
+import { type GeneratedProvider, getBundledModels, getBundledProviders } from "@oh-my-pi/pi-catalog/models";
+import { Command } from "@oh-my-pi/pi-utils/cli";
+import { SessionManager } from "../session/session-manager";
+
+export default class Complete extends Command {
+	static hidden = true;
+	static strict = false;
+
+	async run(): Promise<void> {
+		const argv = this.argv.filter(token => token !== "--");
+		const kind = argv[0];
+		const prefix = argv.length > 1 ? argv[argv.length - 1] : "";
+		if (kind === "models") {
+			completeModels(prefix);
+		} else if (kind === "sessions") {
+			await completeSessions(prefix);
+		}
+	}
+}
+
+/** Strip control chars that would corrupt the tab-separated line protocol. */
+function clean(text: string): string {
+	return text.replace(/[\t\r\n]+/g, " ").trim();
+}
+
+function completeModels(prefix: string): void {
+	const needle = prefix.toLowerCase();
+	const seen = new Set<string>();
+	const lines: string[] = [];
+	for (const provider of getBundledProviders()) {
+		for (const model of getBundledModels(provider as GeneratedProvider)) {
+			// Offer both the fully-qualified `provider/id` and the bare `id`
+			// (matches the fuzzy resolution `--model` accepts).
+			const candidates = [`${model.provider}/${model.id}`, model.id];
+			for (const candidate of candidates) {
+				if (seen.has(candidate)) continue;
+				seen.add(candidate);
+				if (needle && !candidate.toLowerCase().includes(needle)) continue;
+				lines.push(`${candidate}\t${model.provider}`);
+			}
+		}
+	}
+	lines.sort();
+	if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+async function completeSessions(prefix: string): Promise<void> {
+	const sessions = await SessionManager.list(process.cwd());
+	const lines: string[] = [];
+	for (const session of sessions) {
+		if (prefix && !session.id.startsWith(prefix)) continue;
+		const label = clean(session.title ?? session.firstMessage ?? "").slice(0, 72);
+		lines.push(`${session.id}\t${label}`);
+	}
+	if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+}

package/src/commands/completions.ts

@@ -0,0 +1,60 @@
+/**
+ * `omp completions <bash|zsh|fish>` — print a shell completion script.
+ *
+ * The script is derived entirely from the declarative command/flag metadata
+ * (see `cli/completion-gen.ts`), so it never drifts from the actual CLI surface.
+ */
+import { APP_NAME, VERSION } from "@oh-my-pi/pi-utils";
+import { Args, type CliConfig, Command, type CommandCtor } from "@oh-my-pi/pi-utils/cli";
+import { buildSpec, generateCompletion, type Shell } from "../cli/completion-gen";
+import { commands } from "../cli-commands";
+
+/** Entry name of the default command whose flags become top-level completions. */
+const ROOT_COMMAND = "launch";
+const SHELLS = ["bash", "zsh", "fish"] as const;
+
+export default class Completions extends Command {
+	static description = "Print a shell completion script (bash, zsh, or fish)";
+
+	static args = {
+		shell: Args.string({
+			description: "Target shell",
+			required: true,
+			options: SHELLS,
+		}),
+	};
+
+	static examples = [
+		`# zsh — eval at startup, or write to a file in $fpath\n  eval "$(${APP_NAME} completions zsh)"`,
+		`# bash\n  eval "$(${APP_NAME} completions bash)"`,
+		`# fish\n  ${APP_NAME} completions fish > ~/.config/fish/completions/${APP_NAME}.fish`,
+	];
+
+	async run(): Promise<void> {
+		const shell = this.argv[0];
+		if (!isShell(shell)) {
+			process.stderr.write(`Usage: ${APP_NAME} completions <${SHELLS.join("|")}>\n`);
+			process.exitCode = 1;
+			return;
+		}
+
+		// Load every command class so we can read its static flag/arg descriptors,
+		// and collect aliases from both the registration table and the class.
+		const loaded = await Promise.all(commands.map(async entry => ({ entry, Cmd: await entry.load() })));
+		const map = new Map<string, CommandCtor>();
+		const aliasMap = new Map<string, readonly string[]>();
+		for (const { entry, Cmd } of loaded) {
+			map.set(entry.name, Cmd);
+			const merged = new Set<string>([...(Cmd.aliases ?? []), ...(entry.aliases ?? [])]);
+			aliasMap.set(entry.name, [...merged]);
+		}
+
+		const config: CliConfig = { bin: APP_NAME, version: VERSION, commands: map };
+		const spec = buildSpec(config, ROOT_COMMAND, aliasMap);
+		await Bun.write(Bun.stdout, generateCompletion(shell, spec));
+	}
+}
+
+function isShell(value: string | undefined): value is Shell {
+	return value === "bash" || value === "zsh" || value === "fish";
+}

package/src/commands/config.ts

@@ -0,0 +1,51 @@
+/**
+ * Manage configuration settings.
+ */
+import { Args, Command, Flags } from "@oh-my-pi/pi-utils/cli";
+import { type ConfigAction, type ConfigCommandArgs, runConfigCommand } from "../cli/config-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: ConfigAction[] = ["list", "get", "set", "reset", "path", "init-xdg"];
+
+export default class Config extends Command {
+	static description = "Manage configuration settings";
+
+	static args = {
+		action: Args.string({
+			description: "Config action",
+			required: false,
+			options: ACTIONS,
+		}),
+		key: Args.string({
+			description: "Setting key",
+			required: false,
+		}),
+		value: Args.string({
+			description: "Value (for set/reset)",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Config);
+		const action = (args.action ?? "list") as ConfigAction;
+		const value = Array.isArray(args.value) ? args.value.join(" ") : args.value;
+
+		const cmd: ConfigCommandArgs = {
+			action,
+			key: args.key,
+			value,
+			flags: {
+				json: flags.json,
+			},
+		};
+
+		await initTheme();
+		await runConfigCommand(cmd);
+	}
+}