@kimchi-dev/kimchictl 0.0.6 → 0.0.8

package/src/api/workspaces.ts

@@ -121,29 +121,89 @@ export async function getWorkspace(apiKey: string, id: string, options?: Workspa
 	return mapWorkspace(data, endpoint)
 }
 
+/**
+ * Create-time workspace parameters (mirrors the WorkspaceSpec proto).
+ * Set either template fields or spec fields — never both.
+ */
+export interface CreateWorkspaceSpec {
+	resources?: {
+		/** CPU request as a k8s quantity string, e.g. "500m", "2". */
+		cpu?: string
+		/** Memory request as a k8s quantity string, e.g. "1Gi", "512Mi". */
+		memory?: string
+		/** PVC size as a k8s quantity string, e.g. "20Gi". */
+		pvcSize?: string
+	}
+	/** CLI tools to install at boot, e.g. ["jq", "node@22"]. */
+	dependencies?: string[]
+	egressPolicy?: {
+		denyByDefault?: boolean
+		allowed?: string[]
+		denied?: string[]
+	}
+	/** Shell script executed at boot after dependency installation. */
+	initScript?: string
+}
+
+export interface CreateWorkspaceOptions extends WorkspaceCommandOptions {
+	description?: string
+	templateName?: string
+	templateId?: string
+	spec?: CreateWorkspaceSpec
+}
+
 /**
  * Create a workspace. Server generates the alias (like kap) — there is no
- * client-side name input. Returns the created workspace (status likely
- * "initializing"; callers may poll getWorkspace until "active").
+ * client-side name input. Set either template fields (templateName or
+ * templateId) or explicit spec parameters, never both (the API rejects
+ * both — proto: "conflicts with spec: set either template fields or
+ * explicit parameters, never both"). Returns the created workspace
+ * (status likely "initializing"; callers may poll getWorkspace until
+ * "active").
  */
