@kimchi-dev/kimchictl 0.0.2

package/src/commands/workspace.test.ts

@@ -0,0 +1,360 @@
+import { writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import {
+	captureConsole,
+	cleanupTempDirs,
+	jsonResponse,
+	makeTempDir,
+	stubAgentDirEnv,
+	stubFetch,
+} from "../test-support.js"
+import { guardCommand } from "./guard.js"
+import { runWorkspace, type WorkspaceDeps } from "./workspace.js"
+
+const guardedWorkspace = guardCommand(runWorkspace)
+
+afterEach(() => {
+	cleanupTempDirs()
+	vi.unstubAllEnvs()
+	vi.restoreAllMocks()
+})
+
+// ---------------------------------------------------------------- fixtures
+
+interface WorkspaceOverrides extends Record<string, unknown> {
+	id?: string
+	alias?: string
+}
+
+function wsJson(over: WorkspaceOverrides = {}): Record<string, unknown> {
+	const alias = over.alias ?? "bright-oak-otter"
+	return {
+		id: over.id ?? "11111111-2222-3333-4444-555555555555",
+		description: "api work",
+		status: "ACTIVE",
+		createTime: "2026-01-01T00:00:00Z",
+		uri: `${alias}.remote.kimchi.dev`,
+		spec: { resources: { cpu: "2", memory: "4Gi", pvcSize: "20Gi" } },
+		...over,
+	}
+}
+
+interface Route {
+	method: string
+	match: RegExp
+	respond: (call: number) => Response
+	/** Number of times this route must be hit at minimum (0 = optional). */
+	minCalls?: number
+}
+
+/**
+ * Fetch stub routing on method+path. verifyKey is always answered with the
+ * fixed org — the commands start every flow by resolving the org id.
+ */
+function apiFetch(routes: Route[]): typeof globalThis.fetch {
+	const counts = new Map<Route, number>()
+	return stubFetch(async (url, init) => {
+		const method = init?.method ?? "GET"
+		if (method === "POST" && url.endsWith("workspace-tokens:verifyKey")) {
+			return jsonResponse({ organizationId: "org-1" })
+		}
+		for (const route of routes) {
+			if (route.method === method && route.match.test(url)) {
+				counts.set(route, (counts.get(route) ?? 0) + 1)
+				return route.respond(counts.get(route) ?? 1)
+			}
+		}
+		throw new Error(`unexpected request: ${method} ${url}`)
+	})
+}
+
+async function run(
+	args: string[],
+	fetch: typeof globalThis.fetch,
+	deps: WorkspaceDeps = {},
+): Promise<{ code: number; lines: string[]; errors: string[] }> {
+	const dir = makeTempDir()
+	stubAgentDirEnv(dir)
+	writeFileSync(join(dir, "auth.json"), JSON.stringify({ "kimchi-dev": { type: "api_key", key: "key" } }))
+	const { lines, errors } = captureConsole()
+	const code = await guardedWorkspace(args, { fetch, ...deps })
+	return { code, lines, errors }
+}
+
+// ---------------------------------------------------------------- group dispatch
+
+describe("kimchictl workspace (group dispatch)", () => {
+	it("prints group usage on help / missing verb", async () => {
+		const { code, lines } = await run(["help"], apiFetch([]))
+		expect(code).toBe(0)
+		expect(lines[0]).toContain("kimchictl workspace <verb>")
+	})
+
+	it("rejects unknown verbs with exit 2", async () => {
+		const { code, errors } = await run(["frobnicate"], apiFetch([]))
+		expect(code).toBe(2)
+		expect(errors[0]).toBe('kimchictl workspace: unknown verb "frobnicate"')
+	})
+
+	it("mounts the hidden ws alias", async () => {
+		const dir = makeTempDir()
+		stubAgentDirEnv(dir)
+		writeFileSync(join(dir, "auth.json"), JSON.stringify({ "kimchi-dev": { type: "api_key", key: "key" } }))
+		captureConsole()
+		const code = await guardedWorkspace(["help"])
+
+		expect(code).toBe(0)
+	})
+})
+
+// ---------------------------------------------------------------- create
+
+describe("kimchictl workspace create", () => {
+	it("creates, waits for ACTIVE, and prints the alias on stdout", async () => {
+		const fetch = apiFetch([
+			{
+				method: "POST",
+				match: /\/organizations\/org-1\/workspaces$/,
+				respond: () => jsonResponse(wsJson({ status: "INITIALIZING" })),
+			},
+			{
+				method: "GET",
+				match: /\/workspaces\/11111111-2222-3333-4444-555555555555$/,
+				respond: (call) => jsonResponse(wsJson({ status: call >= 2 ? "ACTIVE" : "INITIALIZING" })),
+			},
+		])
+
+		const { code, lines, errors } = await run(["create", "--desc", "api work"], fetch, { sleep: async () => {} })
+
+		expect(code).toBe(0)
+		expect(lines).toEqual(["bright-oak-otter"])
+		expect(errors[0]).toBe("✓ created bright-oak-otter (initializing)")
+		expect(errors.some((l) => l.includes("uri  bright-oak-otter.remote.kimchi.dev"))).toBe(true)
+	})
+
+	it("--no-wait returns immediately after create", async () => {
+		const fetch = apiFetch([
+			{
+				method: "POST",
+				match: /\/organizations\/org-1\/workspaces$/,
+				respond: () => jsonResponse(wsJson({ status: "INITIALIZING" })),
+			},
+		])
+
+		const { code, lines } = await run(["create", "--no-wait"], fetch)
+
+		expect(code).toBe(0)
+		expect(lines).toEqual(["bright-oak-otter"])
+	})
+
+	it("warns when the workspace is not ACTIVE at the deadline", async () => {
+		const fetch = apiFetch([
+			{ method: "POST", match: /workspaces$/, respond: () => jsonResponse(wsJson({ status: "INITIALIZING" })) },
+			{
+				method: "GET",
+				match: /11111111-2222-3333-4444-555555555555$/,
+				respond: () => jsonResponse(wsJson({ status: "INITIALIZING" })),
+			},
+		])
+
+		// deadline 1s, sleep override advances nothing — the loop exits when Date.now() passes the deadline…
+		// …so use --timeout 1 with a real timer of 0 polls by making sleep a no-op that burns real time? No:
+		// sleep is mocked to resolve instantly, and Date.now() stays under the deadline — the loop would spin
+		// forever. Instead, advance the clock via the sleep mock.
+		let now = Date.now()
+		const realNow = Date.now
+		vi.spyOn(Date, "now").mockImplementation(() => now)
+
+		const { code, errors } = await run(["create", "--timeout", "1"], fetch, {
+			sleep: async () => {
+				now += 2000
+			},
+		})
+		vi.spyOn(Date, "now").mockImplementation(realNow)
+
+		expect(code).toBe(0)
+		expect(errors.some((l) => l.includes("still initializing"))).toBe(true)
+	})
+
+	it("--template errors gracefully until the templates API lands", async () => {
+		const { code, errors } = await run(["create", "--template", "node"], apiFetch([]))
+
+		expect(code).toBe(1)
+		expect(errors[0]).toContain('templates are not available yet (requested "node")')
+	})
+
+	it("rejects positional arguments and bad timeouts as usage errors", async () => {
+		for (const args of [
+			["create", "myname"],
+			["create", "--timeout", "abc"],
+			["create", "--timeout", "0"],
+		]) {
+			const { code } = await run(args, apiFetch([]))
+			expect(code).toBe(2)
+		}
+	})
+})
+
+// ---------------------------------------------------------------- list
+
+describe("kimchictl workspace list", () => {
+	it("renders the table", async () => {
+		const fetch = apiFetch([
+			{
+				method: "GET",
+				match: /\?page\.limit=/,
+				respond: () =>
+					jsonResponse({
+						items: [
+							wsJson(),
+							wsJson({
+								alias: "demo",
+								description: "",
+								status: "SUSPENDED",
+								createTime: "2025-12-30T00:00:00Z",
+								spec: undefined,
+							}),
+						],
+					}),
+			},
+		])
+
+		const { code, lines } = await run(["list"], fetch, { now: () => new Date("2026-01-01T03:00:00Z") })
+
+		expect(code).toBe(0)
+		// formatTable prints the whole table as one console call.
+		const table = lines[0]?.split("\n") ?? []
+		expect(table[0]).toBe("NAME              STATUS     CPU  MEMORY  AGE")
+		expect(table[1]).toMatch(/^bright-oak-otter\s+active\s+2\s+4Gi\s+3h$/)
+		expect(table[2]).toMatch(/^demo\s+suspended\s+-\s+-\s+2d$/)
+		expect(table).toHaveLength(3)
+	})
+
+	it("renders json output and the empty table", async () => {
+		const fetch = apiFetch([{ method: "GET", match: /\?page\.limit=/, respond: () => jsonResponse({ items: [] }) }])
+
+		const jsonRun = await run(["list", "--output", "json"], fetch)
+		expect(JSON.parse(jsonRun.lines.join(""))).toEqual([])
+
+		const tableRun = await run(["list"], fetch)
+		expect(tableRun.lines).toEqual(["NAME  STATUS  CPU  MEMORY  AGE"])
+	})
+
+	it("rejects an unsupported output flavor", async () => {
+		const { code } = await run(["list", "--output", "yaml"], apiFetch([]))
+		expect(code).toBe(2)
+	})
+})
+
+// ---------------------------------------------------------------- get
+
+describe("kimchictl workspace get", () => {
+	it("renders the detail view", async () => {
+		const fetch = apiFetch([
+			{ method: "GET", match: /\?page\.limit=/, respond: () => jsonResponse({ items: [wsJson()] }) },
+		])
+
+		const { code, lines } = await run(["get", "bright-oak-otter"], fetch)
+
+		expect(code).toBe(0)
+		expect(lines).toEqual([
+			"name:        bright-oak-otter",
+			"description: api work",
+			"status:      active",
+			"uri:         bright-oak-otter.remote.kimchi.dev",
+			"created:     2026-01-01T00:00:00.000Z",
+			"cpu:         2",
+			"memory:      4Gi",
+			"storage:     20Gi",
+		])
+	})
+
+	it("reports a missing workspace via the guard", async () => {
+		const fetch = apiFetch([
+			{ method: "GET", match: /\?page\.limit=/, respond: () => jsonResponse({ items: [wsJson()] }) },
+		])
+
+		const { code, errors } = await run(["get", "ghost"], fetch)
+
+		expect(code).toBe(1)
+		expect(errors[0]).toMatch(/No workspace matches "ghost"/)
+	})
+
+	it("resolves a UUID ref without listing", async () => {
+		const fetch = apiFetch([
+			{
+				method: "GET",
+				match: /\/workspaces\/11111111-2222-3333-4444-555555555555$/,
+				respond: () => jsonResponse(wsJson()),
+			},
+		])
+
+		const { code, lines } = await run(["get", "11111111-2222-3333-4444-555555555555"], fetch)
+
+		expect(code).toBe(0)
+		expect(lines[0]).toBe("name:        bright-oak-otter")
+	})
+
+	it("requires exactly one name", async () => {
+		expect((await run(["get"], apiFetch([]))).code).toBe(2)
+		expect((await run(["get", "a", "b"], apiFetch([]))).code).toBe(2)
+	})
+})
+
+// ---------------------------------------------------------------- delete
+
+describe("kimchictl workspace delete", () => {
+	it("deletes after an affirmative confirmation", async () => {
+		const fetch = apiFetch([
+			{ method: "GET", match: /\?page\.limit=/, respond: () => jsonResponse({ items: [wsJson()] }) },
+			{
+				method: "DELETE",
+				match: /\/workspaces\/11111111-2222-3333-4444-555555555555$/,
+				respond: () => new Response(null, { status: 200 }),
+			},
+		])
+
+		const { code, lines } = await run(["delete", "bright-oak-otter"], fetch, { confirm: async () => true })
+
+		expect(code).toBe(0)
+		expect(lines).toEqual(["✓ deleted bright-oak-otter"])
+	})
+
+	it("--force deletes without prompting", async () => {
+		const fetch = apiFetch([
+			{ method: "GET", match: /\?page\.limit=/, respond: () => jsonResponse({ items: [wsJson()] }) },
+			{
+				method: "DELETE",
+				match: /\/workspaces\/11111111-2222-3333-4444-555555555555$/,
+				respond: () => new Response(null, { status: 200 }),
+			},
+		])
+
+		const { code } = await run(["delete", "--force", "bright-oak-otter"], fetch)
+		expect(code).toBe(0)
+	})
+
+	it("declined confirmation deletes nothing (no DELETE request)", async () => {
+		// Resolution still runs (it names the target in the prompt) — only the
+		// DELETE must not happen: any DELETE route would throw "unexpected request".
+		const fetch = apiFetch([
+			{ method: "GET", match: /\?page\.limit=/, respond: () => jsonResponse({ items: [wsJson()] }) },
+		])
+
+		const { code, lines } = await run(["delete", "bright-oak-otter"], fetch, { confirm: async () => false })
+
+		expect(code).toBe(0)
+		expect(lines).toEqual(["Aborted."])
+	})
+
+	it("requires --force when non-interactive", async () => {
+		const fetch = apiFetch([
+			{ method: "GET", match: /\?page\.limit=/, respond: () => jsonResponse({ items: [wsJson()] }) },
+		])
+		const { code, errors } = await run(["delete", "bright-oak-otter"], fetch, { interactive: false })
+
+		expect(code).toBe(1)
+		expect(errors.some((l) => l.includes("--force"))).toBe(true)
+	})
+})

package/src/commands/workspace.ts

@@ -0,0 +1,250 @@
+import { resolveWorkspace } from "../api/resolver.js"
+import { formatAge, formatBytes, formatMillicores } from "../api/resources.js"
+import { resolveTemplate } from "../api/templates.js"
+import { waitForWorkspaceActive } from "../api/wait.js"
+import { createWorkspace, deleteWorkspace, listWorkspaces, type Workspace } from "../api/workspaces.js"
+import { requireApiKey } from "../auth/resolve.js"
+import { parseFlags, UsageError } from "./flags.js"
+import { confirm, isInteractive } from "./prompt.js"
+import { formatTable } from "./table.js"
+
+export interface WorkspaceDeps {
+	fetch?: typeof globalThis.fetch
+	env?: NodeJS.ProcessEnv
+	/** Override TTY interactivity detection (tests). */
+	interactive?: boolean
+	/** Confirmation override (tests). */
+	confirm?: (question: string) => Promise<boolean>
+	/** Clock override for deterministic AGE columns (tests). */
+	now?: () => Date
+	/** Sleep override for the create wait loop (tests). */
+	sleep?: (ms: number) => Promise<void>
+}
+
+const GROUP_USAGE = `Usage:
+  kimchictl workspace <verb> [options]
+
+Verbs:
+  create   Create a workspace (server generates the alias)
+  list     List workspaces  (alias: ls)
+  get      Show workspace details
+  delete   Delete a workspace  (alias: rm)
+
+Options:
+  --help   Show this help`
+
+/** `kimchictl workspace <verb> …` — group command; also mounted as hidden alias `ws`. */
+export async function runWorkspace(args: string[], deps: WorkspaceDeps = {}): Promise<number> {
+	const [verb, ...rest] = args
+	switch (verb) {
+		case "create":
+			return runCreate(rest, deps)
+		case "list":
+		case "ls":
+			return runList(rest, deps)
+		case "get":
+			return runGet(rest, deps)
+		case "delete":
+		case "rm":
+			return runDelete(rest, deps)
+		case "help":
+		case "--help":
+		case "-h":
+		case undefined:
+			console.log(GROUP_USAGE)
+			return verb === undefined ? 2 : 0
+		default:
+			console.error(`kimchictl workspace: unknown verb "${verb}"`)
+			console.error(GROUP_USAGE)
+			return 2
+	}
+}
+
+// ---------------------------------------------------------------- create
+
+async function runCreate(args: string[], deps: WorkspaceDeps): Promise<number> {
+	const { values, positionals } = parseFlags("workspace create", args, {
+		desc: { type: "string" },
+		template: { type: "string", short: "t" },
+		"no-wait": { type: "boolean" },
+		timeout: { type: "string", default: "60" },
+	})
+	if (positionals.length > 0) {
+		throw new UsageError(
+			"kimchictl workspace create: unexpected positional argument (workspaces are named by the server)",
+		)
+	}
+
+	const template = values.template
+	if (typeof template === "string" && template.length > 0) {
+		// Placeholder: errors gracefully until the templates API contract lands.
+		resolveTemplate(template)
+	}
+	if (values.template !== undefined && (typeof values.template !== "string" || values.template.length === 0)) {
+		throw new UsageError("kimchictl workspace create: --template must not be empty")
+	}
+
+	const timeoutSeconds = parseTimeoutSeconds(values.timeout, "workspace create")
+	const desc = typeof values.desc === "string" && values.desc.length > 0 ? values.desc : undefined
+
+	const { key } = requireApiKey(deps.env)
+	const sleep = deps.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)))
+
+	const created = await createWorkspace(key, { description: desc, fetch: deps.fetch })
+	console.error(`✓ created ${created.alias} (${created.status})`)
+
+	let current = created
+	if (!values["no-wait"]) {
+		// kap's create poll: 2s cadence, deadline, progress on stderr.
+		current = await waitForWorkspaceActive(key, created.id, {
+			fetch: deps.fetch,
+			timeoutMs: timeoutSeconds * 1000,
+			sleep,
+			onTick: (elapsedSeconds) => process.stderr.write(`\r  waiting… ${elapsedSeconds}s`),
+		})
+		process.stderr.write("\n")
+		if (current.status !== "active") {
+			console.error(`  ⚠ workspace still initializing — check with: kimchictl workspace get ${created.alias}`)
+		}
+	}
+
+	if (current.uri) console.error(`  uri  ${current.uri}`)
+	// The alias goes to stdout last so scripts can capture it: ALIAS=$(kimchictl workspace create)
+	console.log(current.alias)
+	return 0
+}
+
+function parseTimeoutSeconds(raw: unknown, command: string): number {
+	const seconds = typeof raw === "string" ? Number(raw) : Number.NaN
+	if (!Number.isInteger(seconds) || seconds <= 0) {
+		throw new UsageError(`kimchictl ${command}: --timeout must be a positive number of seconds`)
+	}
+	return seconds
+}
+
+// ---------------------------------------------------------------- list
+
+async function runList(args: string[], deps: WorkspaceDeps): Promise<number> {
+	const { values, positionals } = parseFlags("workspace list", args, {
+		output: { type: "string", short: "o", default: "table" },
+	})
+	if (positionals.length > 0) {
+		throw new UsageError("kimchictl workspace list: unexpected positional argument")
+	}
+	if (values.output !== "json" && values.output !== "table") {
+		// Validate before touching the network — usage errors fail fast and offline.
+		throw new UsageError(
+			`kimchictl workspace list: unsupported --output "${String(values.output)}" (expected table|json)`,
+		)
+	}
+
+	const { key } = requireApiKey(deps.env)
+	const workspaces = await listWorkspaces(key, { fetch: deps.fetch })
+
+	if (values.output === "json") {
+		console.log(JSON.stringify(workspaces.map(serializeWorkspace), null, 2))
+		return 0
+	}
+
+	const now = deps.now?.() ?? new Date()
+	const rows = workspaces.map((w) => [
+		w.alias,
+		w.status,
+		formatMillicores(w.cpuMillicores),
+		formatBytes(w.ramBytes),
+		formatAge(w.createdAt, now),
+	])
+	console.log(formatTable(["NAME", "STATUS", "CPU", "MEMORY", "AGE"], rows))
+	return 0
+}
+
+// ---------------------------------------------------------------- get
+
+async function runGet(args: string[], deps: WorkspaceDeps): Promise<number> {
+	const { values, positionals } = parseFlags("workspace get", args, {
+		output: { type: "string", short: "o", default: "text" },
+	})
+	if (positionals.length !== 1) {
+		throw new UsageError("kimchictl workspace get: expected exactly one workspace name")
+	}
+	if (values.output !== "json" && values.output !== "text") {
+		throw new UsageError(
+			`kimchictl workspace get: unsupported --output "${String(values.output)}" (expected text|json)`,
+		)
+	}
+
+	const { key } = requireApiKey(deps.env)
+	// Accepts a UUID, full alias, or alias prefix (see api/resolver.ts).
+	const workspace = await resolveWorkspace(key, positionals[0] ?? "", { fetch: deps.fetch })
+
+	if (values.output === "json") {
+		console.log(JSON.stringify(serializeWorkspace(workspace), null, 2))
+		return 0
+	}
+
+	const lines = [
+		`name:        ${workspace.alias}`,
+		workspace.description ? `description: ${workspace.description}` : undefined,
+		`status:      ${workspace.status}`,
+		workspace.uri ? `uri:         ${workspace.uri}` : undefined,
+		`created:     ${workspace.createdAt.toISOString()}`,
+		`cpu:         ${formatMillicores(workspace.cpuMillicores)}`,
+		`memory:      ${formatBytes(workspace.ramBytes)}`,
+		`storage:     ${formatBytes(workspace.pvcSizeBytes)}`,
+	].filter((line): line is string => line !== undefined)
+	for (const line of lines) console.log(line)
+	return 0
+}
+
+// ---------------------------------------------------------------- delete
+
+async function runDelete(args: string[], deps: WorkspaceDeps): Promise<number> {
+	const { values, positionals } = parseFlags("workspace delete", args, {
+		force: { type: "boolean", short: "f" },
+	})
+	if (positionals.length !== 1) {
+		throw new UsageError("kimchictl workspace delete: expected exactly one workspace name")
+	}
+	const ref = positionals[0] ?? ""
+
+	const { key } = requireApiKey(deps.env)
+	// Resolve before prompting so the confirmation names the real target and
+	// typos fail fast instead of after the user answered the prompt.
+	const workspace = await resolveWorkspace(key, ref, { fetch: deps.fetch })
+
+	if (!values.force) {
+		const interactive = deps.interactive ?? isInteractive()
+		const question = `Delete workspace "${workspace.alias}"? [y/N] `
+		const ok = await (deps.confirm ? deps.confirm(question) : interactive ? confirm(question) : false)
+		if (!ok) {
+			if (!deps.confirm && !interactive) {
+				console.error(`kimchictl workspace delete: not interactive — re-run with --force to delete ${workspace.alias}`)
+				return 1
+			}
+			console.log("Aborted.")
+			return 0
+		}
+	}
+
+	await deleteWorkspace(key, workspace.id, { fetch: deps.fetch })
+	console.log(`✓ deleted ${workspace.alias}`)
+	return 0
+}
+
+// ---------------------------------------------------------------- shared
+
+function serializeWorkspace(w: Workspace): Record<string, unknown> {
+	return {
+		id: w.id,
+		alias: w.alias,
+		...(w.description ? { description: w.description } : {}),
+		status: w.status,
+		...(w.uri ? { uri: w.uri } : {}),
+		createdAt: w.createdAt.getTime() > 0 ? w.createdAt.toISOString() : undefined,
+		resources: {
+			cpuMillicores: w.cpuMillicores,
+			ramBytes: w.ramBytes,
+			pvcSizeBytes: w.pvcSizeBytes,
+		},
+	}
+}

