@kimchi-dev/kimchictl 0.0.2

package/src/api/resolver.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest"
+import { jsonResponse, stubFetch } from "../test-support.js"
+import { AmbiguousWorkspaceError, isWorkspaceUuid, resolveWorkspace, WorkspaceNotFoundError } from "./resolver.js"
+
+const UUID = "3d3dc322-dd05-4d0c-adab-beb2a0819e69"
+
+function wsJson(alias: string, over: Record<string, unknown> = {}): Record<string, unknown> {
+	return {
+		id: UUID,
+		description: "",
+		status: "ACTIVE",
+		createTime: "2026-01-01T00:00:00Z",
+		uri: `${alias}.remote.kimchi.dev`,
+		spec: { resources: { cpu: "1", memory: "2Gi", pvcSize: "10Gi" } },
+		...over,
+	}
+}
+
+function apiFetch(routes: { method: string; match: RegExp; respond: () => Response }[]): typeof globalThis.fetch {
+	return stubFetch(async (url, init) => {
+		if ((init?.method ?? "GET") === "POST" && url.endsWith("workspace-tokens:verifyKey")) {
+			return jsonResponse({ organizationId: "org-1" })
+		}
+		for (const route of routes) {
+			if (route.method === (init?.method ?? "GET") && route.match.test(url)) return route.respond()
+		}
+		throw new Error(`unexpected request: ${init?.method ?? "GET"} ${url}`)
+	})
+}
+
+describe("isWorkspaceUuid", () => {
+	it("recognizes UUID shapes only", () => {
+		expect(isWorkspaceUuid(UUID)).toBe(true)
+		expect(isWorkspaceUuid(UUID.toUpperCase())).toBe(true)
+		expect(isWorkspaceUuid("pensive-brainy-kimchi")).toBe(false)
+		expect(isWorkspaceUuid("3d3dc322-dd05-4d0c-adab-beb2a0819e6")).toBe(false)
+	})
+})
+
+describe("resolveWorkspace", () => {
+	it("goes straight to GET for a UUID ref (no list call)", async () => {
+		const fetch = apiFetch([
+			{ method: "GET", match: new RegExp(`/${UUID}$`), respond: () => jsonResponse(wsJson("pensive-brainy")) },
+		])
+
+		const ws = await resolveWorkspace("key-1", UUID, { fetch })
+
+		expect(ws.id).toBe(UUID)
+		expect(ws.alias).toBe("pensive-brainy")
+	})
+
+	it("maps a 404 on the UUID path to WorkspaceNotFoundError", async () => {
+		const fetch = apiFetch([
+			{ method: "GET", match: new RegExp(`/${UUID}$`), respond: () => new Response("gone", { status: 404 }) },
+		])
+
+		await expect(resolveWorkspace("key-1", UUID, { fetch })).rejects.toThrow(WorkspaceNotFoundError)
+	})
+
+	it("resolves an exact alias via the workspace list", async () => {
+		const fetch = apiFetch([
+			{
+				method: "GET",
+				match: /\?page\.limit=/,
+				respond: () => jsonResponse({ items: [wsJson("bright-oak-otter"), wsJson("pensive-brainy")] }),
+			},
+		])
+
+		const ws = await resolveWorkspace("key-1", "pensive-brainy", { fetch })
+
+		expect(ws.alias).toBe("pensive-brainy")
+		expect(ws.id).toBe(UUID)
+	})
+
+	it("resolves a case-insensitive alias prefix", async () => {
+		const fetch = apiFetch([
+			{
+				method: "GET",
+				match: /\?page\.limit=/,
+				respond: () => jsonResponse({ items: [wsJson("bright-oak-otter"), wsJson("pensive-brainy")] }),
+			},
+		])
+
+		const ws = await resolveWorkspace("key-1", "Pensive", { fetch })
+
+		expect(ws.alias).toBe("pensive-brainy")
+	})
+
+	it("lists candidates when a prefix is ambiguous", async () => {
+		const fetch = apiFetch([
+			{
+				method: "GET",
+				match: /\?page\.limit=/,
+				respond: () => jsonResponse({ items: [wsJson("bright-oak-otter"), wsJson("bright-oak-owl")] }),
+			},
+		])
+
+		await expect(resolveWorkspace("key-1", "bright-oak", { fetch })).rejects.toThrow(AmbiguousWorkspaceError)
+		await expect(resolveWorkspace("key-1", "bright-oak", { fetch })).rejects.toThrow(/bright-oak-otter, bright-oak-owl/)
+	})
+
+	it("throws WorkspaceNotFoundError when nothing matches", async () => {
+		const fetch = apiFetch([
+			{ method: "GET", match: /\?page\.limit=/, respond: () => jsonResponse({ items: [wsJson("bright-oak-otter")] }) },
+		])
+
+		await expect(resolveWorkspace("key-1", "ghost", { fetch })).rejects.toThrow(/No workspace matches "ghost"/)
+	})
+})

