@kimchi-dev/kimchictl 0.0.2

package/dist/test-support.js

@@ -0,0 +1,67 @@
+/**
+ * Shared test helpers — co-located *.test.ts files import from here instead of
+ * re-rolling temp-dir / fetch-stub / console-capture boilerplate per file.
+ * Excluded from the published build (tsconfig.build.json).
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { vi } from "vitest";
+const tempDirs = [];
+export function makeTempDir(prefix = "kimchictl-test-") {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+/** Call from afterEach — removes every dir created via makeTempDir. */
+export function cleanupTempDirs() {
+    for (const dir of tempDirs.splice(0))
+        rmSync(dir, { recursive: true, force: true });
+}
+/**
+ * Build a fetch stub from a narrow implementation. The `as unknown` adapts the
+ * test's string-URL signature to fetch's wide `(string | URL | Request)` one —
+ * deliberate, one place, test-only.
+ */
+export function stubFetch(impl) {
+    return impl;
+}
+export function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+/** Point the shared-credential paths at an isolated HOME + agent dir and neutralize ambient key env vars. Returns the stubbed HOME — the shared config.json lives at `<home>/.config/kimchi/config.json` (sibling of the harness agent dir, matching kimchi-dev:src/config.ts). */
+export function stubAgentDirEnv(dir) {
+    const home = makeTempDir();
+    vi.stubEnv("HOME", home);
+    vi.stubEnv("KIMCHI_CODING_AGENT_DIR", dir);
+    // resolveApiKey treats an empty KIMCHI_API_KEY as absent.
+    vi.stubEnv("KIMCHI_API_KEY", "");
+    return { home };
+}
+/** Path of the harness's shared wizard config under a (stubbed) HOME. */
+export function sharedConfigPath(home) {
+    return join(home, ".config", "kimchi", "config.json");
+}
+/** Seed the shared config.json under a stubbed HOME (creates parent dirs). */
+export function writeSharedConfigJson(home, value) {
+    const configPath = sharedConfigPath(home);
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, JSON.stringify(value, null, 2));
+    return configPath;
+}
+/** Capture console.log / console.error; restore() in afterEach (or rely on vi.restoreAllMocks). */
+export function captureConsole() {
+    const lines = [];
+    const errors = [];
+    vi.spyOn(console, "log").mockImplementation((...args) => {
+        lines.push(args.map(String).join(" "));
+    });
+    vi.spyOn(console, "error").mockImplementation((...args) => {
+        errors.push(args.map(String).join(" "));
+    });
+    return { lines, errors };
+}
+//# sourceMappingURL=test-support.js.map

package/dist/test-support.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-support.js","sourceRoot":"../src/","sources":["test-support.ts"],"names":[],"mappings":"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"}

package/dist/updates/check.d.ts

@@ -0,0 +1,18 @@
+/** Semantic-ish comparison: 0.10.0 > 0.9.9. Only digits matter; pre-releases compare numerically too. */
+export declare function isNewer(latest: string, current: string): boolean;
+export interface UpdateCheckResult {
+    latest: string;
+    current: string;
+}
+export interface CheckForUpdateOptions {
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof globalThis.fetch;
+    now?: () => Date;
+    /** Version to compare against — tests inject; defaults to the baked-in VERSION. */
+    currentVersion?: string;
+}
+/** Returns {latest, current} when a newer release exists, otherwise undefined. Never throws. */
+export declare function checkForUpdate(options?: CheckForUpdateOptions): Promise<UpdateCheckResult | undefined>;
+/** Post the update hint to stderr. Extracted so cli.ts stays a one-liner. */
+export declare function maybeNotifyUpdate(options?: CheckForUpdateOptions): Promise<void>;
+//# sourceMappingURL=check.d.ts.map