-export async function createWorkspace(
-	apiKey: string,
-	options: WorkspaceCommandOptions & { description?: string },
-): Promise<Workspace> {
+export async function createWorkspace(apiKey: string, options: CreateWorkspaceOptions): Promise<Workspace> {
 	const fetchImpl = options?.fetch ?? globalThis.fetch
 	const endpoint = resolveEndpoint(options)
 	const orgId = await resolveOrgId(apiKey, options)
 
+	// Build the request body — the Workspace message (gRPC-gateway body: "workspace").
+	// gRPC-gateway maps proto field names to camelCase JSON keys.
+	const body: Record<string, unknown> = {
+		clientType: HARNESS_CLIENT_TYPE,
+	}
+	if (options.description) body.description = options.description
+	if (options.templateName) body.templateName = options.templateName
+	if (options.templateId) body.templateId = options.templateId
+
+	const spec = options.spec
+	if (spec) {
+		const specBody: Record<string, unknown> = {}
+		if (spec.resources) {
+			const res: Record<string, string> = {}
+			if (spec.resources.cpu) res.cpu = spec.resources.cpu
+			if (spec.resources.memory) res.memory = spec.resources.memory
+			if (spec.resources.pvcSize) res.pvcSize = spec.resources.pvcSize
+			if (Object.keys(res).length > 0) specBody.resources = res
+		}
+		if (spec.dependencies && spec.dependencies.length > 0) specBody.dependencies = spec.dependencies
+		if (spec.egressPolicy) {
+			const eg: Record<string, unknown> = {}
+			if (spec.egressPolicy.denyByDefault !== undefined) eg.denyByDefault = spec.egressPolicy.denyByDefault
+			if (spec.egressPolicy.allowed && spec.egressPolicy.allowed.length > 0) eg.allowed = spec.egressPolicy.allowed
+			if (spec.egressPolicy.denied && spec.egressPolicy.denied.length > 0) eg.denied = spec.egressPolicy.denied
+			if (Object.keys(eg).length > 0) specBody.egressPolicy = eg
+		}
+		if (spec.initScript) specBody.initScript = spec.initScript
+		if (Object.keys(specBody).length > 0) body.spec = specBody
+	}
+
 	const url = `${endpoint}/ai-optimizer/v1beta/organizations/${encodeURIComponent(orgId)}/workspaces`
 	const resp = await fetchWithTimeout(
 		url,
 		{
 			method: "POST",
 			headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
-			body: JSON.stringify({
-				...(options.description ? { description: options.description } : {}),
-				clientType: HARNESS_CLIENT_TYPE,
-			}),
+			body: JSON.stringify(body),
 		},
 		fetchImpl,
 		30_000,

package/src/commands/flags.ts

@@ -8,7 +8,7 @@ export class UsageError extends Error {
 	}
 }
 
-export type FlagValues = Record<string, string | boolean | undefined>
+export type FlagValues = Record<string, string | boolean | string[] | boolean[] | undefined>
 
 /**
  * Strict flag parsing with a uniform usage-error shape across commands.

package/src/commands/guard.ts

@@ -1,5 +1,5 @@
 import { AmbiguousWorkspaceError, WorkspaceNotFoundError } from "../api/resolver.js"
-import { TemplatesUnavailableError } from "../api/templates.js"
+import { AmbiguousTemplateError, TemplateNotFoundError } from "../api/templates.js"
 import { RemoteAuthError, RemoteNetworkError } from "../api/types.js"
 import { ModelsFetchError } from "../auth/models-providers.js"
 import { NotLoggedInError } from "../auth/resolve.js"
@@ -28,9 +28,10 @@ export function guardCommand<TDeps>(
 			if (
 				err instanceof NotLoggedInError ||
 				err instanceof ModelsFetchError ||
-				err instanceof TemplatesUnavailableError ||
 				err instanceof WorkspaceNotFoundError ||
 				err instanceof AmbiguousWorkspaceError ||
+				err instanceof TemplateNotFoundError ||
+				err instanceof AmbiguousTemplateError ||
 				err instanceof BridgeError ||
 				err instanceof RemoteAuthError ||
 				err instanceof RemoteNetworkError

package/src/commands/workspace.test.ts

@@ -198,11 +198,88 @@ describe("kimchictl workspace create", () => {
 		expect(lines[lines.length - 1]).toBe("bright-oak-otter")
 	})
 
-	it("--template errors gracefully until the templates API lands", async () => {
-		const { code, errors } = await run(["create", "--template", "node"], apiFetch([]))
+	it("--template conflicts with spec flags (usage error)", async () => {
+		for (const specFlag of [
+			["--cpu", "2"],
+			["--memory", "4Gi"],
+			["--storage", "20Gi"],
+			["--dep", "jq"],
+			["--egress-allow", "*.example.com"],
+			["--init-script", "echo hi"],
+		]) {
+			const { code, errors } = await run(["create", "--template", "node", ...specFlag], apiFetch([]))
+			expect(code).toBe(2)
+			expect(errors.some((e) => e.includes("mutually exclusive"))).toBe(true)
+		}
+	})
 
-		expect(code).toBe(1)
-		expect(errors[0]).toContain('templates are not available yet (requested "node")')
+	it("--template and --template-id conflict (usage error)", async () => {
+		const { code, errors } = await run(
+			["create", "--template", "node", "--template-id", "11111111-2222-3333-4444-555555555555"],
+			apiFetch([]),
+		)
+		expect(code).toBe(2)
+		expect(errors.some((e) => e.includes("--template and --template-id"))).toBe(true)
+	})
+
+	it("sends templateName to the API", async () => {
+		const calls: { body?: unknown }[] = []
+		const rawFetch = stubFetch(async (url, init) => {
+			if (url.endsWith("workspace-tokens:verifyKey")) return jsonResponse({ organizationId: "org-1" })
+			if (url.endsWith("/workspaces") && init?.method === "POST") {
+				calls.push({ body: JSON.parse(String(init.body)) })
+				return jsonResponse(wsJson({ status: "ACTIVE" }))
+			}
+			throw new Error(`unexpected: ${init?.method ?? "GET"} ${url}`)
+		})
+
+		await run(["create", "--template", "rust", "--no-wait"], rawFetch as typeof globalThis.fetch)
+
+		expect(calls[0]?.body).toMatchObject({
+			templateName: "rust",
+			clientType: "harness",
+		})
+	})
+
+	it("sends spec fields to the API", async () => {
+		const calls: { body?: unknown }[] = []
+		const rawFetch = stubFetch(async (url, init) => {
+			if (url.endsWith("workspace-tokens:verifyKey")) return jsonResponse({ organizationId: "org-1" })
+			if (url.endsWith("/workspaces") && init?.method === "POST") {
+				calls.push({ body: JSON.parse(String(init.body)) })
+				return jsonResponse(wsJson({ status: "ACTIVE" }))
+			}
+			throw new Error(`unexpected: ${init?.method ?? "GET"} ${url}`)
+		})
+
+		await run(
+			[
+				"create",
+				"--cpu",
+				"500m",
+				"--memory",
+				"2Gi",
+				"--storage",
+				"10Gi",
+				"--dep",
+				"jq",
+				"--dep",
+				"node@22",
+				"--egress-allow",
+				"*.example.com",
+				"--egress-default-allow",
+				"--no-wait",
+			],
+			rawFetch as typeof globalThis.fetch,
+		)
+
+		expect(calls[0]?.body).toMatchObject({
+			spec: {
+				resources: { cpu: "500m", memory: "2Gi", pvcSize: "10Gi" },
+				dependencies: ["jq", "node@22"],
+				egressPolicy: { denyByDefault: false, allowed: ["*.example.com"] },
+			},
+		})
 	})
 
 	it("rejects positional arguments and bad timeouts as usage errors", async () => {
@@ -352,6 +429,99 @@ describe("kimchictl workspace get", () => {
 
 // ---------------------------------------------------------------- delete
 
+describe("kimchictl workspace templates", () => {
+	const TEMPLATE_JSON = {
+		id: "aaaa1111-2222-3333-4444-555555555555",
+		organizationId: "org-1",
+		name: "rust",
+		description: "Rust workspace",
+		spec: {
+			resources: { cpu: "2", memory: "4Gi", pvcSize: "20Gi" },
+			dependencies: ["jq", "node@22"],
+			egressPolicy: { denyByDefault: true, allowed: ["*.github.com"] },
+			initScript: "echo hi",
+		},
+		createdBy: "user-1",
+		updatedBy: "user-1",
+		createTime: "2026-01-01T00:00:00Z",
+		updateTime: "2026-01-01T00:00:00Z",
+	}
+
+	function templateFetch(items: unknown[]): typeof globalThis.fetch {
+		return stubFetch(async (url, init) => {
+			if (init?.method === "POST" || (init?.method ?? "GET") === "POST") {
+				if (url.endsWith("workspace-tokens:verifyKey")) return jsonResponse({ organizationId: "org-1" })
+			}
+			if (url.endsWith("workspace-tokens:verifyKey")) return jsonResponse({ organizationId: "org-1" })
+			if (url.includes("workspace-templates?")) return jsonResponse({ items })
+			if (url.endsWith("/workspace-templates/aaaa1111-2222-3333-4444-555555555555")) {
+				return jsonResponse(items[0])
+			}
+			throw new Error(`unexpected: ${init?.method ?? "GET"} ${url}`)
+		}) as typeof globalThis.fetch
+	}
+
+	it("prints group usage on help / missing verb", async () => {
+		const { code, lines } = await run(["templates", "help"], templateFetch([]))
+		expect(code).toBe(0)
+		expect(lines[0]).toContain("kimchictl workspace templates <verb>")
+	})
+
+	it("renders the template table", async () => {
+		const { code, lines } = await run(["templates", "list"], templateFetch([TEMPLATE_JSON]), {
+			now: () => new Date("2026-01-01T03:00:00Z"),
+		})
+		expect(code).toBe(0)
+		const table = lines[0]?.split("\n") ?? []
+		expect(table[0]).toMatch(/^NAME\s+DESCRIPTION\s+CPU\s+MEMORY\s+STORAGE\s+AGE$/)
+		expect(table[1]).toMatch(/^rust\s+Rust workspace\s+2\s+4Gi\s+20Gi\s+3h$/)
+	})
+
+	it("renders json output", async () => {
+		const { code, lines } = await run(["templates", "list", "--output", "json"], templateFetch([TEMPLATE_JSON]))
+		expect(code).toBe(0)
+		const parsed = JSON.parse(lines.join(""))
+		expect(parsed[0]).toMatchObject({ name: "rust", description: "Rust workspace" })
+	})
+
+	it("renders the template detail card by name", async () => {
+		const { code, lines } = await run(["templates", "get", "rust"], templateFetch([TEMPLATE_JSON]), {
+			now: () => new Date("2026-01-01T03:00:00Z"),
+		})
+		expect(code).toBe(0)
+		const text = lines.join("\n")
+		expect(text).toContain("rust  template")
+		expect(text).toContain("Rust workspace")
+		expect(text).toContain("deps  jq, node@22")
+		expect(text).toContain("egress  allow: *.github.com")
+	})
+
+	it("resolves by UUID without listing", async () => {
+		const fetch = templateFetch([TEMPLATE_JSON])
+		const calls: string[] = []
+		const trackedFetch = stubFetch(async (url, init) => {
+			calls.push(url)
+			return fetch(url, init)
+		}) as typeof globalThis.fetch
+
+		const { code } = await run(["templates", "get", "aaaa1111-2222-3333-4444-555555555555"], trackedFetch)
+		expect(code).toBe(0)
+		// No list call — the UUID went straight to GET
+		expect(calls.some((u) => u.includes("workspace-templates?"))).toBe(false)
+	})
+
+	it("errors on unknown template", async () => {
+		const { code, errors } = await run(["templates", "get", "nope"], templateFetch([]))
+		expect(code).toBe(1)
+		expect(errors[0]).toContain('No workspace template matches "nope"')
+	})
+
+	it("rejects unknown verbs and bad output", async () => {
+		expect((await run(["templates", "frobnicate"], templateFetch([]))).code).toBe(2)
+		expect((await run(["templates", "list", "--output", "yaml"], templateFetch([]))).code).toBe(2)
+	})
+})
+
 describe("kimchictl workspace delete", () => {
 	it("deletes after an affirmative confirmation", async () => {
 		const fetch = apiFetch([