@kimchi-dev/kimchictl 0.0.6 → 0.0.8

package/src/commands/workspace.ts

@@ -1,8 +1,22 @@
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
 import { resolveWorkspace } from "../api/resolver.js"
 import { formatAge, formatBytes, formatMillicores } from "../api/resources.js"
-import { resolveTemplate } from "../api/templates.js"
+import {
+	AmbiguousTemplateError,
+	getWorkspaceTemplate,
+	listWorkspaceTemplates,
+	TemplateNotFoundError,
+	type WorkspaceTemplate,
+} from "../api/templates.js"
 import { waitForWorkspaceActive } from "../api/wait.js"
-import { createWorkspace, deleteWorkspace, listWorkspaces, type Workspace } from "../api/workspaces.js"
+import {
+	type CreateWorkspaceSpec,
+	createWorkspace,
+	deleteWorkspace,
+	listWorkspaces,
+	type Workspace,
+} from "../api/workspaces.js"
 import { requireApiKey } from "../auth/resolve.js"
 import { resolveSshDomain } from "../ssh/config.js"
 import { parseFlags, UsageError } from "./flags.js"
@@ -29,10 +43,26 @@ 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)
+  create     Create a workspace (server generates the alias)
+  list       List workspaces  (alias: ls)
+  get        Show workspace details
+  delete     Delete a workspace  (alias: rm)
+  templates  Browse workspace templates (list | get)
+
+Create options:
+  --desc <text>              Description
+  --template <name>          Workspace template (conflicts with spec flags)
+  --template-id <uuid>       Template ID (alternative to --template)
+  --cpu <qty>               CPU request (e.g. "500m", "2")
+  --memory <qty>             Memory request (e.g. "1Gi", "512Mi")
+  --storage <qty>            PVC size (e.g. "20Gi")
+  --dep <tool>               CLI tool to install (repeatable, e.g. --dep jq --dep node@22)
+  --egress-allow <dest>      Allow egress destination (repeatable)
+  --egress-deny <dest>       Deny egress destination (repeatable)
+  --egress-default-allow     Default-allow egress (instead of deny-by-default)
+  --init-script <script>     Boot script (or @file to read from file)
+  --no-wait                  Skip waiting for ACTIVE
+  --timeout <seconds>        Wait timeout (default 60)
 
 Options:
   --help   Show this help`
@@ -51,6 +81,9 @@ export async function runWorkspace(args: string[], deps: WorkspaceDeps = {}): Pr
 		case "delete":
 		case "rm":
 			return runDelete(rest, deps)
+		case "templates":
+		case "template":
+			return runTemplates(rest, deps)
 		case "help":
 		case "--help":
 		case "-h":
@@ -70,6 +103,15 @@ async function runCreate(args: string[], deps: WorkspaceDeps): Promise<number> {
 	const { values, positionals } = parseFlags("workspace create", args, {
 		desc: { type: "string" },
 		template: { type: "string", short: "t" },
+		"template-id": { type: "string" },
+		cpu: { type: "string" },
+		memory: { type: "string" },
+		storage: { type: "string" },
+		dep: { type: "string", multiple: true },
+		"egress-allow": { type: "string", multiple: true },
+		"egress-deny": { type: "string", multiple: true },
+		"egress-default-allow": { type: "boolean" },
+		"init-script": { type: "string" },
 		"no-wait": { type: "boolean" },
 		timeout: { type: "string", default: "60" },
 	})
@@ -79,22 +121,92 @@ async function runCreate(args: string[], deps: WorkspaceDeps): Promise<number> {
 		)
 	}
 
-	const template = values.template
-	if (typeof template === "string" && template.length > 0) {
-		// Placeholder: errors gracefully until the templates API contract lands.
-		resolveTemplate(template)
+	const timeoutSeconds = parseTimeoutSeconds(values.timeout, "workspace create")
+	const desc = typeof values.desc === "string" && values.desc.length > 0 ? values.desc : undefined
+
+	const templateName = typeof values.template === "string" && values.template.length > 0 ? values.template : undefined
+	const templateId =
+		typeof values["template-id"] === "string" && values["template-id"].length > 0 ? values["template-id"] : undefined
+
+	// Collect explicit spec parameters from the flags.
+	const resources: { cpu?: string; memory?: string; pvcSize?: string } = {}
+	if (typeof values.cpu === "string" && values.cpu.length > 0) resources.cpu = values.cpu
+	if (typeof values.memory === "string" && values.memory.length > 0) resources.memory = values.memory
+	if (typeof values.storage === "string" && values.storage.length > 0) resources.pvcSize = values.storage
+
+	const dependencies = (Array.isArray(values.dep) ? values.dep : []).filter(
+		(d): d is string => typeof d === "string" && d.length > 0,
+	)
+	const egressAllowed = (Array.isArray(values["egress-allow"]) ? values["egress-allow"] : []).filter(
+		(d): d is string => typeof d === "string" && d.length > 0,
+	)
+	const egressDenied = (Array.isArray(values["egress-deny"]) ? values["egress-deny"] : []).filter(
+		(d): d is string => typeof d === "string" && d.length > 0,
+	)
+	const egressDefaultAllow = values["egress-default-allow"] === true
+	const initScriptRaw = typeof values["init-script"] === "string" ? values["init-script"] : undefined
+
+	// @file syntax for --init-script: read the script from a file.
+	let initScript: string | undefined
+	if (initScriptRaw) {
+		if (initScriptRaw.startsWith("@")) {
+			const filePath = initScriptRaw.slice(1)
+			try {
+				initScript = readFileSync(resolve(filePath), "utf-8")
+			} catch {
+				throw new UsageError(`kimchictl workspace create: --init-script: cannot read ${filePath}`)
+			}
+		} else {
+			initScript = initScriptRaw
+		}
 	}
-	if (values.template !== undefined && (typeof values.template !== "string" || values.template.length === 0)) {
-		throw new UsageError("kimchictl workspace create: --template must not be empty")
+
+	const hasSpec =
+		Object.keys(resources).length > 0 ||
+		dependencies.length > 0 ||
+		egressAllowed.length > 0 ||
+		egressDenied.length > 0 ||
+		egressDefaultAllow ||
+		initScript !== undefined
+
+	// Mutual exclusion: template fields and spec parameters cannot coexist
+	// (the API rejects both — proto: "conflicts with spec").
+	if ((templateName || templateId) && hasSpec) {
+		throw new UsageError(
+			"kimchictl workspace create: --template and spec flags (--cpu, --memory, --storage, --dep, --egress-*, --init-script) are mutually exclusive — a template provides these values",
+		)
+	}
+	if (templateName && templateId) {
+		throw new UsageError("kimchictl workspace create: --template and --template-id are mutually exclusive")
 	}
 
-	const timeoutSeconds = parseTimeoutSeconds(values.timeout, "workspace create")
-	const desc = typeof values.desc === "string" && values.desc.length > 0 ? values.desc : undefined
+	const spec: CreateWorkspaceSpec | undefined = hasSpec
+		? {
+				...(Object.keys(resources).length > 0 ? { resources } : {}),
+				...(dependencies.length > 0 ? { dependencies } : {}),
+				...(egressAllowed.length > 0 || egressDenied.length > 0 || egressDefaultAllow
+					? {
+							egressPolicy: {
+								...(egressDefaultAllow ? { denyByDefault: false } : {}),
+								...(egressAllowed.length > 0 ? { allowed: egressAllowed } : {}),
+								...(egressDenied.length > 0 ? { denied: egressDenied } : {}),
+							},
+						}
+					: {}),
+				...(initScript !== undefined ? { initScript } : {}),
+			}
+		: 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 })
+	const created = await createWorkspace(key, {
+		description: desc,
+		templateName,
+		templateId,
+		spec,
+		fetch: deps.fetch,
+	})
 	// Success-path info goes to stdout (terminals that color stderr red made
 	// this look like an error); only warnings and the transient progress
 	// spinner stay on stderr.
@@ -237,6 +349,184 @@ async function runDelete(args: string[], deps: WorkspaceDeps): Promise<number> {
 	return 0
 }
 
+// ---------------------------------------------------------------- templates
+
+async function runTemplates(args: string[], deps: WorkspaceDeps): Promise<number> {
+	const [verb, ...rest] = args
+	switch (verb) {
+		case "list":
+		case "ls":
+			return runTemplatesList(rest, deps)
+		case "get":
+			return runTemplatesGet(rest, deps)
+		case "help":
+		case "--help":
+		case "-h":
+			console.log(TEMPLATES_USAGE)
+			return 0
+		case undefined:
+			console.error(TEMPLATES_USAGE)
+			return 2
+		default:
+			console.error(`kimchictl workspace templates: unknown verb "${verb}"`)
+			console.error(TEMPLATES_USAGE)
+			return 2
+	}
+}
+
+const TEMPLATES_USAGE = `Usage:
+  kimchictl workspace templates <verb> [options]
+
+Verbs:
+  list   List workspace templates  (alias: ls)
+  get    Show template details
+
+Options:
+  --help   Show this help`
+
+async function runTemplatesList(args: string[], deps: WorkspaceDeps): Promise<number> {
+	const { values, positionals } = parseFlags("workspace templates list", args, {
+		output: { type: "string", short: "o", default: "table" },
+	})
+	if (positionals.length > 0) {
+		throw new UsageError("kimchictl workspace templates list: unexpected positional argument")
+	}
+	if (values.output !== "json" && values.output !== "table") {
+		throw new UsageError(
+			`kimchictl workspace templates list: unsupported --output "${String(values.output)}" (expected table|json)`,
+		)
+	}
+
+	const { key } = requireApiKey(deps.env)
+	const templates = await listWorkspaceTemplates(key, { fetch: deps.fetch })
+
+	if (values.output === "json") {
+		console.log(JSON.stringify(templates.map(serializeTemplate), null, 2))
+		return 0
+	}
+
+	const now = deps.now?.() ?? new Date()
+	const rows = templates.map((t) => [
+		t.name || t.id.slice(0, 12),
+		t.description.length > 40 ? `${t.description.slice(0, 37)}…` : t.description || "-",
+		formatMillicores(t.spec?.resources?.cpu ? parseQuantity(t.spec.resources.cpu) : undefined),
+		formatBytes(t.spec?.resources?.memory ? parseByteQuantity(t.spec.resources.memory) : undefined),
+		formatBytes(t.spec?.resources?.pvcSize ? parseByteQuantity(t.spec.resources.pvcSize) : undefined),
+		formatAge(t.createTime, now),
+	])
+	console.log(formatTable(["NAME", "DESCRIPTION", "CPU", "MEMORY", "STORAGE", "AGE"], rows))
+	return 0
+}
+
+async function runTemplatesGet(args: string[], deps: WorkspaceDeps): Promise<number> {
+	const { values, positionals } = parseFlags("workspace templates get", args, {
+		output: { type: "string", short: "o", default: "text" },
+	})
+	if (positionals.length !== 1) {
+		throw new UsageError("kimchictl workspace templates get: expected exactly one template name or ID")
+	}
+	if (values.output !== "json" && values.output !== "text") {
+		throw new UsageError(
+			`kimchictl workspace templates get: unsupported --output "${String(values.output)}" (expected text|json)`,
+		)
+	}
+
+	const { key } = requireApiKey(deps.env)
+	const ref = positionals[0] ?? ""
+
+	// Templates are addressed by ID in the API; when the ref is a name,
+	// list-and-match (the API has no by-name lookup).
+	let template: WorkspaceTemplate | undefined
+	if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(ref)) {
+		template = await getWorkspaceTemplate(key, ref, { fetch: deps.fetch })
+	} else {
+		const all = await listWorkspaceTemplates(key, { fetch: deps.fetch })
+		const matches = all.filter((t) => t.name === ref || t.name.startsWith(ref))
+		if (matches.length === 0) throw new TemplateNotFoundError(ref)
+		if (matches.length > 1)
+			throw new AmbiguousTemplateError(
+				ref,
+				matches.map((t) => t.name),
+			)
+		template = matches[0]
+	}
+	if (!template) throw new TemplateNotFoundError(ref)
+
+	if (values.output === "json") {
+		console.log(JSON.stringify(serializeTemplate(template), null, 2))
+		return 0
+	}
+
+	for (const line of renderTemplateCard(template, deps.color ?? false, deps.now?.() ?? new Date())) {
+		console.log(line)
+	}
+	return 0
+}
+
+function renderTemplateCard(template: WorkspaceTemplate, color: boolean, now: Date): string[] {
+	const lines: string[] = [`${template.name || template.id.slice(0, 12)}  ${dim("template", color)}`]
+	if (template.description) lines.push(dim(`  ${template.description}`, color))
+
+	const parts: string[] = []
+	const res = template.spec?.resources
+	if (res) {
+		if (res.cpu) parts.push(formatMillicores(parseQuantity(res.cpu)))
+		if (res.memory) parts.push(formatBytes(parseByteQuantity(res.memory)))
+	}
+	if (parts.length > 0) {
+		lines.push(dim(`  ${parts.join(" · ")}`, color))
+	}
+
+	const deps = template.spec?.dependencies
+	if (deps && deps.length > 0) {
+		lines.push(`  deps  ${deps.join(", ")}`)
+	}
+
+	const eg = template.spec?.egressPolicy
+	if (eg) {
+		const egParts: string[] = []
+		if (eg.denyByDefault === false) egParts.push("default-allow")
+		if (eg.allowed && eg.allowed.length > 0) egParts.push(`allow: ${eg.allowed.join(", ")}`)
+		if (eg.denied && eg.denied.length > 0) egParts.push(`deny: ${eg.denied.join(", ")}`)
+		if (egParts.length > 0) lines.push(dim(`  egress  ${egParts.join(" · ")}`, color))
+	}
+
+	lines.push(dim(`  updated ${formatAge(template.updateTime, now)} ago`, color))
+	return lines
+}
+
+function serializeTemplate(t: WorkspaceTemplate): Record<string, unknown> {
+	return {
+		id: t.id,
+		name: t.name,
+		...(t.description ? { description: t.description } : {}),
+		spec: t.spec,
+		...(t.createdBy ? { createdBy: t.createdBy } : {}),
+		...(t.updateTime.getTime() > 0 ? { updateTime: t.updateTime.toISOString() } : {}),
+	}
+}
+
+/** Parse a k8s CPU quantity string ("500m", "2") to millicores. */
+function parseQuantity(q: string): number | undefined {
+	const value = Number.parseFloat(q.replace(/m$/, ""))
+	if (Number.isNaN(value)) return undefined
+	return q.endsWith("m") ? value : value * 1000
+}
+
+/** Parse a k8s memory/storage quantity string ("1Gi", "512Mi") to bytes. */
+function parseByteQuantity(q: string): number | undefined {
+	const units: Record<string, number> = { Ki: 1024, Mi: 1024 ** 2, Gi: 1024 ** 3, Ti: 1024 ** 4 }
+	for (const [suffix, mult] of Object.entries(units)) {
+		if (q.endsWith(suffix)) {
+			const value = Number.parseFloat(q.slice(0, -suffix.length))
+			if (!Number.isNaN(value)) return value * mult
+		}
+	}
+	const value = Number.parseFloat(q)
+	if (!Number.isNaN(value)) return value
+	return undefined
+}
+
 // ---------------------------------------------------------------- shared
 
 /** Tinted status dot: green=active, yellow=transitional/suspended, dim=terminated. */

package/src/version.ts

@@ -3,4 +3,4 @@
  * version over this constant at build time; the committed value stays a
  * sentinel so source checkouts are recognizable.
  */
-export const VERSION = "0.0.6"
+export const VERSION = "0.0.8"