package/dist/updates/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"../src/","sources":["updates/check.ts"],"names":[],"mappings":"AAuBA,yGAAyG;AACzG,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAahE;AAED,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CACf;AAqBD,MAAM,WAAW,qBAAqB;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IAChB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,gGAAgG;AAChG,wBAAsB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAoChH;AAED,6EAA6E;AAC7E,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAK1F"}

package/dist/updates/check.js

@@ -0,0 +1,90 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fetchWithTimeout } from "../api/http.js";
+import { resolveSshPaths } from "../ssh/config.js";
+import { VERSION } from "../version.js";
+/**
+ * Daily background update check against the GitHub Releases API.
+ *
+ * The check must never block or fail a real command: every failure mode
+ * resolves to "no notification". Results cache in
+ * ~/.config/kimchi/kimchictl/update-check.json for 24h.
+ */
+const LATEST_RELEASE_URL = "https://api.github.com/repos/getkimchi/kimchictl/releases/latest";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 2500;
+/** Semantic-ish comparison: 0.10.0 > 0.9.9. Only digits matter; pre-releases compare numerically too. */
+export function isNewer(latest, current) {
+    const parse = (v) => v
+        .replace(/^v/, "")
+        .split(".")
+        .map((part) => Number.parseInt(part, 10) || 0);
+    const a = parse(latest);
+    const b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        if (diff !== 0)
+            return diff > 0;
+    }
+    return false;
+}
+async function readCache(path) {
+    try {
+        const raw = JSON.parse(await readFile(path, "utf-8"));
+        if (typeof raw.latestVersion === "string" && typeof raw.checkedAt === "string") {
+            return { latestVersion: raw.latestVersion, checkedAt: raw.checkedAt };
+        }
+        return undefined;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        return undefined; // corrupt cache → treat as stale (refetched below)
+    }
+}
+async function writeCache(path, cache) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(cache, null, 2)}\n`, { mode: 0o600 });
+    await chmod(path, 0o600);
+}
+/** Returns {latest, current} when a newer release exists, otherwise undefined. Never throws. */
+export async function checkForUpdate(options = {}) {
+    try {
+        const current = options.currentVersion ?? VERSION;
+        // Source checkouts and dev builds are not versioned against releases.
+        if (current.endsWith("-dev"))
+            return undefined;
+        const env = options.env ?? process.env;
+        if (env.KIMCHICTL_NO_UPDATE_CHECK)
+            return undefined;
+        const now = options.now ?? (() => new Date());
+        const cachePath = join(resolveSshPaths(env).home, "update-check.json");
+        const cached = await readCache(cachePath);
+        if (cached && now().getTime() - new Date(cached.checkedAt).getTime() < CHECK_INTERVAL_MS) {
+            return isNewer(cached.latestVersion, current) ? { latest: cached.latestVersion, current } : undefined;
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        const resp = await fetchWithTimeout(LATEST_RELEASE_URL, { headers: { "User-Agent": `kimchictl/${current}` } }, fetchImpl, FETCH_TIMEOUT_MS);
+        if (!resp.ok)
+            return undefined;
+        const data = (await resp.json());
+        if (typeof data.tag_name !== "string")
+            return undefined;
+        const latest = data.tag_name.replace(/^v/, "");
+        await writeCache(cachePath, { latestVersion: latest, checkedAt: now().toISOString() }).catch(() => {
+            // Cache writes are best-effort only.
+        });
+        return isNewer(latest, current) ? { latest, current } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Post the update hint to stderr. Extracted so cli.ts stays a one-liner. */
+export async function maybeNotifyUpdate(options = {}) {
+    const result = await checkForUpdate(options);
+    if (result) {
+        console.error(`⬆ kimchictl ${result.latest} available (current ${result.current}) — update: kimchictl update`);
+    }
+}
+//# sourceMappingURL=check.js.map

package/dist/updates/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"../src/","sources":["updates/check.ts"],"names":[],"mappings":"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"}

package/dist/updates/self.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Self-update plumbing: detect how kimchictl was installed and, for binary
+ * installs, swap the executable in place from the latest GitHub release.
+ * Homebrew/npm/RTE (runtime) installs delegate to their own updaters.
+ */
+export type InstallMethod = "binary" | "homebrew" | "runtime";
+/** realpath seam: tests feed synthetic paths. */
+export declare function detectInstallMethod(realpath: () => string): InstallMethod;
+/** realpath of the running executable, best-effort. */
+export declare function defaultInstallMethod(execPath?: string): InstallMethod;
+/** Release asset name for this platform, e.g. kimchictl-darwin-arm64. */
+export declare function platformAssetName(platform?: NodeJS.Platform, arch?: string): string;
+export declare class SelfUpdateError extends Error {
+    constructor(message: string);
+}
+/** Distinct from a checksums-download failure: a verified mismatch always aborts. */
+export declare class ChecksumMismatchError extends SelfUpdateError {
+    constructor(message: string);
+}
+export interface SelfUpdateOptions {
+    targetPath: string;
+    version: string;
+    fetch?: typeof globalThis.fetch;
+    download?: (url: string, destPath: string) => Promise<void>;
+    chmodFn?: (path: string, mode: number) => Promise<void>;
+    renameFn?: (from: string, to: string) => Promise<void>;
+    tmpRoot?: string;
+}
+/**
+ * Download the release asset for the current platform, checksum-verify it
+ * against release checksums.txt, then atomically rename it over targetPath.
+ */
+export declare function selfUpdateToVersion(options: SelfUpdateOptions): Promise<void>;
+/** Guard for the update command — plain error for guard.ts, no new error family. */
+export declare function assertNotDevBuild(): void;
+//# sourceMappingURL=self.d.ts.map

package/dist/updates/self.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self.d.ts","sourceRoot":"../src/","sources":["updates/self.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AAEH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAA;AAE7D,iDAAiD;AACjD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,MAAM,GAAG,aAAa,CAUzE;AAED,uDAAuD;AACvD,wBAAgB,oBAAoB,CAAC,QAAQ,SAAmB,GAAG,aAAa,CAM/E;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAAE,IAAI,GAAE,MAAqB,GAAG,MAAM,CAOnH;AAED,qBAAa,eAAgB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI3B;AAED,qFAAqF;AACrF,qBAAa,qBAAsB,SAAQ,eAAe;gBAC7C,OAAO,EAAE,MAAM;CAI3B;AAED,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAUD;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCnF;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC"}

package/dist/updates/self.js

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdtemp, readFile, rename, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { fetchWithTimeout } from "../api/http.js";
+import { VERSION } from "../version.js";
+/** realpath seam: tests feed synthetic paths. */
+export function detectInstallMethod(realpath) {
+    const target = realpath();
+    if (/\/(Cellar|linuxbrew)\/[^/]*kimchictl?\//.test(target) || /homebrew.*kimchictl/i.test(target)) {
+        return "homebrew";
+    }
+    const base = basename(target);
+    if (base === "node" || base === "bun" || base === "node.exe") {
+        return "runtime";
+    }
+    return "binary";
+}
+/** realpath of the running executable, best-effort. */
+export function defaultInstallMethod(execPath = process.execPath) {
+    // bun-compiled binaries ARE the install (execPath is the binary); node/bun
+    // runtime hosts are npm/dev installs.
+    const base = basename(execPath);
+    if (base === "node" || base === "bun" || base === "node.exe")
+        return "runtime";
+    return detectInstallMethod(() => execPath);
+}
+/** Release asset name for this platform, e.g. kimchictl-darwin-arm64. */
+export function platformAssetName(platform = process.platform, arch = process.arch) {
+    const os = platform === "darwin" ? "darwin" : platform === "linux" ? "linux" : undefined;
+    const cpu = arch === "arm64" ? "arm64" : arch === "x64" ? "x64" : undefined;
+    if (!os || !cpu) {
+        throw new Error(`unsupported platform for self-update: ${platform}/${arch}`);
+    }
+    return `kimchictl-${os}-${cpu}`;
+}
+export class SelfUpdateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SelfUpdateError";
+    }
+}
+/** Distinct from a checksums-download failure: a verified mismatch always aborts. */
+export class ChecksumMismatchError extends SelfUpdateError {
+    constructor(message) {
+        super(message);
+        this.name = "ChecksumMismatchError";
+    }
+}
+async function defaultDownload(url, destPath) {
+    const resp = await fetchWithTimeout(url, {}, globalThis.fetch, 60_000);
+    if (!resp.ok) {
+        throw new SelfUpdateError(`download failed: HTTP ${resp.status} for ${url}`);
+    }
+    await writeFile(destPath, new Uint8Array(await resp.arrayBuffer()));
+}
+/**
+ * Download the release asset for the current platform, checksum-verify it
+ * against release checksums.txt, then atomically rename it over targetPath.
+ */
+export async function selfUpdateToVersion(options) {
+    const base = `https://github.com/getkimchi/kimchictl/releases/download/${options.version}`;
+    const asset = platformAssetName();
+    const download = options.download ?? defaultDownload;
+    const chmodFn = options.chmodFn ?? chmod;
+    const renameFn = options.renameFn ?? rename;
+    const tmpDir = await mkdtemp(join(options.tmpRoot ?? tmpdir(), "kimchictl-update-"));
+    const staged = join(tmpDir, "kimchictl");
+    await download(`${base}/${asset}`, staged);
+    // Verify against the release checksums.txt when it exists.
+    const checksumsPath = join(tmpDir, "checksums.txt");
+    try {
+        await download(`${base}/checksums.txt`, checksumsPath);
+        const checksums = await readFile(checksumsPath, "utf-8");
+        const expected = checksums
+            .split("\n")
+            .map((line) => line.trim())
+            .find((line) => line.endsWith(` ${asset}`))
+            ?.split(/\s+/)[0];
+        if (expected) {
+            const actual = createHash("sha256")
+                .update(await readFile(staged))
+                .digest("hex");
+            if (actual !== expected) {
+                throw new ChecksumMismatchError(`checksum mismatch for ${asset} — aborting update (expected ${expected}, got ${actual})`);
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof ChecksumMismatchError)
+            throw err;
+        // Fetching checksums.txt itself failed (older releases may lack it) — proceed without verification.
+    }
+    await chmodFn(staged, 0o755);
+    await renameFn(staged, options.targetPath);
+}
+/** Guard for the update command — plain error for guard.ts, no new error family. */
+export function assertNotDevBuild() {
+    if (VERSION.endsWith("-dev")) {
+        throw new SelfUpdateError("self-update is not available from a dev build (VERSION is 0.0.0-dev)");
+    }
+}
+//# sourceMappingURL=self.js.map