package/src/run.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { run } from "./run.js"
+import { VERSION } from "./version.js"
+
+describe("run dispatcher", () => {
+	let logLines: string[]
+	let errorLines: string[]
+
+	beforeEach(() => {
+		logLines = []
+		errorLines = []
+		vi.spyOn(console, "log").mockImplementation((...args: unknown[]) => {
+			logLines.push(args.map(String).join(" "))
+		})
+		vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+			errorLines.push(args.map(String).join(" "))
+		})
+	})
+
+	afterEach(() => {
+		vi.restoreAllMocks()
+	})
+
+	it("prints help and exits 0 with no args", async () => {
+		expect(await run([])).toBe(0)
+		expect(logLines.some((line) => line.includes("Usage:"))).toBe(true)
+	})
+
+	it("prints help for `help`, --help and -h", async () => {
+		for (const args of [["help"], ["--help"], ["-h"]]) {
+			expect(await run(args)).toBe(0)
+		}
+		expect(logLines.filter((line) => line.includes("Usage:"))).toHaveLength(3)
+	})
+
+	it("prints the version for the version command and --version / -v", async () => {
+		for (const args of [["version"], ["--version"], ["-v"]]) {
+			expect(await run(args)).toBe(0)
+		}
+		expect(logLines).toEqual([`kimchictl ${VERSION}`, `kimchictl ${VERSION}`, `kimchictl ${VERSION}`])
+	})
+
+	it("exits 2 and reports an unknown command, without printing help to stdout", async () => {
+		expect(await run(["frobnicate"])).toBe(2)
+		expect(errorLines[0]).toBe('kimchictl: unknown command "frobnicate"')
+		expect(logLines).toHaveLength(0)
+	})
+
+	it("omits hidden commands from help", async () => {
+		await run([])
+		expect(logLines.some((line) => line.includes("version"))).toBe(true)
+	})
+})

package/src/run.ts

@@ -0,0 +1,34 @@
+import { printHelp } from "./commands/help.js"
+import { COMMANDS, findCommand } from "./commands/registry.js"
+import { VERSION } from "./version.js"
+
+/** Usage errors (unknown command, bad flags) exit with this code. */
+export const EXIT_USAGE = 2
+
+/**
+ * Shared CLI dispatcher — the single entry behind the standalone `kimchictl`
+ * binary, the npm bin shim, and the kimchi harness bridge (`kimchi workspace`).
+ * Returns the exit code instead of calling process.exit so hosts can run it
+ * in-process.
+ */
+export async function run(argv: readonly string[]): Promise<number> {
+	const [head, ...rest] = argv
+
+	if (head === undefined || head === "help" || head === "--help" || head === "-h") {
+		printHelp(COMMANDS)
+		return 0
+	}
+	if (head === "--version" || head === "-v") {
+		console.log(`kimchictl ${VERSION}`)
+		return 0
+	}
+
+	const command = findCommand(head)
+	if (!command) {
+		console.error(`kimchictl: unknown command "${head}"`)
+		printHelp(COMMANDS, (line) => console.error(line))
+		return EXIT_USAGE
+	}
+
+	return (await command.run(rest)) ?? 0
+}