@sayknow-cli/coding-agent 0.3.7 → 0.3.8

package/src/cli/fixture-report.ts

@@ -0,0 +1,171 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { SkcSessionContext } from "../skc-runtime/session-layout";
+import { resolveSkcSessionForRead, SessionResolutionError } from "../skc-runtime/session-resolution";
+import { computeTaskTokenMetrics, readTaskTokenLogs } from "../task/token-log";
+import type { TaskTokenLog } from "../task/types";
+
+const LIVE_RUNNER_SCHEMA_VERSION = 1;
+const BINARY_ID = "skc";
+
+function deterministicLog(
+	input: number,
+	output: number,
+	cacheRead: number,
+	cacheWrite: number,
+	totalTokens: number,
+): TaskTokenLog {
+	return {
+		subagentId: "root",
+		agent: "main",
+		turn: 1,
+		at: "2026-01-01T00:00:00.000Z",
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		totalTokens,
+		model: "fixture-model",
+	};
+}
+
+export interface LiveRunReportShape {
+	schemaVersion: 1;
+	binaryId: string;
+	fixtureId: string;
+	totals: {
+		turns: number;
+		inputTokens: number;
+		outputTokens: number;
+		cacheReadTokens: number;
+		cacheWriteTokens: number;
+		totalTokens: number;
+	};
+	cacheHitRate: number | null;
+	receiptArtifactRatio: number | null;
+	spawnDecisions: number | null;
+	roi: number | null;
+}
+
+const DETERMINISTIC_FIXTURES: Record<string, readonly TaskTokenLog[]> = {
+	"fixed-fixture": [
+		{
+			subagentId: "root",
+			agent: "main",
+			turn: 1,
+			at: "2026-01-01T00:00:00.000Z",
+			input: 100,
+			output: 20,
+			cacheRead: 40,
+			cacheWrite: 10,
+			totalTokens: 170,
+			model: "fixture-model",
+		},
+		{
+			subagentId: "1-executor",
+			agent: "executor",
+			turn: 1,
+			at: "2026-01-01T00:00:01.000Z",
+			input: 60,
+			output: 15,
+			cacheRead: 20,
+			cacheWrite: 5,
+			totalTokens: 100,
+			model: "fixture-model",
+		},
+	],
+};
+const DEFAULT_REDUCTION_FIXTURE_LOGS: Record<string, readonly TaskTokenLog[]> = {
+	"pr9.task-recursion.before": [deterministicLog(2400, 420, 600, 200, 3620)],
+	"pr9.task-recursion.after": [deterministicLog(1800, 360, 450, 150, 2760)],
+	"pr9.output-caps.before": [deterministicLog(22_000, 3_200, 0, 0, 25_200)],
+	"pr9.output-caps.after": [deterministicLog(18_000, 2_400, 0, 0, 20_400)],
+	"pr9.max-inline-result-bytes.before": [deterministicLog(48_000, 2_000, 0, 0, 50_000)],
+	"pr9.max-inline-result-bytes.after": [deterministicLog(12_000, 1_600, 0, 0, 13_600)],
+	"pr9.read-artifact-spill-threshold.before": [deterministicLog(96_000, 2_500, 0, 0, 98_500)],
+	"pr9.read-artifact-spill-threshold.after": [deterministicLog(18_000, 2_100, 0, 0, 20_100)],
+	"pr9.maintenance-pruning.before": [deterministicLog(40_000, 2_000, 18_000, 6_000, 66_000)],
+	"pr9.maintenance-pruning.after": [deterministicLog(30_000, 1_800, 10_000, 3_000, 44_800)],
+	"pr9.append-only-provider-expansion.before": [deterministicLog(28_000, 1_700, 8_000, 2_500, 40_200)],
+	"pr9.append-only-provider-expansion.after": [deterministicLog(20_000, 1_700, 14_000, 2_500, 38_200)],
+	"pr9.rpc-compact-deltas.before": [deterministicLog(14_000, 1_200, 6_000, 1_500, 22_700)],
+	"pr9.rpc-compact-deltas.after": [deterministicLog(10_000, 900, 6_200, 1_500, 18_600)],
+};
+
+export function buildFixtureReport(fixtureId: string, logs: readonly TaskTokenLog[]): LiveRunReportShape {
+	const metrics = computeTaskTokenMetrics(logs);
+	return {
+		schemaVersion: LIVE_RUNNER_SCHEMA_VERSION,
+		binaryId: BINARY_ID,
+		fixtureId,
+		totals: {
+			turns: metrics.turns,
+			inputTokens: metrics.inputTokens,
+			outputTokens: metrics.outputTokens,
+			cacheReadTokens: metrics.cacheReadTokens,
+			cacheWriteTokens: metrics.cacheWriteTokens,
+			totalTokens: metrics.totalTokens,
+		},
+		cacheHitRate: logs.length === 0 ? null : metrics.cacheHitRate,
+		receiptArtifactRatio: null,
+		spawnDecisions: null,
+		roi: null,
+	};
+}
+
+export async function runFixtureReport(fixtureId: string): Promise<number> {
+	let resolved: ResolvedFixtureLogs;
+	try {
+		resolved = await resolveFixtureLogs(fixtureId);
+	} catch (error) {
+		// e.g. a corrupt token-log. Fail loudly rather than emitting an all-zero report.
+		process.stderr.write(
+			`failed to build fixture report for ${fixtureId}: ${error instanceof Error ? error.message : String(error)}\n`,
+		);
+		return 1;
+	}
+	if (resolved.kind === "unknown") {
+		// Neither a known deterministic fixture nor a resolvable SKC session. Emit a
+		// bounded error on stderr with a non-zero exit rather than a schema-valid
+		// all-zero report, which a before/after benchmark would misread as "0 tokens".
+		process.stderr.write(`unknown fixture id and no matching SKC session: ${fixtureId}\n`);
+		return 1;
+	}
+	process.stdout.write(JSON.stringify(buildFixtureReport(fixtureId, resolved.logs)));
+	return 0;
+}
+
+type ResolvedFixtureLogs =
+	| { readonly kind: "logs"; readonly logs: readonly TaskTokenLog[] }
+	| { readonly kind: "unknown" };
+
+async function resolveFixtureLogs(fixtureId: string): Promise<ResolvedFixtureLogs> {
+	const deterministic = DETERMINISTIC_FIXTURES[fixtureId] ?? DEFAULT_REDUCTION_FIXTURE_LOGS[fixtureId];
+	if (deterministic) return { kind: "logs", logs: deterministic };
+	let session: SkcSessionContext;
+	try {
+		session = await resolveSkcSessionForRead(process.cwd(), {
+			flagValue: fixtureId,
+			envSessionId: process.env.SKC_SESSION_ID,
+		});
+	} catch (error) {
+		if (error instanceof SessionResolutionError) return { kind: "unknown" };
+		throw error;
+	}
+	// resolveSkcSessionForRead accepts any explicit flagValue as a session id
+	// without checking the dir exists, so a typo would otherwise yield a
+	// schema-valid all-zero report. Require the session root to exist; a real
+	// session with no turns yet still reads as a legitimate empty log set.
+	if (!(await directoryExists(session.sessionRoot))) return { kind: "unknown" };
+	const logs = await readTaskTokenLogs(path.join(session.sessionRoot, "token-logs"));
+	return { kind: "logs", logs };
+}
+
+async function directoryExists(dir: string): Promise<boolean> {
+	try {
+		const stat = await fs.stat(dir);
+		return stat.isDirectory();
+	} catch {
+		return false;
+	}
+}