package/src/api/resolver.ts

@@ -0,0 +1,72 @@
+import type { ApiOptions } from "./types.js"
+import { RemoteAuthError } from "./types.js"
+import { getWorkspace, listWorkspaces, type Workspace, type WorkspaceCommandOptions } from "./workspaces.js"
+
+/**
+ * Workspace reference resolution — a port of kap's internal/resolver.
+ *
+ * Users type the alias (the first DNS label of the workspace URI) or a
+ * prefix of it; the control plane addresses workspaces by UUID. Resolution:
+ *   1. UUID-shaped refs go straight to GET (404 → not found).
+ *   2. Anything else lists workspaces and matches, in order:
+ *      exact id, exact alias, case-insensitive alias prefix.
+ *   3. No match → WorkspaceNotFoundError; multiple matches →
+ *      AmbiguousWorkspaceError listing the candidates.
+ *
+ * kap caches the list for 30s — pointless in a one-shot CLI process, so
+ * this port is uncached.
+ */
+
+export class WorkspaceNotFoundError extends Error {
+	constructor(ref: string) {
+		super(`No workspace matches "${ref}" — list workspaces with: kimchictl workspace list`)
+		this.name = "WorkspaceNotFoundError"
+	}
+}
+
+export class AmbiguousWorkspaceError extends Error {
+	constructor(ref: string, candidates: readonly string[]) {
+		super(`Multiple workspaces match "${ref}": ${candidates.join(", ")} — use the full alias`)
+		this.name = "AmbiguousWorkspaceError"
+	}
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export function isWorkspaceUuid(ref: string): boolean {
+	return UUID_RE.test(ref)
+}
+
+function matchesRef(ws: Workspace, ref: string): boolean {
+	if (ws.id === ref) return true
+	if (ws.alias === ref) return true
+	return ws.alias.toLowerCase().startsWith(ref.toLowerCase())
+}
+
+/** Resolve a workspace reference (UUID, alias, or alias prefix) to the workspace. */
+export async function resolveWorkspace(
+	apiKey: string,
+	ref: string,
+	options?: WorkspaceCommandOptions & ApiOptions,
+): Promise<Workspace> {
+	if (isWorkspaceUuid(ref)) {
+		try {
+			return await getWorkspace(apiKey, ref, options)
+		} catch (err) {
+			if (err instanceof RemoteAuthError && err.statusCode === 404) {
+				throw new WorkspaceNotFoundError(ref)
+			}
+			throw err
+		}
+	}
+
+	const workspaces = await listWorkspaces(apiKey, options)
+	const matched = workspaces.filter((ws) => matchesRef(ws, ref))
+	const [unique] = matched
+	if (matched.length === 1 && unique) return unique
+	if (matched.length === 0) throw new WorkspaceNotFoundError(ref)
+	throw new AmbiguousWorkspaceError(
+		ref,
+		matched.map((ws) => ws.alias),
+	)
+}

package/src/api/resources.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest"
+import { byteQuantityToBytes, cpuQuantityToMillicores, formatAge, formatBytes, formatMillicores } from "./resources.js"
+
+describe("quantity parsing", () => {
+	it.each([
+		["200m", 200],
+		["1.5", 1500],
+		["2", 2000],
+		["1e1", 10000],
+	])("cpuQuantityToMillicores(%s) → %d", (input, expected) => {
+		expect(cpuQuantityToMillicores(input)).toBe(expected)
+	})
+
+	it.each([
+		["512Mi", 536870912],
+		["1G", 1000000000],
+		["1.5Gi", 1610612736],
+		["20Gi", 21474836480],
+	])("byteQuantityToBytes(%s) → %d", (input, expected) => {
+		expect(byteQuantityToBytes(input)).toBe(expected)
+	})
+
+	it.each([["not-a-quantity"], ["-5"], ["1e3m"], [""]])("rejects %s", (input) => {
+		expect(cpuQuantityToMillicores(input)).toBeUndefined()
+		expect(byteQuantityToBytes(input)).toBeUndefined()
+	})
+})
+
+describe("display formatting", () => {
+	it("formats millicores", () => {
+		expect(formatMillicores(undefined)).toBe("-")
+		expect(formatMillicores(250)).toBe("250m")
+		expect(formatMillicores(1000)).toBe("1")
+		expect(formatMillicores(1500)).toBe("1.5")
+		expect(formatMillicores(2000)).toBe("2")
+	})
+
+	it("formats bytes", () => {
+		expect(formatBytes(undefined)).toBe("-")
+		expect(formatBytes(536870912)).toBe("512Mi")
+		expect(formatBytes(2147483648)).toBe("2Gi")
+		expect(formatBytes(1610612736)).toBe("1.5Gi")
+		expect(formatBytes(2048)).toBe("2Ki")
+		expect(formatBytes(100)).toBe("100B")
+	})
+
+	it("formats ages", () => {
+		const now = new Date("2026-01-02T12:00:00Z")
+		expect(formatAge(new Date("2026-01-02T11:59:30Z"), now)).toBe("30s")
+		expect(formatAge(new Date("2026-01-02T11:45:00Z"), now)).toBe("15m")
+		expect(formatAge(new Date("2026-01-02T09:00:00Z"), now)).toBe("3h")
+		expect(formatAge(new Date("2025-12-28T12:00:00Z"), now)).toBe("5d")
+		// Clock skew must never produce a negative age.
+		expect(formatAge(new Date("2027-01-01T00:00:00Z"), now)).toBe("0s")
+	})
+})

package/src/api/resources.ts

@@ -0,0 +1,92 @@
+/**
+ * Kubernetes quantity parsing (port of kimchi-dev:src/sandbox/cloud/resources.ts,
+ * trimmed to what the workspace list/detail rendering needs) plus display
+ * formatters for human tables.
+ */
+
+/**
+ * Kubernetes quantity: mantissa, then EITHER an exponent OR a decimal/binary
+ * SI suffix — never both.
+ */
+const QUANTITY_RE = /^([0-9]+(?:\.[0-9]+)?|\.[0-9]+)([eE][+-]?[0-9]+|n|u|m|k|M|G|T|P|E|Ki|Mi|Gi|Ti|Pi|Ei)?$/
+
+const DECIMAL_SUFFIX: Record<string, number> = {
+	n: 1e-9,
+	u: 1e-6,
+	m: 1e-3,
+	k: 1e3,
+	M: 1e6,
+	G: 1e9,
+	T: 1e12,
+	P: 1e15,
+	E: 1e18,
+}
+
+const BINARY_SUFFIX: Record<string, number> = {
+	Ki: 1024,
+	Mi: 1024 ** 2,
+	Gi: 1024 ** 3,
+	Ti: 1024 ** 4,
+	Pi: 1024 ** 5,
+	Ei: 1024 ** 6,
+}
+
+function parseQuantity(raw: unknown): number | undefined {
+	if (typeof raw !== "string") return undefined
+	const match = QUANTITY_RE.exec(raw.trim())
+	if (!match) return undefined
+	const mantissa = Number.parseFloat(match[1] ?? "")
+	if (!Number.isFinite(mantissa)) return undefined
+	const suffix = match[2]
+	if (suffix === undefined) return mantissa
+	if (/^[eE][+-]?[0-9]+$/.test(suffix)) {
+		return mantissa * 10 ** Number.parseInt(suffix.slice(1), 10)
+	}
+	return mantissa * (BINARY_SUFFIX[suffix] ?? DECIMAL_SUFFIX[suffix] ?? 1)
+}
+
+/** "200m" → 200, "1.5" → 1500. Undefined for absent/invalid. */
+export function cpuQuantityToMillicores(raw: unknown): number | undefined {
+	const cores = parseQuantity(raw)
+	return cores === undefined ? undefined : Math.round(cores * 1000)
+}
+
+/** "512Mi" → 536870912, "1G" → 1000000000. Undefined for absent/invalid. */
+export function byteQuantityToBytes(raw: unknown): number | undefined {
+	const bytes = parseQuantity(raw)
+	return bytes === undefined ? undefined : Math.round(bytes)
+}
+
+/** 1000 → "1", 1500 → "1.5", 250 → "250m", undefined → "-". */
+export function formatMillicores(millicores: number | undefined): string {
+	if (millicores === undefined) return "-"
+	if (millicores < 1000) return `${millicores}m`
+	const cores = millicores / 1000
+	return Number.isInteger(cores) ? String(cores) : cores.toFixed(2).replace(/0+$/, "").replace(/\.$/, "")
+}
+
+/** 2147483648 → "2Gi", 536870912 → "512Mi", undefined → "-". */
+export function formatBytes(bytes: number | undefined): string {
+	if (bytes === undefined) return "-"
+	const GI = 1024 ** 3
+	const MI = 1024 ** 2
+	if (bytes >= GI) return formatUnit(bytes / GI, "Gi")
+	if (bytes >= MI) return formatUnit(bytes / MI, "Mi")
+	if (bytes >= 1024) return formatUnit(bytes / 1024, "Ki")
+	return `${bytes}B`
+}
+
+function formatUnit(value: number, suffix: string): string {
+	return `${Number.isInteger(value) ? value : value.toFixed(1)}${suffix}`
+}
+
+/** Relative age for table columns: "45s", "12m", "3h", "5d". */
+export function formatAge(since: Date, now: Date = new Date()): string {
+	const seconds = Math.max(0, Math.floor((now.getTime() - since.getTime()) / 1000))
+	if (seconds < 60) return `${seconds}s`
+	const minutes = Math.floor(seconds / 60)
+	if (minutes < 60) return `${minutes}m`
+	const hours = Math.floor(minutes / 60)
+	if (hours < 48) return `${hours}h`
+	return `${Math.floor(hours / 24)}d`
+}

package/src/api/templates.ts

@@ -0,0 +1,28 @@
+/**
+ * Server-side workspace templates — PLACEHOLDER.
+ *
+ * Templates are created and stored in the API (they are not local files).
+ * The API contract is being finalised server-side; until it lands,
+ * `workspace create --template <name>` is accepted at the CLI and fails here
+ * with a graceful, actionable error instead of a 4xx surprise.
+ */
+
+export class TemplatesUnavailableError extends Error {
+	constructor(templateName: string) {
+		super(
+			`Workspace templates are not available yet (requested "${templateName}") — ` +
+				`the templates API is being finalised. Omit --template for now.`,
+		)
+		this.name = "TemplatesUnavailableError"
+	}
+}
+
+/**
+ * Resolve a template name to its create-time parameters.
+ *
+ * TODO(templates-api): replace with the real call once the contract lands —
+ * expected to return resources/dependencies applied at create time.
+ */
+export function resolveTemplate(templateName: string): never {
+	throw new TemplatesUnavailableError(templateName)
+}

package/src/api/tokens.ts

@@ -0,0 +1,80 @@
+import { checkResponse, fetchWithTimeout, resolveEndpoint } from "./http.js"
+import type { ApiOptions } from "./types.js"
+import { RemoteNetworkError } from "./types.js"
+
+/**
+ * Workspace token exchange + lifecycle RPCs (ports of the corresponding
+ * kimchi-dev:src/sandbox/cloud/auth.ts functions, without the harness's
+ * upsert semantics — kimchictl only resumes, never upserts).
+ */
+
+/** Exchange the API key for a short-lived workspace JWT (WebSocket auth). */
+export async function exchangeWorkspaceToken(
+	apiKey: string,
+	workspaceId: string,
+	options?: ApiOptions & { orgId?: string },
+): Promise<{ token: string; expireTime: string }> {
+	const endpoint = resolveEndpoint(options)
+	const fetchImpl = options?.fetch ?? globalThis.fetch
+
+	const url = `${endpoint}/ai-optimizer/v1beta/workspace-tokens:exchange`
+	const resp = await fetchWithTimeout(
+		url,
+		{
+			method: "POST",
+			headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+			body: JSON.stringify({ workspaceId }),
+		},
+		fetchImpl,
+		30_000,
+		options?.signal,
+	)
+
+	await checkResponse(resp, url)
+
+	const data = (await resp.json().catch(() => undefined)) as { token?: unknown; expireTime?: unknown } | undefined
+	if (typeof data?.token !== "string") {
+		throw new RemoteNetworkError(`Missing token in exchange response from ${endpoint}`)
+	}
+	return { token: data.token, expireTime: typeof data.expireTime === "string" ? data.expireTime : "" }
+}
+
+/**
+ * Resume a suspended (hibernated) workspace: POST …/workspaces/{id}:resume.
+ *
+ * Success and "workspace is not suspended" (the control plane's FailedPrecondition
+ * 400) both mean the workspace is running. Every other failure propagates.
+ */
+export async function resumeWorkspace(
+	apiKey: string,
+	workspaceId: string,
+	options: ApiOptions & { orgId: string },
+): Promise<void> {
+	const endpoint = resolveEndpoint(options)
+	const fetchImpl = options?.fetch ?? globalThis.fetch
+
+	const url = `${endpoint}/ai-optimizer/v1beta/organizations/${encodeURIComponent(options.orgId)}/workspaces/${encodeURIComponent(workspaceId)}:resume`
+	const resp = await fetchWithTimeout(
+		url,
+		{
+			method: "POST",
+			headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+			body: JSON.stringify({}),
+		},
+		fetchImpl,
+		30_000,
+		options?.signal,
+	)
+
+	if (resp.ok) return
+
+	// Clone BEFORE consuming the body: checkResponse re-reads resp.text() and a
+	// second read of the same body fails in undici.
+	const rest = resp.clone()
+	const body = await resp.text().catch(() => "")
+	if (resp.status >= 400 && resp.status < 500 && body.includes("not suspended")) {
+		return
+	}
+
+	await checkResponse(rest, url)
+}

package/src/api/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Control-plane client types — mirror of the harness's
+ * kimchi-dev:src/sandbox/cloud types (trimmed to what kimchictl v1 needs).
+ */
+
+export class RemoteAuthError extends Error {
+	constructor(
+		message: string,
+		public readonly statusCode: number,
+	) {
+		super(message)
+		this.name = "RemoteAuthError"
+	}
+}
+
+export class RemoteNetworkError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = "RemoteNetworkError"
+	}
+}
+
+/**
+ * Thrown when the control plane rejects a request because the user's
+ * resource quota is exhausted (HTTP 429 with a quota body). The message is
+ * already user-facing — surface verbatim.
+ */
+export class RemoteQuotaError extends RemoteNetworkError {
+	constructor(
+		message: string,
+		public readonly statusCode: number,
+	) {
+		super(message)
+		this.name = "RemoteQuotaError"
+	}
+}
+
+export interface ApiOptions {
+	/**
+	 * Override the cloud API endpoint. Resolution order:
+	 *   1. this option
+	 *   2. KIMCHI_REMOTE_ENDPOINT env var
+	 *   3. production default https://app.kimchi.dev/api
+	 */
+	endpoint?: string
+	/** Override global fetch (tests). */
+	fetch?: typeof globalThis.fetch
+	/** External abort signal. */
+	signal?: AbortSignal
+}

