@kimchi-dev/kimchictl 0.0.2

package/src/commands/registry.ts

@@ -0,0 +1,50 @@
+import { runCompletion } from "./completion.js"
+import { guardCommand } from "./guard.js"
+import { runLogin } from "./login.js"
+import { runLogout } from "./logout.js"
+import { runSsh } from "./ssh.js"
+import { runUpdate } from "./update.js"
+import { runVersion } from "./version.js"
+import { runWhoami } from "./whoami.js"
+import { runWorkspace } from "./workspace.js"
+
+/**
+ * Shape mirrors kimchi-dev's `src/commands/registry.ts` CommandDefinition so
+ * the harness bridge can mount kimchictl commands without adaptation.
+ */
+export interface CommandDefinition {
+	name: string
+	summary: string
+	/** Hidden commands stay functional but are omitted from help (internal bridges like `ssh proxy`). */
+	hidden?: boolean
+	/** Run this command. Receives args after the command name. Return the exit code; undefined means 0. */
+	run: (args: string[]) => Promise<number | undefined> | number | undefined
+}
+
+export const COMMANDS: CommandDefinition[] = [
+	{ name: "login", summary: "Authenticate via browser (shared with the kimchi harness)", run: guardCommand(runLogin) },
+	{ name: "logout", summary: "Sign out everywhere (also signs out the harness)", run: guardCommand(runLogout) },
+	{ name: "whoami", summary: "Show the authenticated user", run: guardCommand(runWhoami) },
+	{
+		name: "workspace",
+		summary: "Manage remote workspaces (create/list/get/delete)",
+		run: guardCommand(runWorkspace),
+	},
+	{ name: "ws", summary: "Alias for workspace", hidden: true, run: guardCommand(runWorkspace) },
+	{ name: "ssh", summary: "Connect to a workspace over SSH", run: guardCommand(runSsh) },
+	{ name: "update", summary: "Check for and install a newer kimchictl release", run: guardCommand(runUpdate) },
+	{
+		name: "completion",
+		summary: "Print shell completions (kimchictl completion bash|zsh|fish)",
+		run: guardCommand(runCompletion),
+	},
+	{ name: "version", summary: "Print the kimchictl version", run: runVersion },
+]
+
+export function findCommand(name: string): CommandDefinition | undefined {
+	return COMMANDS.find((c) => c.name === name)
+}
+
+export function isKnownCommand(name: string | undefined): boolean {
+	return name !== undefined && COMMANDS.some((c) => c.name === name)
+}