package/dist/updates/self.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self.js","sourceRoot":"../src/","sources":["updates/self.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Package version. The release pipeline (release.yml) stamps the git-tag
+ * version over this constant at build time; the committed value stays a
+ * sentinel so source checkouts are recognizable.
+ */
+export declare const VERSION = "0.0.2";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"../src/","sources":["version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,OAAO,UAAU,CAAA"}

package/dist/version.js

@@ -0,0 +1,7 @@
+/**
+ * Package version. The release pipeline (release.yml) stamps the git-tag
+ * version over this constant at build time; the committed value stays a
+ * sentinel so source checkouts are recognizable.
+ */
+export const VERSION = "0.0.2";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"../src/","sources":["version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAA"}

package/package.json

@@ -0,0 +1,77 @@
+{
+	"//name": "Scoped under the kimchi-dev npm org (the GitHub org is getkimchi)",
+	"name": "@kimchi-dev/kimchictl",
+	"//version": "Placeholder, never bumped: the git tag is the version, stamped by release.yml at publish time",
+	"version": "0.0.2",
+	"description": "Create and connect to kimchi remote workspaces from the terminal.",
+	"keywords": [
+		"kimchi",
+		"workspace",
+		"sandbox",
+		"remote-development",
+		"ssh",
+		"cli"
+	],
+	"license": "Apache-2.0",
+	"author": "CAST AI Group, Inc.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/getkimchi/kimchictl.git"
+	},
+	"homepage": "https://github.com/getkimchi/kimchictl#readme",
+	"bugs": "https://github.com/getkimchi/kimchictl/issues",
+	"packageManager": "pnpm@10.8.1",
+	"type": "module",
+	"engines": {
+		"node": ">=22.19"
+	},
+	"bin": {
+		"kimchictl": "./bin/kimchictl.mjs"
+	},
+	"//files": "dist is what consumers import; src ships so source maps resolve and git installs stay inspectable; bin is the CLI entry shim",
+	"files": [
+		"bin",
+		"dist",
+		"src"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/run.d.ts",
+			"default": "./dist/run.js"
+		},
+		"./commands/workspace": {
+			"types": "./dist/commands/workspace.d.ts",
+			"default": "./dist/commands/workspace.js"
+		},
+		"./commands/guard": {
+			"types": "./dist/commands/guard.d.ts",
+			"default": "./dist/commands/guard.js"
+		}
+	},
+	"scripts": {
+		"dev": "bun src/cli.ts",
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "pnpm run build",
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"check": "pnpm run lint && pnpm run typecheck && pnpm run test"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.6",
+		"@types/node": "^22.19.18",
+		"@types/proper-lockfile": "^4.1.4",
+		"@types/ws": "^8.18.1",
+		"typescript": "^5.9.3",
+		"vitest": "^3.2.4"
+	},
+	"dependencies": {
+		"open": "^11.0.4",
+		"proper-lockfile": "^4.1.2",
+		"ws": "^8.21.3"
+	}
+}