package/src/api/wait.ts

@@ -0,0 +1,45 @@
+import type { ApiOptions } from "./types.js"
+import { RemoteAuthError } from "./types.js"
+import { getWorkspace, type Workspace } from "./workspaces.js"
+
+/**
+ * Poll getWorkspace until the workspace is ACTIVE or the deadline passes.
+ * Shared by `workspace create` (post-create wait) and `ssh` (post-resume
+ * wait) — kap's 2s cadence, deadline-based, progress via onTick.
+ *
+ * Transient get failures (the workspace is still registering with the
+ * control plane) are tolerated until the deadline; auth failures abort.
+ */
+export async function waitForWorkspaceActive(
+	apiKey: string,
+	id: string,
+	options: ApiOptions & {
+		timeoutMs: number
+		pollMs?: number
+		sleep?: (ms: number) => Promise<void>
+		onTick?: (elapsedSeconds: number) => void
+	},
+): Promise<Workspace> {
+	const pollMs = options.pollMs ?? 2000
+	const sleep = options.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)))
+
+	const start = Date.now()
+	const deadline = start + options.timeoutMs
+	let current: Workspace | undefined
+	while (Date.now() < deadline) {
+		await sleep(pollMs)
+		options.onTick?.(Math.round((Date.now() - start) / 1000))
+		try {
+			current = await getWorkspace(apiKey, id, options)
+		} catch (err) {
+			if (err instanceof RemoteAuthError) throw err
+			continue
+		}
+		if (current.status === "active") break
+	}
+	if (!current) {
+		// Every poll failed; fetch once without tolerance so the real error surfaces.
+		current = await getWorkspace(apiKey, id, options)
+	}
+	return current
+}