package/src/commands/ssh.test.ts

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { captureConsole, cleanupTempDirs, makeTempDir } from "../test-support.js"
+import { guardCommand } from "./guard.js"
+import { runSsh } from "./ssh.js"
+
+beforeEach(() => {
+	const home = makeTempDir()
+	vi.stubEnv("HOME", home)
+	vi.stubEnv("KIMCHICTL_HOME", join(home, ".kimchictl"))
+	vi.stubEnv("KIMCHI_API_KEY", "key-1")
+})
+
+afterEach(() => {
+	cleanupTempDirs()
+	vi.unstubAllEnvs()
+	vi.restoreAllMocks()
+})
+
+const guard = guardCommand(runSsh)
+
+describe("kimchictl ssh", () => {
+	it("prints usage (exit 2) with no subcommand", async () => {
+		const { errors } = captureConsole()
+
+		const code = await guard([])
+
+		expect(code).toBe(2)
+		expect(errors[0]).toContain("kimchictl ssh <name>")
+	})
+
+	it("prints help (exit 0) for ssh help", async () => {
+		const { lines } = captureConsole()
+
+		const code = await guard(["help"])
+
+		expect(code).toBe(0)
+		expect(lines[0]).toContain("kimchictl ssh <name>")
+	})
+})
+
+describe("kimchictl ssh setup", () => {
+	it("configures integration, reports idempotency on repeat", async () => {
+		const { lines } = captureConsole()
+
+		const first = await guard(["setup"])
+		expect(first).toBe(0)
+		expect(lines.some((line) => line.startsWith("✓ SSH integration configured"))).toBe(true)
+		const sshConfigPath = join(process.env.KIMCHICTL_HOME ?? "", "ssh_config")
+		expect(readFileSync(sshConfigPath, "utf-8")).toContain("Host *.remote.kimchi.dev")
+		expect(readFileSync(join(process.env.HOME ?? "", ".ssh", "config"), "utf-8")).toContain("kimchictl managed include")
+
+		lines.length = 0
+		const second = await guard(["setup"])
+		expect(second).toBe(0)
+		expect(lines[0]).toContain("already configured")
+	})
+
+	it("honors --domain", async () => {
+		const { lines } = captureConsole()
+
+		await guard(["setup", "--domain", "remote.dev.example"])
+
+		const sshConfigPath = join(process.env.KIMCHICTL_HOME ?? "", "ssh_config")
+		expect(readFileSync(sshConfigPath, "utf-8")).toContain("Host *.remote.dev.example")
+		expect(lines.some((line) => line.includes("remote.dev.example"))).toBe(true)
+	})
+
+	it("--uninstall removes the integration", async () => {
+		captureConsole()
+		await guard(["setup"])
+		const userConfigPath = join(process.env.HOME ?? "", ".ssh", "config")
+
+		const code = await guard(["setup", "--uninstall"])
+
+		expect(code).toBe(0)
+		expect(existsSync(join(process.env.KIMCHICTL_HOME ?? "", "ssh_config"))).toBe(false)
+		expect(readFileSync(userConfigPath, "utf-8")).not.toContain("kimchictl managed include")
+	})
+
+	it("--uninstall on a fresh machine is a clean no-op", async () => {
+		const { lines } = captureConsole()
+
+		const code = await guard(["setup", "--uninstall"])
+
+		expect(code).toBe(0)
+		expect(lines[0]).toContain("Nothing to remove")
+	})
+})
+
+describe("kimchictl ssh proxy (usage validation)", () => {
+	it("rejects a missing host and a bad port with usage errors (exit 2)", async () => {
+		const { errors } = captureConsole()
+
+		expect(await guard(["proxy"])).toBe(2)
+		expect(await guard(["proxy", "ws-1.remote.kimchi.dev", "--port", "nope"])).toBe(2)
+		expect(errors.some((line) => line.includes("one host"))).toBe(true)
+		expect(errors.some((line) => line.includes("--port"))).toBe(true)
+	})
+})

package/src/commands/ssh.ts