package/src/api/http.ts

@@ -0,0 +1,70 @@
+import type { ApiOptions } from "./types.js"
+import { RemoteAuthError, RemoteNetworkError, RemoteQuotaError } from "./types.js"
+
+/** Control-plane base URL: option → KIMCHI_REMOTE_ENDPOINT → https://app.kimchi.dev/api. */
+export function resolveEndpoint(options?: ApiOptions): string {
+	return options?.endpoint ?? process.env.KIMCHI_REMOTE_ENDPOINT ?? "https://app.kimchi.dev/api"
+}
+
+export async function fetchWithTimeout(
+	url: string,
+	init: RequestInit,
+	fetchImpl: typeof globalThis.fetch,
+	ms = 30_000,
+	externalSignal?: AbortSignal,
+): Promise<Response> {
+	const ctrl = new AbortController()
+	const timer = setTimeout(() => ctrl.abort(), ms)
+	const signal = externalSignal ? AbortSignal.any([ctrl.signal, externalSignal]) : ctrl.signal
+	try {
+		return await fetchImpl(url, { ...init, signal })
+	} finally {
+		clearTimeout(timer)
+	}
+}
+
+/** Status-to-error mapping shared by all control-plane calls (mirrors the harness). */
+export async function checkResponse(resp: Response, endpoint: string): Promise<void> {
+	if (resp.ok) return
+
+	const body = await resp.text().catch(() => "")
+	switch (resp.status) {
+		case 401:
+			throw new RemoteAuthError(`Invalid API key — run 'kimchictl login' to authenticate: ${endpoint}`, 401)
+		case 403:
+			throw new RemoteAuthError(
+				`Forbidden — your API key does not have permission to use remote workspaces. ${endpoint}`,
+				403,
+			)
+		case 404:
+			throw new RemoteAuthError(`Workspace not found or endpoint not available. ${endpoint}`, 404)
+		case 409:
+			throw new RemoteAuthError(`Workspace conflict — another client may already own this workspace. ${endpoint}`, 409)
+		case 429: {
+			// Quota-exceeded bodies look like
+			// {"message":"quota exceeded: user CPU limit exceeded","fieldViolations":[]}.
+			const detail = parseQuotaDetail(body)
+			if (detail !== undefined) {
+				throw new RemoteQuotaError(`Unable to provision workspace: ${detail}`, 429)
+			}
+			throw new RemoteNetworkError(`HTTP ${resp.status} from ${endpoint}${body ? `: ${body}` : ""}`)
+		}
+		default: {
+			throw new RemoteNetworkError(`HTTP ${resp.status} from ${endpoint}${body ? `: ${body}` : ""}`)
+		}
+	}
+}
+
+/**
+ * Extract the human-readable reason from a 429 body, or undefined when the
+ * body is not JSON with a "message" string (plain rate-limit response).
+ */
+function parseQuotaDetail(body: string): string | undefined {
+	try {
+		const parsed = JSON.parse(body) as { message?: unknown }
+		if (typeof parsed.message !== "string" || parsed.message.length === 0) return undefined
+		return parsed.message.replace(/^quota exceeded:\s*/i, "")
+	} catch {
+		return undefined
+	}
+}