package/src/cli/nofile-limit.ts

@@ -0,0 +1,48 @@
+import { execFileSync } from "node:child_process";
+
+export const RECOMMENDED_MACOS_NOFILE_LIMIT = 4096;
+
+export function parseNoFileLimit(text: string): number | undefined {
+	const trimmed = text.trim();
+	if (!trimmed || trimmed === "unlimited") return undefined;
+	const value = Number(trimmed);
+	return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+export function buildMacOSNoFileLimitWarning(currentLimit: number): string {
+	return [
+		`Warning: macOS file descriptor limit is low (ulimit -n = ${currentLimit}).`,
+		'SKC and project dev servers can hit EMFILE / "too many open files" while scanning or watching repositories.',
+		"For this terminal session, run:",
+		`  ulimit -n ${RECOMMENDED_MACOS_NOFILE_LIMIT}`,
+		"If your shell refuses that value, raise the per-user launchd limit and restart the terminal:",
+		`  sudo launchctl limit maxfiles ${RECOMMENDED_MACOS_NOFILE_LIMIT} 65536`,
+		"Avoid using huge values such as 2147483646 on macOS; they are commonly rejected or clamped.",
+		"Set SKC_SKIP_NOFILE_CHECK=1 to silence this preflight warning.",
+	].join("\n");
+}
+
+export interface WarnIfMacOSNoFileLimitTooLowDeps {
+	platform?: NodeJS.Platform;
+	env?: NodeJS.ProcessEnv;
+	execFileSync?: typeof execFileSync;
+	writeStderr?: (text: string) => void;
+}
+
+export function warnIfMacOSNoFileLimitTooLow(deps: WarnIfMacOSNoFileLimitTooLowDeps = {}): void {
+	const platform = deps.platform ?? process.platform;
+	if (platform !== "darwin") return;
+	const env = deps.env ?? process.env;
+	if (env.SKC_SKIP_NOFILE_CHECK === "1" || env.SKC_SKIP_NOFILE_CHECK === "true") return;
+
+	const run = deps.execFileSync ?? execFileSync;
+	let currentLimit: number | undefined;
+	try {
+		currentLimit = parseNoFileLimit(run("/bin/sh", ["-lc", "ulimit -n"], { encoding: "utf8" }));
+	} catch {
+		return;
+	}
+	if (currentLimit === undefined || currentLimit >= RECOMMENDED_MACOS_NOFILE_LIMIT) return;
+	const write = deps.writeStderr ?? (text => process.stderr.write(text));
+	write(`${buildMacOSNoFileLimitWarning(currentLimit)}\n`);
+}

package/src/cli/notify-cli.ts

@@ -4,7 +4,7 @@
  * Handles `skc notify` setup/status and the hidden daemon entrypoint.
  */
 import { createInterface } from "node:readline/promises";
-import { APP_NAME } from "@sayknow-cli/utils";
+import { APP_NAME } from "@sayknow-cli/utils/dirs";
 import chalk from "chalk";
 import type { Settings } from "../config/settings";
 import { getNotificationConfig, maskToken } from "../notifications/config";
@@ -58,6 +58,11 @@ interface TelegramUser {
 	allows_users_to_create_topics?: boolean;
 }
 
+interface TelegramChat {
+	id?: number | string;
+	type?: string;
+}
+
 type ThreadedModeState = "enabled" | "disabled" | "unknown";
 type ThreadedModeFinalLabel = "verified" | "unverified" | "unknown";
 
@@ -148,6 +153,7 @@ async function runSetup(deps: NotifyCommandDeps): Promise<void> {
 	let chatId: string;
 	if (deps.setupChatId?.trim()) {
 		chatId = deps.setupChatId.trim();
+		await verifyPrivateChatId(fetchImpl, apiBase, token, chatId);
 		process.stdout.write(`Using provided chat id ${chatId} (non-interactive).\n`);
 	} else {
 		const stale = await getUpdates(fetchImpl, apiBase, token, { timeout: 0, allowed_updates: ["message"] });
@@ -170,16 +176,76 @@ async function runSetup(deps: NotifyCommandDeps): Promise<void> {
 	);
 }
 
-async function promptForToken(): Promise<string> {
-	if (!process.stdin.isTTY) {
+type TokenPromptInput = NodeJS.ReadStream & {
+	isRaw?: boolean;
+	setRawMode?: (mode: boolean) => unknown;
+};
+
+type TokenPromptOutput = Pick<NodeJS.WriteStream, "write">;
+
+export async function promptForToken(
+	input: TokenPromptInput = process.stdin,
+	output: TokenPromptOutput = process.stdout,
+): Promise<string> {
+	if (!input.isTTY) {
 		throw new Error("notify setup requires an interactive TTY unless setupToken is injected.");
 	}
-	const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
-	try {
-		return (await rl.question("Telegram BotFather token: ")).trim();
-	} finally {
-		rl.close();
+	if (typeof input.setRawMode !== "function") {
+		throw new Error("notify setup requires a TTY with raw input support unless setupToken is injected.");
 	}
+
+	output.write("Telegram BotFather token: ");
+	const wasRaw = input.isRaw === true;
+	input.setRawMode(true);
+
+	return await new Promise<string>((resolve, reject) => {
+		let value = "";
+		let settled = false;
+
+		const cleanup = () => {
+			input.off("data", onData);
+			input.off("error", onError);
+			input.setRawMode?.(wasRaw);
+			output.write("\n");
+		};
+
+		const finish = (callback: () => void) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			callback();
+		};
+
+		const accept = () => finish(() => resolve(value.trim()));
+		const cancel = () => finish(() => reject(new Error("Telegram bot token prompt cancelled.")));
+		const onError = (error: Error) => finish(() => reject(error));
+		const onData = (chunk: Buffer | string) => {
+			for (const char of String(chunk)) {
+				if (char === "\r" || char === "\n") {
+					accept();
+					return;
+				}
+				if (char === "\u0003") {
+					cancel();
+					return;
+				}
+				if (char === "\u0004") {
+					if (value) accept();
+					else cancel();
+					return;
+				}
+				if (char === "\u007f" || char === "\b") {
+					value = value.slice(0, -1);
+					continue;
+				}
+				if (char >= " ") value += char;
+			}
+		};
+
+		input.on("data", onData);
+		input.once("error", onError);
+		input.resume();
+	});
 }
 
 const THREADED_ENABLED_SUCCESS =
@@ -223,6 +289,24 @@ async function getMe(fetchImpl: typeof fetch, apiBase: string, token: string): P
 	return user;
 }
 
+async function verifyPrivateChatId(
+	fetchImpl: typeof fetch,
+	apiBase: string,
+	token: string,
+	chatId: string,
+): Promise<void> {
+	const chat = (await callTelegram<unknown>(fetchImpl, apiBase, token, "getChat", { chat_id: chatId })) as
+		| TelegramChat
+		| undefined;
+	if (!chat || typeof chat !== "object") {
+		throw new Error("Telegram getChat returned invalid Telegram response: missing valid Chat result.");
+	}
+	if (chat.type !== "private") {
+		const type = typeof chat.type === "string" && chat.type ? chat.type : "unknown";
+		throw new Error(`Provided chat id ${chatId} is a ${type} chat; pairing requires a private Telegram chat.`);
+	}
+}
+
 function threadedModeState(user: TelegramUser): ThreadedModeState {
 	if (user.has_topics_enabled === true) return "enabled";
 	if (user.has_topics_enabled === false) return "disabled";

package/src/cli/telegram-cli.ts

@@ -4,10 +4,10 @@
  */
 
 import { logger } from "@sayknow-cli/utils";
-import { resolveSkcRuntimeSpawnInfo } from "../daemon/runtime";
 import { isSettingsInitialized, Settings, settings } from "../config/settings";
 import type { TelegramSettings } from "../config/settings-schema";
 import { telegramSettingsToEnv, validateTelegramSettings } from "../config/telegram-env-bridge";
+import { resolveSkcRuntimeSpawnInfo } from "../daemon/runtime";
 
 export type TelegramAction = "start" | "status" | "env" | "__gateway";
 

package/src/cli/update-cli.ts

@@ -552,31 +552,107 @@ async function updateViaNpm(packageName: string, expectedVersion: string): Promi
 }
 
 /**
- * Download a release binary to a target path, replacing an existing file.
+ * Flush a freshly written file's data to stable storage.
+ *
+ * Critical on network filesystems (e.g. NFS home directories): `pipeline`
+ * resolving does not guarantee the downloaded bytes are durable on the
+ * server, so the post-install `skc --version` check can exec a binary whose
+ * pages are not yet consistent. The child then faults, the version check
+ * fails, and the update is rolled back with "could not verify updated
+ * version" even though the download itself succeeded. Explicitly fsyncing
+ * before the rename/exec avoids the race.
  */
-async function updateViaBinaryAt(targetPath: string, expectedVersion: string): Promise<void> {
-	const binaryName = getBinaryName();
-	const url = buildReleaseBinaryUrl(expectedVersion);
+async function fsyncFile(filePath: string): Promise<void> {
+	const handle = await fs.promises.open(filePath, "r+");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
 
-	const tempPath = `${targetPath}.new`;
-	const backupPath = `${targetPath}.bak`;
-	console.log(chalk.dim(`Downloading ${binaryName}…`));
+export async function fsyncFileForTest(filePath: string): Promise<void> {
+	return fsyncFile(filePath);
+}
 
+/**
+ * Download a release binary to a temp path, throwing a friendly error when the
+ * release asset cannot be fetched.
+ */
+async function downloadBinaryTo(url: string, tempPath: string, binaryName: string): Promise<void> {
 	const response = await fetch(url, { redirect: "follow" });
 	if (!response.ok || !response.body) {
 		throw new Error(formatBinaryDownloadFailureMessage(binaryName, url, response.statusText || response.status));
 	}
 	const fileStream = fs.createWriteStream(tempPath, { mode: 0o755 });
 	await pipeline(response.body, fileStream);
+}
+
+/** Injectable steps of the binary update flow (seams for testing ordering). */
+export interface BinaryUpdateFlow {
+	download(url: string, tempPath: string): Promise<void>;
+	fsync(filePath: string): Promise<void>;
+	replace(options: BinaryReplacementOptions): Promise<InstalledVersionVerification>;
+	verifyInstalledVersion(expectedVersion: string): Promise<InstalledVersionVerification>;
+	/** Best-effort cleanup of the temp file when the flow aborts before replace. */
+	removeTemp?(filePath: string): Promise<void>;
+	/** Called once fsync has succeeded, right before replacement begins. */
+	beforeReplace?(): void;
+}
 
-	console.log(chalk.dim("Installing update..."));
-	const verification = await replaceBinaryForUpdate({
+/**
+ * Orchestrate download → fsync → replace → verify with a strict ordering
+ * contract: the downloaded temp binary MUST be flushed to stable storage
+ * before it is published (renamed into place) or exec'd for verification.
+ *
+ * If fsync fails the temp bytes are not durable, so we abort before
+ * replacement/verification and clean up the temp file rather than installing a
+ * possibly-truncated binary.
+ */
+export async function runBinaryUpdateFlow(
+	targetPath: string,
+	url: string,
+	expectedVersion: string,
+	flow: BinaryUpdateFlow,
+): Promise<InstalledVersionVerification> {
+	const tempPath = `${targetPath}.new`;
+	const backupPath = `${targetPath}.bak`;
+
+	await flow.download(url, tempPath);
+	try {
+		await flow.fsync(tempPath);
+	} catch (err) {
+		if (flow.removeTemp) await flow.removeTemp(tempPath);
+		throw err;
+	}
+
+	flow.beforeReplace?.();
+	return flow.replace({
 		targetPath,
 		tempPath,
 		backupPath,
 		expectedVersion,
+		verifyInstalledVersion: flow.verifyInstalledVersion,
+	});
+}
+
+/**
+ * Download a release binary to a target path, replacing an existing file.
+ */
+async function updateViaBinaryAt(targetPath: string, expectedVersion: string): Promise<void> {
+	const binaryName = getBinaryName();
+	const url = buildReleaseBinaryUrl(expectedVersion);
+	console.log(chalk.dim(`Downloading ${binaryName}…`));
+
+	const verification = await runBinaryUpdateFlow(targetPath, url, expectedVersion, {
+		download: (downloadUrl, tempPath) => downloadBinaryTo(downloadUrl, tempPath, binaryName),
+		fsync: fsyncFile,
+		replace: replaceBinaryForUpdate,
 		verifyInstalledVersion: verifyInstalledRuntime,
+		removeTemp: unlinkIfExists,
+		beforeReplace: () => console.log(chalk.dim("Installing update...")),
 	});
+
 	printVerifiedVersion(expectedVersion);
 	if (verification.cleanupWarning) console.warn(chalk.yellow(verification.cleanupWarning));
 	printRestartGuidance();

package/src/cli.ts

@@ -6,6 +6,7 @@
  */
 import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@sayknow-cli/utils/cli";
 import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@sayknow-cli/utils/dirs";
+import { runFixtureReport } from "./cli/fixture-report";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
@@ -35,6 +36,7 @@ export const commands: CommandEntry[] = [
 	{ name: "gc", load: () => import("./commands/gc").then(m => m.default) },
 	{ name: "ralplan", load: () => import("./commands/ralplan").then(m => m.default) },
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
+	{ name: "stats", load: () => import("./commands/stats").then(m => m.default) },
 	{ name: "notify", load: () => import("./commands/notify").then(m => m.default) },
 	{ name: "daemon", load: () => import("./commands/daemon").then(m => m.default) },
 	{ name: "web-search", aliases: ["q"], load: () => import("./commands/web-search").then(m => m.default) },
@@ -51,6 +53,7 @@ export const commands: CommandEntry[] = [
 	{ name: "rlm", load: () => import("./commands/rlm").then(m => m.default) },
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
+	{ name: "completion", load: () => import("./commands/completion").then(m => m.default) },
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
 	{ name: "telegram", load: () => import("./commands/telegram").then(m => m.default) },
 ];
@@ -74,6 +77,9 @@ async function installRuntimeGlobals(): Promise<void> {
 	// `HTTP2Unsupported`. See @sayknow-cli/ai/utils/h2-fetch for details.
 	installH2Fetch();
 
+	const { warnIfMacOSNoFileLimitTooLow } = await import("./cli/nofile-limit");
+	warnIfMacOSNoFileLimitTooLow();
+
 	// Strip macOS malloc-stack-logging env vars before any subprocess is spawned.
 	// Otherwise every child bun process (subagents, plugin installs, ptree spawns,
 	// etc.) prints a `MallocStackLogging: can't turn off …` warning to stderr.
@@ -94,6 +100,17 @@ async function runNotifyDaemonInternalFastPath(argv: string[]): Promise<void> {
 	await runNotifyCommand(cmd);
 }
 
+function rootFixtureArg(argv: string[]): { present: boolean; id: string | undefined } {
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		// Stop at the first subcommand token so a `--fixture` flag belonging to a
+		// subcommand never hijacks the root fast-path into fixture-report mode.
+		if (isSubcommand(arg)) return { present: false, id: undefined };
+		if (arg === "--fixture") return { present: true, id: argv[i + 1] };
+	}
+	return { present: false, id: undefined };
+}
+
 function hasRootFastFlag(argv: string[], flags: readonly string[]): boolean {
 	for (const arg of argv) {
 		if (isSubcommand(arg)) return false;
@@ -110,7 +127,7 @@ function hasRootVersionFlag(argv: string[]): boolean {
 	return hasRootFastFlag(argv, versionFlags);
 }
 
-class RootHelpCommand extends Command {
+export class RootHelpCommand extends Command {
 	static description = "Sayknow-CLI — an AI coding assistant";
 	static hidden = true;
 	static args = {
@@ -231,6 +248,17 @@ export async function runCli(argv: string[]): Promise<void> {
 		await runSmokeTest();
 		return;
 	}
+	const fixtureArg = rootFixtureArg(argv);
+	if (fixtureArg.present) {
+		const id = fixtureArg.id;
+		if (!id || id.startsWith("-")) {
+			process.stderr.write(`${APP_NAME} --fixture requires a fixture id\n`);
+			process.exitCode = 1;
+			return;
+		}
+		process.exitCode = await runFixtureReport(id);
+		return;
+	}
 	if (hasRootHelpFlag(argv)) {
 		const { renderRootHelp } = await import("@sayknow-cli/utils/cli");
 		const { getExtraHelpText } = await import("./cli/fast-help");

package/src/commands/completion.ts

@@ -0,0 +1,84 @@
+/**
+ * Generate shell completion specs for external completion engines.
+ */
+import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import { commands, RootHelpCommand } from "../cli";
+import {
+	buildSkcFigSpec,
+	defaultInshellisenseSpecDir,
+	type InstallSkcInshellisenseSpecResult,
+	installSkcInshellisenseSpec,
+	renderFigSpecModule,
+} from "../cli/completion-cli";
+
+const TARGETS = ["inshellisense", "fig"] as const;
+
+type CompletionTarget = (typeof TARGETS)[number];
+
+function normalizeTarget(target: CompletionTarget): "inshellisense" {
+	return target === "fig" ? "inshellisense" : target;
+}
+
+function formatInstallResult(result: InstallSkcInshellisenseSpecResult, customDir: boolean): string {
+	const lines = [
+		"Installed SKC inshellisense completion spec:",
+		`  spec:  ${result.specPath}`,
+		`  index: ${result.indexPath} (${result.indexStatus})`,
+	];
+	if (customDir) {
+		lines.push(
+			"Add the install directory to inshellisense's [specs].path setting, then restart the inshellisense session.",
+		);
+	} else {
+		lines.push("Restart the inshellisense session, or run `is reinit` if your shell integration needs a refresh.");
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+export default class Completion extends Command {
+	static description = "Generate shell completion specs";
+
+	static args = {
+		target: Args.string({
+			description: "Completion format",
+			required: false,
+			options: TARGETS,
+		}),
+	};
+
+	static flags = {
+		install: Flags.boolean({ description: "Install the generated spec for inshellisense" }),
+		dir: Flags.string({ description: "Install directory (defaults to ~/.fig/autocomplete/build)" }),
+		force: Flags.boolean({ description: "Overwrite an existing non-SKC inshellisense index.js" }),
+		json: Flags.boolean({ description: "Output JSON instead of JavaScript or status text" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Completion);
+		const target = normalizeTarget((args.target ?? "inshellisense") as CompletionTarget);
+		if (target !== "inshellisense") {
+			process.stderr.write(`Unsupported completion target: ${target}\n`);
+			process.exitCode = 1;
+			return;
+		}
+		if ((flags.dir || flags.force) && !flags.install) {
+			process.stderr.write("--dir and --force only apply with --install\n");
+			process.exitCode = 1;
+			return;
+		}
+
+		const spec = await buildSkcFigSpec(commands, RootHelpCommand);
+		if (!flags.install) {
+			process.stdout.write(flags.json ? `${JSON.stringify(spec, null, 2)}\n` : renderFigSpecModule(spec));
+			return;
+		}
+
+		const directory = flags.dir ?? defaultInshellisenseSpecDir();
+		const result = await installSkcInshellisenseSpec(spec, { dir: directory, force: flags.force });
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+			return;
+		}
+		process.stdout.write(formatInstallResult(result, flags.dir !== undefined));
+	}
+}

package/src/commands/config.ts

@@ -29,6 +29,7 @@ export default class Config extends Command {
 
 	static flags = {
 		json: Flags.boolean({ description: "Output JSON" }),
+		"show-secrets": Flags.boolean({ description: "Show secret-like setting values without redaction (unsafe)" }),
 	};
 
 	async run(): Promise<void> {
@@ -42,6 +43,7 @@ export default class Config extends Command {
 			value,
 			flags: {
 				json: flags.json,
+				showSecrets: flags["show-secrets"],
 			},
 		};
 

package/src/commands/contribution-prep.ts

@@ -1,5 +1,4 @@
 import { Command, Flags } from "@sayknow-cli/utils/cli";
-import { prepareContributionPrep } from "../session/contribution-prep";
 
 function writeText(lines: string[]): void {
 	process.stdout.write(`${lines.join("\n")}\n`);
@@ -19,6 +18,7 @@ export default class ContributionPrep extends Command {
 
 	async run(): Promise<void> {
 		const { flags } = await this.parse(ContributionPrep);
+		const { prepareContributionPrep } = await import("../session/contribution-prep");
 		const cwd = process.cwd();
 		const result = await prepareContributionPrep(
 			{