@@ -0,0 +1,112 @@
+import { verifyApiKey } from "../api/keys.js"
+import { requireApiKey } from "../auth/resolve.js"
+import { bridgeStdioToWebSocket } from "../ssh/bridge.js"
+import {
+	isSshIntegrationConfigured,
+	resolveSshDomain,
+	resolveSshPaths,
+	setupSshIntegration,
+	uninstallSshIntegration,
+} from "../ssh/config.js"
+import { connectToWorkspace } from "../ssh/connect.js"
+import { resolveTunnel } from "../ssh/tunnel.js"
+import { parseFlags, UsageError } from "./flags.js"
+
+export interface SshDeps {
+	fetch?: typeof globalThis.fetch
+	env?: NodeJS.ProcessEnv
+	interactive?: boolean
+	/** Exec seam (tests). */
+	exec?: (args: string[]) => number
+	sleep?: (ms: number) => Promise<void>
+}
+
+const GROUP_USAGE = `Usage:
+  kimchictl ssh <name> [command...]   Connect to a workspace (auto-configures SSH on first use)
+  kimchictl ssh setup [--uninstall]   Manage the native SSH integration`
+
+/**
+ * `kimchictl ssh …` — connect, or manage the SSH integration. The hidden
+ * `proxy` subcommand is the ProxyCommand target in the generated ssh_config
+ * and is deliberately absent from help (internal plumbing, not user-facing).
+ */
+export async function runSsh(args: string[], deps: SshDeps = {}): Promise<number> {
+	const [head, ...rest] = args
+	switch (head) {
+		case "setup":
+			return runSetup(rest, deps)
+		case "proxy":
+			return runProxy(rest, deps)
+		case "help":
+		case "--help":
+		case "-h":
+			console.log(GROUP_USAGE)
+			return 0
+		case undefined:
+			console.error(GROUP_USAGE)
+			return 2
+		default:
+			return connectToWorkspace(head, rest, deps)
+	}
+}
+
+// ---------------------------------------------------------------- setup
+
+async function runSetup(args: string[], deps: SshDeps): Promise<number> {
+	const { values, positionals } = parseFlags("ssh setup", args, {
+		uninstall: { type: "boolean" },
+		domain: { type: "string" },
+	})
+	if (positionals.length > 0) {
+		throw new UsageError("kimchictl ssh setup: unexpected positional argument")
+	}
+	const env = deps.env ?? process.env
+	const paths = resolveSshPaths(env)
+
+	if (values.uninstall) {
+		const { notes } = await uninstallSshIntegration({ paths })
+		if (notes.length === 0) {
+			console.log("Nothing to remove — SSH integration was not configured.")
+			return 0
+		}
+		console.log("✓ SSH integration removed")
+		for (const note of notes) console.log(`  ${note}`)
+		return 0
+	}
+
+	const domain = resolveSshDomain(typeof values.domain === "string" && values.domain ? values.domain : undefined, env)
+	if (await isSshIntegrationConfigured(paths, domain)) {
+		console.log(`SSH integration already configured for *.${domain} (undo: kimchictl ssh setup --uninstall)`)
+		return 0
+	}
+
+	const { notes } = await setupSshIntegration({ paths, domain })
+	console.log("✓ SSH integration configured")
+	for (const note of notes) console.log(`  ${note}`)
+	console.log("") // blank line before the usage hint
+	console.log(`You can now run: ssh <workspace-name>.${domain}   (scp, VS Code Remote-SSH, …)`)
+	return 0
+}
+
+// ---------------------------------------------------------------- proxy (hidden)
+
+async function runProxy(args: string[], deps: SshDeps): Promise<number> {
+	const { values, positionals } = parseFlags("ssh proxy", args, {
+		port: { type: "string", default: "443" },
+	})
+	const host = positionals[0]
+	if (!host || positionals.length > 1) {
+		throw new UsageError("kimchictl ssh proxy: expected one host")
+	}
+	const port = Number(values.port)
+	if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+		throw new UsageError("kimchictl ssh proxy: --port must be an integer 1-65535")
+	}
+
+	const env = deps.env ?? process.env
+	const { key } = requireApiKey(env)
+	await verifyApiKey(key, { fetch: deps.fetch })
+	const creds = await resolveTunnel(key, host, { port, fetch: deps.fetch })
+	await bridgeStdioToWebSocket({ wsUrl: creds.wsUrl, token: creds.token })
+	return 0
+}

package/src/commands/table.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest"
+import { formatTable } from "./table.js"
+
+describe("formatTable", () => {
+	it("pads columns to the widest cell and trims trailing whitespace", () => {
+		expect(
+			formatTable(
+				["NAME", "STATUS"],
+				[
+					["bright-oak-otter", "active"],
+					["demo", "suspended"],
+				],
+			),
+		).toBe("NAME              STATUS\nbright-oak-otter  active\n" + "demo              suspended")
+	})
+
+	it("renders headers alone when there are no rows", () => {
+		expect(formatTable(["A", "B"], [])).toBe("A  B")
+	})
+
+	it("tolerates ragged rows", () => {
+		expect(formatTable(["A", "B"], [["x"]])).toBe("A  B\nx")
+	})
+})