package/src/api/keys.ts

@@ -0,0 +1,40 @@
+import { checkResponse, fetchWithTimeout, resolveEndpoint } from "./http.js"
+import type { ApiOptions } from "./types.js"
+import { RemoteNetworkError } from "./types.js"
+
+/**
+ * Verify an API key against the control plane. Returns the organization id.
+ * (Mirror of kimchi-dev:src/sandbox/cloud/keys.ts.)
+ */
+export async function verifyApiKey(apiKey: string, options?: ApiOptions): Promise<string> {
+	const endpoint = resolveEndpoint(options)
+	const fetchImpl = options?.fetch ?? globalThis.fetch
+
+	const url = `${endpoint}/ai-optimizer/v1beta/workspace-tokens:verifyKey`
+	const resp = await fetchWithTimeout(
+		url,
+		{
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+				"Content-Type": "application/json",
+			},
+		},
+		fetchImpl,
+		30_000,
+		options?.signal,
+	)
+
+	await checkResponse(resp, url)
+
+	const data = await resp.json().catch(() => {
+		throw new RemoteNetworkError(`Unexpected non-JSON response from ${endpoint}`)
+	})
+
+	const orgId = (data as { organizationId?: unknown }).organizationId
+	if (typeof orgId !== "string") {
+		throw new RemoteNetworkError(`Missing organizationId in verify response from ${endpoint}`)
+	}
+
+	return orgId
+}

package/src/api/me.ts

@@ -0,0 +1,48 @@
+import { fetchWithTimeout, resolveEndpoint } from "./http.js"
+import type { ApiOptions } from "./types.js"
+
+/**
+ * GET /v1/me — the authenticated user's profile.
+ * (Mirror of kimchi-dev:src/api/me.ts.)
+ */
+export async function getMe(
+	apiKey: string,
+	options?: ApiOptions,
+): Promise<{
+	id: string
+	username?: string
+	name?: string
+	email?: string
+}> {
+	const endpoint = resolveEndpoint(options)
+	const fetchImpl = options?.fetch ?? globalThis.fetch
+
+	const url = `${endpoint}/v1/me`
+	const resp = await fetchWithTimeout(
+		url,
+		{
+			method: "GET",
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+				Accept: "application/json",
+			},
+		},
+		fetchImpl,
+		30_000,
+		options?.signal,
+	)
+
+	if (!resp.ok) {
+		throw new Error(`GET ${url} failed with HTTP ${resp.status}`)
+	}
+
+	const data = await resp.json().catch(() => {
+		throw new Error(`Unexpected non-JSON response from ${url}`)
+	})
+
+	if (typeof (data as { id?: unknown })?.id !== "string" || (data as { id: string }).id.length === 0) {
+		throw new Error(`Missing id in /v1/me response from ${url}`)
+	}
+
+	return data as { id: string; username?: string; name?: string; email?: string }
+}