package/src/commands/table.ts

@@ -0,0 +1,10 @@
+/** Minimal kubectl-style table renderer: pad columns to the widest cell, two-space gutter. */
+export function formatTable(headers: readonly string[], rows: readonly (readonly string[])[]): string {
+	const widths = headers.map((header, i) => Math.max(header.length, ...rows.map((row) => row[i]?.length ?? 0)))
+	const line = (cells: readonly string[]) =>
+		cells
+			.map((cell, i) => cell.padEnd(widths[i] ?? 0))
+			.join("  ")
+			.trimEnd()
+	return [line(headers), ...rows.map(line)].join("\n")
+}

package/src/commands/update.test.ts

@@ -0,0 +1,91 @@
+import { mkdtempSync, readFileSync } from "node:fs"
+import { writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { captureConsole, jsonResponse, stubFetch } from "../test-support.js"
+import { runUpdate, type UpdateDeps } from "./update.js"
+
+afterEach(() => {
+	vi.restoreAllMocks()
+	vi.unstubAllEnvs()
+})
+
+function latestReleaseFetch(version: string): typeof globalThis.fetch {
+	return stubFetch(async (url) => {
+		if (url.includes("releases/latest")) return jsonResponse({ tag_name: version })
+		throw new Error(`unexpected request: ${url}`)
+	}) as typeof globalThis.fetch
+}
+
+const DIRECTED_DEPS: { [method: string]: Partial<UpdateDeps> } = {
+	homebrew: { installMethod: "homebrew" },
+	runtime: { installMethod: "runtime" },
+}
+
+describe("kimchictl update", () => {
+	it("delegates to Homebrew for brew installs", async () => {
+		const { lines } = captureConsole()
+
+		const code = await runUpdate([], DIRECTED_DEPS.homebrew as UpdateDeps)
+
+		expect(code).toBe(0)
+		expect(lines.join("\n")).toContain("brew upgrade kimchictl")
+	})
+
+	it("delegates to npm for runtime installs", async () => {
+		const { lines } = captureConsole()
+
+		const code = await runUpdate([], DIRECTED_DEPS.runtime as UpdateDeps)
+
+		expect(code).toBe(0)
+		expect(lines.join("\n")).toContain("npm update -g kimchictl")
+	})
+
+	it("skips self-update for dev builds", async () => {
+		const { lines } = captureConsole()
+
+		const code = await runUpdate([], { installMethod: "binary", currentVersion: "0.0.0-dev" })
+
+		expect(code).toBe(0)
+		expect(lines.join("\n")).toContain("Dev build")
+	})
+
+	it("reports when already up to date", async () => {
+		const { lines } = captureConsole()
+
+		const code = await runUpdate([], {
+			installMethod: "binary",
+			currentVersion: "0.3.0",
+			fetch: latestReleaseFetch("0.3.0"),
+		})
+
+		expect(code).toBe(0)
+		expect(lines.join("\n")).toContain("already up to date")
+	})
+
+	it("downloads and swaps in the new binary", async () => {
+		const { lines } = captureConsole()
+		const dir = mkdtempSync(join(tmpdir(), "kimchictl-update-test-"))
+		const target = join(dir, "kimchictl")
+		const payload = Buffer.from("#!/bin/fake new kimchictl\n")
+
+		const code = await runUpdate([], {
+			installMethod: "binary",
+			currentVersion: "0.2.0",
+			targetPath: target,
+			fetch: stubFetch(async (url) => {
+				if (url.includes("releases/latest")) return jsonResponse({ tag_name: "0.3.0" })
+				throw new Error(`unexpected request: ${url}`)
+			}) as typeof globalThis.fetch,
+			download: async (url, dest) => {
+				if (url.endsWith("checksums.txt")) throw new Error("404")
+				await writeFile(dest, payload)
+			},
+		})
+
+		expect(code).toBe(0)
+		expect(readFileSync(target)).toEqual(payload)
+		expect(lines.join("\n")).toContain("✓ kimchictl 0.3.0 installed")
+	})
+})

package/src/commands/update.ts

@@ -0,0 +1,78 @@
+import { fetchWithTimeout } from "../api/http.js"
+import { defaultInstallMethod, type InstallMethod, platformAssetName, selfUpdateToVersion } from "../updates/self.js"
+import { VERSION } from "../version.js"
+import { parseFlags, UsageError } from "./flags.js"
+
+export interface UpdateDeps {
+	fetch?: typeof globalThis.fetch
+	env?: NodeJS.ProcessEnv
+	/** Injection seams (tests). */
+	installMethod?: InstallMethod
+	download?: (url: string, destPath: string) => Promise<void>
+	targetPath?: string
+	currentVersion?: string
+}
+
+const LATEST_RELEASE_URL = "https://api.github.com/repos/getkimchi/kimchictl/releases/latest"
+
+async function fetchLatestVersion(fetchImpl: typeof globalThis.fetch): Promise<string | undefined> {
+	const resp = await fetchWithTimeout(
+		LATEST_RELEASE_URL,
+		{ headers: { "User-Agent": `kimchictl/${VERSION}` } },
+		fetchImpl,
+		15_000,
+	)
+	if (!resp.ok) return undefined
+	const data = (await resp.json()) as { tag_name?: string }
+	return typeof data.tag_name === "string" ? data.tag_name.replace(/^v/, "") : undefined
+}
+
+/**
+ * `kimchictl update` — self-updates binary installs in place, tells brew/npm
+ * users the command their package manager owns.
+ */
+export async function runUpdate(args: string[], deps: UpdateDeps = {}): Promise<number> {
+	const { positionals } = parseFlags("update", args, {})
+	if (positionals.length > 0) {
+		throw new UsageError("kimchictl update: unexpected positional argument")
+	}
+
+	const method = deps.installMethod ?? defaultInstallMethod()
+
+	if (method === "homebrew") {
+		console.log("kimchictl was installed via Homebrew — update with:")
+		console.log("")
+		console.log("  brew upgrade kimchictl")
+		return 0
+	}
+	if (method === "runtime") {
+		console.log("This kimchictl runs under a JS runtime (npm install or dev checkout) — update with:")
+		console.log("")
+		console.log("  npm update -g kimchictl     # npm users")
+		console.log("  git pull && pnpm install    # source checkouts")
+		return 0
+	}
+
+	const current = deps.currentVersion ?? VERSION
+	if (current.endsWith("-dev")) {
+		console.log("Dev build — self-update only works for released binaries.")
+		return 0
+	}
+
+	const fetchImpl = deps.fetch ?? globalThis.fetch
+	const latest = await fetchLatestVersion(fetchImpl)
+	if (latest === undefined) {
+		console.error("✗ could not determine the latest release (GitHub API unavailable)")
+		return 1
+	}
+	if (latest === current) {
+		console.log(`kimchictl ${current} — already up to date.`)
+		return 0
+	}
+
+	const targetPath = deps.targetPath ?? process.execPath
+	console.log(`updating kimchictl ${current} → ${latest} (${platformAssetName()})…`)
+	await selfUpdateToVersion({ targetPath, version: latest, fetch: fetchImpl, download: deps.download })
+	console.log(`✓ kimchictl ${latest} installed at ${targetPath}`)
+	return 0
+}

package/src/commands/version.ts

@@ -0,0 +1,6 @@
+import { VERSION } from "../version.js"
+
+export function runVersion(): number {
+	console.log(`kimchictl ${VERSION}`)
+	return 0
+}

package/src/commands/whoami.test.ts

@@ -0,0 +1,72 @@
+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 { runWhoami } from "./whoami.js"
+
+afterEach(() => {
+	cleanupTempDirs()
+	vi.unstubAllEnvs()
+	vi.restoreAllMocks()
+})
+
+const guardedWhoami = guardCommand(runWhoami)
+
+function seedAuth(dir: string): void {
+	writeFileSync(join(dir, "auth.json"), JSON.stringify({ "kimchi-dev": { type: "api_key", key: "key" } }))
+}
+
+describe("kimchictl whoami", () => {
+	it("prints the profile (text) and the key source on stderr", async () => {
+		const dir = makeTempDir()
+		stubAgentDirEnv(dir)
+		seedAuth(dir)
+		const { lines, errors } = captureConsole()
+		const fetch = stubFetch(async (url) => {
+			expect(url).toBe("https://app.kimchi.dev/api/v1/me")
+			return jsonResponse({ id: "user-1", username: "mike", email: "m@example.com" })
+		})
+
+		expect(await guardedWhoami([], { fetch })).toBe(0)
+		expect(lines).toEqual(["id:       user-1", "username: mike", "email:    m@example.com"])
+		expect(errors).toEqual(["(authenticated via auth.json)"])
+	})
+
+	it("prints JSON with --output json", async () => {
+		const dir = makeTempDir()
+		stubAgentDirEnv(dir)
+		seedAuth(dir)
+		const { lines } = captureConsole()
+		const fetch = stubFetch(async () => jsonResponse({ id: "user-1", email: "m@example.com" }))
+
+		expect(await guardedWhoami(["--output", "json"], { fetch })).toBe(0)
+		expect(lines).toEqual([JSON.stringify({ id: "user-1", email: "m@example.com" })])
+	})
+
+	it("reports not-logged-in via the guard (no stack trace)", async () => {
+		stubAgentDirEnv(makeTempDir())
+		const { errors } = captureConsole()
+
+		expect(await guardedWhoami([])).toBe(1)
+		expect(errors[0]).toMatch(/Not logged in/)
+	})
+
+	it("rejects an unknown --output flavor as usage error", async () => {
+		const dir = makeTempDir()
+		stubAgentDirEnv(dir)
+		seedAuth(dir)
+		const { errors } = captureConsole()
+		const fetch = stubFetch(async () => jsonResponse({ id: "u1" }))
+
+		expect(await guardedWhoami(["--output", "yaml"], { fetch })).toBe(2)
+		expect(errors[0]).toMatch(/unsupported --output "yaml"/)
+	})
+})

package/src/commands/whoami.ts

@@ -0,0 +1,36 @@
+import { getMe } from "../api/me.js"
+import { requireApiKey } from "../auth/resolve.js"
+import { parseFlags } from "./flags.js"
+
+export interface WhoamiDeps {
+	fetch?: typeof globalThis.fetch
+	env?: NodeJS.ProcessEnv
+}
+
+/** `kimchictl whoami` — show the authenticated user (GET /v1/me). */
+export async function runWhoami(args: string[], deps: WhoamiDeps = {}): Promise<number> {
+	const { values } = parseFlags("whoami", args, {
+		output: { type: "string", short: "o", default: "text" },
+	})
+	const env = deps.env ?? process.env
+
+	const { key, source } = requireApiKey(env)
+	if (values.output !== "json" && values.output !== "text") {
+		console.error(`kimchictl whoami: unsupported --output "${values.output}" (expected text|json)`)
+		return 2
+	}
+	const me = await getMe(key, { fetch: deps.fetch })
+
+	if (values.output === "json") {
+		console.log(JSON.stringify(me))
+	} else {
+		console.log(`id:       ${me.id}`)
+		if (me.username) console.log(`username: ${me.username}`)
+		if (me.email) console.log(`email:    ${me.email}`)
+		// Key source goes to stderr so stdout stays machine-parseable.
+		console.error(
+			`(authenticated via ${source === "environment" ? "KIMCHI_API_KEY" : source === "config" ? "config.json" : "auth.json"})`,
+		)
+	}
+	return 0
+}