@kimchi-dev/kimchictl 0.0.2

package/dist/ssh/bridge.js

@@ -0,0 +1,95 @@
+import { WebSocket } from "ws";
+/**
+ * Binary WebSocket↔stdio bridge — the runtime behind the hidden
+ * `kimchictl ssh proxy` command that the generated ssh_config references via
+ * ProxyCommand. TS port of kap's internal/ssh/bridge.go.
+ *
+ * Exit semantics (mirroring kap): stdin EOF or a normal WS close end the
+ * bridge without error; any other failure rejects with a descriptive error.
+ * The proxy process is short-lived — it exits when the bridge resolves, so
+ * dangling listeners cannot outlive it.
+ */
+export class BridgeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BridgeError";
+    }
+}
+export async function bridgeStdioToWebSocket(options) {
+    const WS = options._WebSocket ?? WebSocket;
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    let ws;
+    try {
+        ws = new WS(options.wsUrl, {
+            headers: { Authorization: `Bearer ${options.token}` },
+        });
+    }
+    catch (err) {
+        throw new BridgeError(`websocket dial ${options.wsUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const done = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            if (err)
+                reject(err);
+            else
+                resolve();
+        };
+        ws.on("open", () => done());
+        ws.on("unexpected-response", (_req, res) => {
+            done(new BridgeError(`websocket dial ${options.wsUrl}: unexpected HTTP ${res.statusCode} ${res.statusMessage ?? ""}`.trim()));
+        });
+        ws.on("error", (err) => done(new BridgeError(`websocket dial ${options.wsUrl}: ${err.message}`)));
+    });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            input.removeAllListeners();
+            // Output is process.stdout when bridging for real — never end() that;
+            // only close streams the caller explicitly passed in.
+            if (options.output)
+                output.end();
+            if (err)
+                reject(err);
+            else
+                resolve();
+        };
+        // WS → stdout
+        ws.on("message", (data, isBinary) => {
+            // The workspace bridge is binary-only; text frames would be a server bug,
+            // but writing them through is still friendlier than dropping bytes.
+            void isBinary;
+            const buffer = Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+            if (!output.write(buffer)) {
+                // Keep memory bounded if the consumer stalls: pause the socket until drained.
+                ws.pause();
+                output.once("drain", () => ws.resume());
+            }
+        });
+        ws.on("close", () => finish());
+        ws.on("error", (err) => finish(err.code === 1000 || err.code === 1001
+            ? undefined // normal / going-away closure
+            : new BridgeError(`websocket error: ${err.message}`)));
+        // stdin → WS
+        if (input.isPaused?.())
+            input.resume();
+        input.on("data", (chunk) => {
+            if (ws.readyState !== WebSocket.OPEN)
+                return;
+            ws.send(chunk, { binary: true });
+        });
+        input.on("end", () => {
+            if (ws.readyState === WebSocket.OPEN)
+                ws.close(1000);
+        });
+        input.on("error", (err) => finish(err));
+    });
+}
+//# sourceMappingURL=bridge.js.map

package/dist/ssh/bridge.js.map

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

package/dist/ssh/config.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Native SSH integration (TS port of kap:internal/ssh/setup.go).
+ *
+ * Layout:
+ *   ~/.config/kimchi/kimchictl/ssh_config   — `Host *.<domain>` wildcard routing
+ *                                             through `kimchictl ssh proxy %h` as ProxyCommand
+ *   ~/.config/kimchi/kimchictl/known_hosts  — dedicated known_hosts for workspace hosts
+ *   ~/.ssh/config                           — gets a marker-wrapped `Include` block
+ *
+ * Behavior per the product decision "setup happens on install": writes are
+ * automatic (no y/N prompt) with a clear notice; `--uninstall` reverts.
+ */
+export declare const SSH_INCLUDE_BEGIN = "# >>> kimchictl managed include >>>";
+export declare const SSH_INCLUDE_END = "# <<< kimchictl managed include <<<";
+export interface SshPaths {
+    /** ~/.config/kimchi/kimchictl root (also used for the update-check cache). */
+    home: string;
+    sshConfig: string;
+    knownHosts: string;
+    userSshConfig: string;
+}
+export declare function resolveSshPaths(env?: NodeJS.ProcessEnv): SshPaths;
+/**
+ * The wildcard domain workspaces are reached at. Default remote.kimchi.dev;
+ * derived from the API endpoint host for dev environments
+ * (app.X → remote.X), overridable via flag/env for exotic setups.
+ */
+export declare function resolveSshDomain(explicit?: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * The ProxyCommand must not rely on ssh's PATH lookup — point it at a
+ * fully-qualified command:
+ *   - compiled binary: its own absolute path
+ *   - node/bun runtime: the runtime plus the ABSOLUTE entry script
+ *     (e.g. `/usr/bin/node /…/dist/cli.js`), so the config works from any cwd
+ * Bare `kimchictl` remains only as a last resort when no entry can be named.
+ */
+export declare function resolveProxyCommandTarget(execPath?: string, entryScript?: string): string;
+export declare function sshConfigContent(domain: string, knownHostsPath: string, proxyTarget: string): string;
+export interface SetupResult {
+    notes: string[];
+}
+/**
+ * Write the kimchictl ssh_config and ensure ~/.ssh/config includes it.
+ * Idempotent; a stale managed block (different include path) is replaced in
+ * place. Returns human-readable notes of everything that changed.
+ */
+export declare function setupSshIntegration(options: {
+    paths: SshPaths;
+    domain: string;
+    proxyTarget?: string;
+    /** Detect and warn about a kap-managed block (same wildcard domain conflict). */
+    warnKapConflict?: (note: string) => void;
+}): Promise<SetupResult>;
+/** Remove the Include block and the generated ssh_config. Returns notes. */
+export declare function uninstallSshIntegration(options: {
+    paths: SshPaths;
+}): Promise<SetupResult>;
+/**
+ * True when the generated ssh_config exists AND the user config includes it.
+ * Used by `ssh <name>` / `login` to auto-setup when missing.
+ */
+export declare function isSshIntegrationConfigured(paths: SshPaths, domain: string, proxyTarget?: string): Promise<boolean>;
+/** Disabled-marker env var honored by every auto-setup caller. */
+export declare function isSshSetupDisabled(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/ssh/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"../src/","sources":["ssh/config.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,iBAAiB,wCAAwC,CAAA;AACtE,eAAO,MAAM,eAAe,wCAAwC,CAAA;AAEpE,MAAM,WAAW,QAAQ;IACxB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,EAAE,MAAM,CAAA;CACrB;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,QAAQ,CAU9E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAchG;AAOD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,GAAE,MAAyB,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAU3G;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQpG;AAED,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAA;CACf;AAqBD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IAClD,KAAK,EAAE,QAAQ,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iFAAiF;IACjF,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC,GAAG,OAAO,CAAC,WAAW,CAAC,CAwCvB;AAED,4EAA4E;AAC5E,wBAAsB,uBAAuB,CAAC,OAAO,EAAE;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CA2BhG;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC/C,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CAelB;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAGhF"}

package/dist/ssh/config.js

@@ -0,0 +1,198 @@
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+/**
+ * Native SSH integration (TS port of kap:internal/ssh/setup.go).
+ *
+ * Layout:
+ *   ~/.config/kimchi/kimchictl/ssh_config   — `Host *.<domain>` wildcard routing
+ *                                             through `kimchictl ssh proxy %h` as ProxyCommand
+ *   ~/.config/kimchi/kimchictl/known_hosts  — dedicated known_hosts for workspace hosts
+ *   ~/.ssh/config                           — gets a marker-wrapped `Include` block
+ *
+ * Behavior per the product decision "setup happens on install": writes are
+ * automatic (no y/N prompt) with a clear notice; `--uninstall` reverts.
+ */
+export const SSH_INCLUDE_BEGIN = "# >>> kimchictl managed include >>>";
+export const SSH_INCLUDE_END = "# <<< kimchictl managed include <<<";
+export function resolveSshPaths(env = process.env) {
+    // Lives with the rest of the kimchi config tree (harness/, desktop/, memory/…).
+    const home = env.KIMCHICTL_HOME ?? join(env.HOME ?? homedir(), ".config", "kimchi", "kimchictl");
+    const userSshConfig = join(env.HOME ?? homedir(), ".ssh", "config");
+    return {
+        home,
+        sshConfig: join(home, "ssh_config"),
+        knownHosts: join(home, "known_hosts"),
+        userSshConfig,
+    };
+}
+/**
+ * The wildcard domain workspaces are reached at. Default remote.kimchi.dev;
+ * derived from the API endpoint host for dev environments
+ * (app.X → remote.X), overridable via flag/env for exotic setups.
+ */
+export function resolveSshDomain(explicit, env = process.env) {
+    if (explicit)
+        return explicit;
+    if (env.KIMCHICTL_SSH_DOMAIN)
+        return env.KIMCHICTL_SSH_DOMAIN;
+    const endpoint = env.KIMCHI_REMOTE_ENDPOINT;
+    if (endpoint) {
+        try {
+            const host = new URL(endpoint).hostname;
+            const stripped = host.startsWith("app.") ? host.slice("app.".length) : host;
+            return `remote.${stripped}`;
+        }
+        catch {
+            // Fall through to the production default below.
+        }
+    }
+    return "remote.kimchi.dev";
+}
+/** Shell-quote a single ProxyCommand token when it contains whitespace. */
+function shellQuote(token) {
+    return /\s|"|'/.test(token) ? `"${token.replace(/"/g, '\\"')}"` : token;
+}
+/**
+ * The ProxyCommand must not rely on ssh's PATH lookup — point it at a
+ * fully-qualified command:
+ *   - compiled binary: its own absolute path
+ *   - node/bun runtime: the runtime plus the ABSOLUTE entry script
+ *     (e.g. `/usr/bin/node /…/dist/cli.js`), so the config works from any cwd
+ * Bare `kimchictl` remains only as a last resort when no entry can be named.
+ */
+export function resolveProxyCommandTarget(execPath = process.execPath, entryScript) {
+    const base = execPath.split("/").pop() ?? "";
+    if (base === "kimchictl" || base.startsWith("kimchictl-")) {
+        return shellQuote(execPath);
+    }
+    const entry = entryScript ?? process.argv[1];
+    if (entry) {
+        return `${shellQuote(execPath)} ${shellQuote(resolve(entry))}`;
+    }
+    return "kimchictl";
+}
+export function sshConfigContent(domain, knownHostsPath, proxyTarget) {
+    return (`Host *.${domain}\n` +
+        `    ProxyCommand ${proxyTarget} ssh proxy %h\n` +
+        `    UserKnownHostsFile ${knownHostsPath}\n` +
+        `    StrictHostKeyChecking accept-new\n` +
+        `    User developer\n`);
+}
+async function writePrivateFile(path, content) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, content, { mode: 0o600 });
+    await chmod(path, 0o600);
+}
+function managedBlock(includePath) {
+    return `${SSH_INCLUDE_BEGIN}\nInclude ${includePath}\n${SSH_INCLUDE_END}`;
+}
+/** Extract an existing managed include block (any path), or undefined. */
+function extractManagedBlock(content) {
+    const start = content.indexOf(SSH_INCLUDE_BEGIN);
+    if (start === -1)
+        return undefined;
+    const endRel = content.slice(start).indexOf(SSH_INCLUDE_END);
+    if (endRel === -1)
+        return undefined;
+    return content.slice(start, start + endRel + SSH_INCLUDE_END.length + 1);
+}
+/**
+ * Write the kimchictl ssh_config and ensure ~/.ssh/config includes it.
+ * Idempotent; a stale managed block (different include path) is replaced in
+ * place. Returns human-readable notes of everything that changed.
+ */
+export async function setupSshIntegration(options) {
+    const { paths, domain } = options;
+    const notes = [];
+    const content = sshConfigContent(domain, paths.knownHosts, options.proxyTarget ?? resolveProxyCommandTarget());
+    const previous = existsSync(paths.sshConfig) ? await readFile(paths.sshConfig, "utf-8") : undefined;
+    if (previous !== content) {
+        await writePrivateFile(paths.sshConfig, content);
+        notes.push(`wrote ${paths.sshConfig} (Host *.${domain})`);
+    }
+    let userConfig = "";
+    try {
+        userConfig = await readFile(paths.userSshConfig, "utf-8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    if (userConfig.includes("# >>> kap managed include >>>")) {
+        notes.push("⚠ found a kap-managed Include block in ~/.ssh/config — both wildcard configs match " +
+            "this domain; the first Include wins. Remove one if connections route to the wrong proxy.");
+    }
+    const block = managedBlock(paths.sshConfig);
+    const existing = extractManagedBlock(userConfig);
+    if (existing === undefined) {
+        // First match in ssh config wins for most options: the Include must come first.
+        const next = userConfig.length > 0 ? `${block}\n\n${userConfig}` : `${block}\n`;
+        await writePrivateFile(paths.userSshConfig, next);
+        notes.push(`added Include block to ${paths.userSshConfig}`);
+    }
+    else if (existing !== block && existing !== `${block}\n`) {
+        // Stale block (e.g. config dir moved) — replace in place.
+        const next = userConfig.replace(existing, `${block}\n`);
+        await writePrivateFile(paths.userSshConfig, next);
+        notes.push(`updated stale Include block in ${paths.userSshConfig}`);
+    }
+    return { notes };
+}
+/** Remove the Include block and the generated ssh_config. Returns notes. */
+export async function uninstallSshIntegration(options) {
+    const { paths } = options;
+    const notes = [];
+    let userConfig = "";
+    try {
+        userConfig = await readFile(paths.userSshConfig, "utf-8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    const existing = extractManagedBlock(userConfig);
+    if (existing !== undefined) {
+        let next = userConfig.replace(existing, "");
+        // Tidy the blank line we added after the block when nothing precedes it.
+        next = next.replace(/^\n+/, "").replace(/\n{3,}/g, "\n\n");
+        await writePrivateFile(paths.userSshConfig, next);
+        notes.push(`removed Include block from ${paths.userSshConfig}`);
+    }
+    if (existsSync(paths.sshConfig)) {
+        // Remove rather than truncate: keep the dir (it also holds known_hosts/cache).
+        await rm(paths.sshConfig, { force: true });
+        notes.push(`removed ${paths.sshConfig}`);
+    }
+    return { notes };
+}
+/**
+ * True when the generated ssh_config exists AND the user config includes it.
+ * Used by `ssh <name>` / `login` to auto-setup when missing.
+ */
+export async function isSshIntegrationConfigured(paths, domain, proxyTarget) {
+    if (!existsSync(paths.sshConfig))
+        return false;
+    try {
+        const userConfig = await readFile(paths.userSshConfig, "utf-8");
+        const expected = managedBlock(paths.sshConfig);
+        const existing = extractManagedBlock(userConfig);
+        if (existing !== expected && existing !== `${expected}\n`)
+            return false;
+        const generated = await readFile(paths.sshConfig, "utf-8");
+        // Both domain drift (endpoint override changed) and proxy-target drift
+        // (the executable moved since setup) must re-trigger setup: compare the
+        // full expected content.
+        return generated === sshConfigContent(domain, paths.knownHosts, proxyTarget ?? resolveProxyCommandTarget());
+    }
+    catch {
+        return false;
+    }
+}
+/** Disabled-marker env var honored by every auto-setup caller. */
+export function isSshSetupDisabled(env = process.env) {
+    const value = env.KIMCHICTL_NO_SSH_SETUP;
+    return value !== undefined && value !== "" && value !== "0" && value !== "false";
+}
+//# sourceMappingURL=config.js.map

package/dist/ssh/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"../src/","sources":["ssh/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAElD;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,qCAAqC,CAAA;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG,qCAAqC,CAAA;AAUpE,MAAM,UAAU,eAAe,CAAC,MAAyB,OAAO,CAAC,GAAG;IACnE,gFAAgF;IAChF,MAAM,IAAI,GAAG,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAA;IAChG,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAA;IACnE,OAAO;QACN,IAAI;QACJ,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC;QACnC,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC;QACrC,aAAa;KACb,CAAA;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAiB,EAAE,MAAyB,OAAO,CAAC,GAAG;IACvF,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAC7B,IAAI,GAAG,CAAC,oBAAoB;QAAE,OAAO,GAAG,CAAC,oBAAoB,CAAA;IAC7D,MAAM,QAAQ,GAAG,GAAG,CAAC,sBAAsB,CAAA;IAC3C,IAAI,QAAQ,EAAE,CAAC;QACd,IAAI,CAAC;YACJ,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAA;YACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;YAC3E,OAAO,UAAU,QAAQ,EAAE,CAAA;QAC5B,CAAC;QAAC,MAAM,CAAC;YACR,gDAAgD;QACjD,CAAC;IACF,CAAC;IACD,OAAO,mBAAmB,CAAA;AAC3B,CAAC;AAED,2EAA2E;AAC3E,SAAS,UAAU,CAAC,KAAa;IAChC,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAA;AACxE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CAAC,WAAmB,OAAO,CAAC,QAAQ,EAAE,WAAoB;IAClG,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAA;IAC5C,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC3D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAA;IAC5B,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAC5C,IAAI,KAAK,EAAE,CAAC;QACX,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAA;IAC/D,CAAC;IACD,OAAO,WAAW,CAAA;AACnB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,cAAsB,EAAE,WAAmB;IAC3F,OAAO,CACN,UAAU,MAAM,IAAI;QACpB,oBAAoB,WAAW,iBAAiB;QAChD,0BAA0B,cAAc,IAAI;QAC5C,wCAAwC;QACxC,sBAAsB,CACtB,CAAA;AACF,CAAC;AAMD,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAe;IAC5D,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IAC5D,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IAC/C,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;AACzB,CAAC;AAED,SAAS,YAAY,CAAC,WAAmB;IACxC,OAAO,GAAG,iBAAiB,aAAa,WAAW,KAAK,eAAe,EAAE,CAAA;AAC1E,CAAC;AAED,0EAA0E;AAC1E,SAAS,mBAAmB,CAAC,OAAe;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAChD,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAA;IAClC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAA;IAC5D,IAAI,MAAM,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAA;IACnC,OAAO,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,eAAe,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;AACzE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAMzC;IACA,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IACjC,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,WAAW,IAAI,yBAAyB,EAAE,CAAC,CAAA;IAC9G,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACnG,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC1B,MAAM,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QAChD,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,SAAS,YAAY,MAAM,GAAG,CAAC,CAAA;IAC1D,CAAC;IAED,IAAI,UAAU,GAAG,EAAE,CAAA;IACnB,IAAI,CAAC;QACJ,UAAU,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,aAAa,EAAE,OAAO,CAAC,CAAA;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAA;IAChE,CAAC;IAED,IAAI,UAAU,CAAC,QAAQ,CAAC,+BAA+B,CAAC,EAAE,CAAC;QAC1D,KAAK,CAAC,IAAI,CACT,qFAAqF;YACpF,0FAA0F,CAC3F,CAAA;IACF,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;IAC3C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;IAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC5B,gFAAgF;QAChF,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,OAAO,UAAU,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAA;QAC/E,MAAM,gBAAgB,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;QACjD,KAAK,CAAC,IAAI,CAAC,0BAA0B,KAAK,CAAC,aAAa,EAAE,CAAC,CAAA;IAC5D,CAAC;SAAM,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5D,0DAA0D;QAC1D,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC,CAAA;QACvD,MAAM,gBAAgB,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;QACjD,KAAK,CAAC,IAAI,CAAC,kCAAkC,KAAK,CAAC,aAAa,EAAE,CAAC,CAAA;IACpE,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,CAAA;AACjB,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,OAA4B;IACzE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IACzB,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,IAAI,UAAU,GAAG,EAAE,CAAA;IACnB,IAAI,CAAC;QACJ,UAAU,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,aAAa,EAAE,OAAO,CAAC,CAAA;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAA;IAChE,CAAC;IAED,MAAM,QAAQ,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;IAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;QAC3C,yEAAyE;QACzE,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;QAC1D,MAAM,gBAAgB,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;QACjD,KAAK,CAAC,IAAI,CAAC,8BAA8B,KAAK,CAAC,aAAa,EAAE,CAAC,CAAA;IAChE,CAAC;IAED,IAAI,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QACjC,+EAA+E;QAC/E,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;QAC1C,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,SAAS,EAAE,CAAC,CAAA;IACzC,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,CAAA;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC/C,KAAe,EACf,MAAc,EACd,WAAoB;IAEpB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC;QAAE,OAAO,KAAK,CAAA;IAC9C,IAAI,CAAC;QACJ,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,aAAa,EAAE,OAAO,CAAC,CAAA;QAC/D,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QAC9C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;QAChD,IAAI,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,GAAG,QAAQ,IAAI;YAAE,OAAO,KAAK,CAAA;QACvE,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QAC1D,uEAAuE;QACvE,wEAAwE;QACxE,yBAAyB;QACzB,OAAO,SAAS,KAAK,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,WAAW,IAAI,yBAAyB,EAAE,CAAC,CAAA;IAC5G,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAA;IACb,CAAC;AACF,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,MAAM,KAAK,GAAG,GAAG,CAAC,sBAAsB,CAAA;IACxC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,OAAO,CAAA;AACjF,CAAC"}

package/dist/ssh/connect.d.ts

@@ -0,0 +1,27 @@
+import type { ApiOptions } from "../api/types.js";
+import { isSshIntegrationConfigured, setupSshIntegration } from "./config.js";
+/**
+ * Validate that native SSH integration is configured; set it up automatically
+ * when missing (the "setup on use" half of the setup-on-install decision).
+ * Returns false when auto-setup is disabled via KIMCHICTL_NO_SSH_SETUP.
+ */
+export declare function ensureSshIntegration(options: {
+    env?: NodeJS.ProcessEnv;
+    domain?: string;
+    /** Injection seams for tests. */
+    setup?: typeof setupSshIntegration;
+    isConfigured?: typeof isSshIntegrationConfigured;
+}): Promise<boolean>;
+export interface SshConnectOptions extends ApiOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Exec seam (tests): run system ssh, return its exit status. */
+    exec?: (args: string[]) => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Connect to a workspace with system ssh: ensure integration → resume a
+ * hibernated workspace (and wait for it) → exec `ssh <alias>.<domain>` with
+ * inherited stdio. Extra args are passed to ssh as the remote command.
+ */
+export declare function connectToWorkspace(name: string, remoteCommand: string[], options?: SshConnectOptions): Promise<number>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/ssh/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"../src/","sources":["ssh/connect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAGjD,OAAO,EACN,0BAA0B,EAI1B,mBAAmB,EACnB,MAAM,aAAa,CAAA;AAMpB;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iCAAiC;IACjC,KAAK,CAAC,EAAE,OAAO,mBAAmB,CAAA;IAClC,YAAY,CAAC,EAAE,OAAO,0BAA0B,CAAA;CAChD,GAAG,OAAO,CAAC,OAAO,CAAC,CAenB;AAED,MAAM,WAAW,iBAAkB,SAAQ,UAAU;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,iEAAiE;IACjE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;IACjC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACrC;AAMD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EAAE,EACvB,OAAO,GAAE,iBAAsB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAgCjB"}

package/dist/ssh/connect.js

@@ -0,0 +1,67 @@
+import { spawnSync } from "node:child_process";
+import { resolveWorkspace } from "../api/resolver.js";
+import { waitForWorkspaceActive } from "../api/wait.js";
+import { requireApiKey } from "../auth/resolve.js";
+import { isSshIntegrationConfigured, isSshSetupDisabled, resolveSshDomain, resolveSshPaths, setupSshIntegration, } from "./config.js";
+import { resumeForConnect, workspaceIdFromRef } from "./tunnel.js";
+/** Post-resume wait budget for a hibernated workspace to reach ACTIVE. */
+const RESUME_WAIT_TIMEOUT_MS = 90_000;
+/**
+ * Validate that native SSH integration is configured; set it up automatically
+ * when missing (the "setup on use" half of the setup-on-install decision).
+ * Returns false when auto-setup is disabled via KIMCHICTL_NO_SSH_SETUP.
+ */
+export async function ensureSshIntegration(options) {
+    const env = options.env ?? process.env;
+    if (isSshSetupDisabled(env))
+        return false;
+    const paths = resolveSshPaths(env);
+    const domain = resolveSshDomain(options.domain, env);
+    const isConfigured = options.isConfigured ?? isSshIntegrationConfigured;
+    if (await isConfigured(paths, domain))
+        return true;
+    const setup = options.setup ?? setupSshIntegration;
+    const { notes } = await setup({ paths, domain });
+    console.error("✓ SSH integration configured");
+    for (const note of notes)
+        console.error(`  ${note}`);
+    console.error("  undo: kimchictl ssh setup --uninstall");
+    return true;
+}
+function defaultExec(args) {
+    return spawnSync(args[0] ?? "ssh", args.slice(1), { stdio: "inherit", shell: false }).status ?? 1;
+}
+/**
+ * Connect to a workspace with system ssh: ensure integration → resume a
+ * hibernated workspace (and wait for it) → exec `ssh <alias>.<domain>` with
+ * inherited stdio. Extra args are passed to ssh as the remote command.
+ */
+export async function connectToWorkspace(name, remoteCommand, options = {}) {
+    const env = options.env ?? process.env;
+    await ensureSshIntegration({ env });
+    const { key } = requireApiKey(env);
+    // Accepts "<alias>", "<alias>.<domain>", a UUID, or an alias prefix.
+    const ref = workspaceIdFromRef(name);
+    let workspace = await resolveWorkspace(key, ref, options);
+    if (workspace.status === "suspended" || workspace.status === "initializing") {
+        if (workspace.status === "suspended") {
+            await resumeForConnect(key, workspace.id, options);
+        }
+        process.stderr.write("  resuming…");
+        workspace = await waitForWorkspaceActive(key, workspace.id, {
+            ...options,
+            timeoutMs: RESUME_WAIT_TIMEOUT_MS,
+            sleep: options.sleep,
+            onTick: (elapsedSeconds) => process.stderr.write(`\r  resuming… ${elapsedSeconds}s`),
+        });
+        process.stderr.write("\n");
+        if (workspace.status !== "active") {
+            process.stderr.write(`  ⚠ workspace is ${workspace.status} — connecting anyway; ` +
+                `if it fails, retry in a minute or check: kimchictl workspace get ${workspace.alias}\n`);
+        }
+    }
+    const domain = resolveSshDomain(undefined, env);
+    const host = `${workspace.alias}.${domain}`;
+    return (options.exec ?? defaultExec)(["ssh", host, ...remoteCommand]);
+}
+//# sourceMappingURL=connect.js.map

package/dist/ssh/connect.js.map

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

package/dist/ssh/tunnel.d.ts

@@ -0,0 +1,29 @@
+import type { ApiOptions } from "../api/types.js";
+/**
+ * Tunnel resolution for the SSH bridge (TS port of kap's
+ * internal/ssh/bridge.go ResolveTunnel — refs resolve via api/resolver.ts).
+ */
+export interface TunnelCreds {
+    /** wss://<workspace-host>/ssh */
+    wsUrl: string;
+    /** Short-lived workspace JWT for the Authorization header. */
+    token: string;
+}
+/**
+ * Accepts a bare workspace id or a full hostname (id.domain) — the domain
+ * suffix is stripped, which is what makes this usable as the ProxyCommand
+ * target (`%h` expands to the full hostname).
+ */
+export declare function workspaceIdFromRef(wsRef: string): string;
+/** wss://{uri}/ssh — explicit port appended only when not 0/443 (kap parity). */
+export declare function buildWsUrl(uri: string, port?: number): string;
+export interface ResolveTunnelOptions extends ApiOptions {
+    /** WebSocket port override (dev; default 443). */
+    port?: number;
+}
+export declare function resolveTunnel(apiKey: string, wsRef: string, options?: ResolveTunnelOptions): Promise<TunnelCreds>;
+/** Wake a hibernated workspace. Best-effort by contract: resume is idempotent server-side. */
+export declare function resumeForConnect(apiKey: string, workspaceId: string, options?: ApiOptions & {
+    orgId?: string;
+}): Promise<void>;
+//# sourceMappingURL=tunnel.d.ts.map

package/dist/ssh/tunnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.ts","sourceRoot":"../src/","sources":["ssh/tunnel.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAGjD;;;GAGG;AAEH,MAAM,WAAW,WAAW;IAC3B,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,MAAM,CAK1D;AAED,MAAM,WAAW,oBAAqB,SAAQ,UAAU;IACvD,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAA;CACb;AAED,wBAAsB,aAAa,CAClC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED,8FAA8F;AAC9F,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,UAAU,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/ssh/tunnel.js

@@ -0,0 +1,36 @@
+import { verifyApiKey } from "../api/keys.js";
+import { resolveWorkspace } from "../api/resolver.js";
+import { exchangeWorkspaceToken, resumeWorkspace } from "../api/tokens.js";
+import { RemoteNetworkError } from "../api/types.js";
+/**
+ * Accepts a bare workspace id or a full hostname (id.domain) — the domain
+ * suffix is stripped, which is what makes this usable as the ProxyCommand
+ * target (`%h` expands to the full hostname).
+ */
+export function workspaceIdFromRef(wsRef) {
+    const dot = wsRef.indexOf(".");
+    return dot > 0 ? wsRef.slice(0, dot) : wsRef;
+}
+/** wss://{uri}/ssh — explicit port appended only when not 0/443 (kap parity). */
+export function buildWsUrl(uri, port = 443) {
+    // The API may return a bare host or a scheme-prefixed URI; normalize to host[:port].
+    const host = uri.includes("://") ? new URL(uri).host : uri;
+    if (!host)
+        throw new RemoteNetworkError(`Invalid workspace URI from server: ${uri}`);
+    return `wss://${host}${port === 0 || port === 443 ? "" : `:${port}`}/ssh`;
+}
+export async function resolveTunnel(apiKey, wsRef, options) {
+    const ref = workspaceIdFromRef(wsRef);
+    const workspace = await resolveWorkspace(apiKey, ref, options);
+    if (!workspace.uri) {
+        throw new RemoteNetworkError(`Workspace ${ref} has no connection URI yet — it may still be provisioning`);
+    }
+    const { token } = await exchangeWorkspaceToken(apiKey, workspace.id, options);
+    return { wsUrl: buildWsUrl(workspace.uri, options?.port), token };
+}
+/** Wake a hibernated workspace. Best-effort by contract: resume is idempotent server-side. */
+export async function resumeForConnect(apiKey, workspaceId, options) {
+    const orgId = options?.orgId ?? (await verifyApiKey(apiKey, options));
+    await resumeWorkspace(apiKey, workspaceId, { ...options, orgId });
+}
+//# sourceMappingURL=tunnel.js.map

package/dist/ssh/tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.js","sourceRoot":"../src/","sources":["ssh/tunnel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAE1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAcpD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC/C,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC9B,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAC7C,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,IAAI,GAAG,GAAG;IACjD,qFAAqF;IACrF,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAA;IAC1D,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,kBAAkB,CAAC,sCAAsC,GAAG,EAAE,CAAC,CAAA;IACpF,OAAO,SAAS,IAAI,GAAG,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,MAAM,CAAA;AAC1E,CAAC;AAOD,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,MAAc,EACd,KAAa,EACb,OAA8B;IAE9B,MAAM,GAAG,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;IACrC,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;IAC9D,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;QACpB,MAAM,IAAI,kBAAkB,CAAC,aAAa,GAAG,2DAA2D,CAAC,CAAA;IAC1G,CAAC;IACD,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,sBAAsB,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IAC7E,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,CAAA;AAClE,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,MAAc,EACd,WAAmB,EACnB,OAAyC;IAEzC,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,CAAC,MAAM,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACrE,MAAM,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;AAClE,CAAC"}

package/dist/test-support.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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).
+ */
+export declare function makeTempDir(prefix?: string): string;
+/** Call from afterEach — removes every dir created via makeTempDir. */
+export declare function cleanupTempDirs(): void;
+export type FetchImpl = typeof globalThis.fetch;
+/**
+ * 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 declare function stubFetch(impl: (url: string, init?: RequestInit) => Promise<Response>): FetchImpl;
+export declare function jsonResponse(body: unknown, status?: number): Response;
+/** 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 declare function stubAgentDirEnv(dir: string): {
+    home: string;
+};
+/** Path of the harness's shared wizard config under a (stubbed) HOME. */
+export declare function sharedConfigPath(home: string): string;
+/** Seed the shared config.json under a stubbed HOME (creates parent dirs). */
+export declare function writeSharedConfigJson(home: string, value: unknown): string;
+/** Capture console.log / console.error; restore() in afterEach (or rely on vi.restoreAllMocks). */
+export declare function captureConsole(): {
+    lines: string[];
+    errors: string[];
+};
+//# sourceMappingURL=test-support.d.ts.map

package/dist/test-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-support.d.ts","sourceRoot":"../src/","sources":["test-support.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,wBAAgB,WAAW,CAAC,MAAM,SAAoB,GAAG,MAAM,CAI9D;AAED,uEAAuE;AACvE,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,UAAU,CAAC,KAAK,CAAA;AAE/C;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,SAAS,CAEjG;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,SAAM,GAAG,QAAQ,CAKlE;AAED,mRAAmR;AACnR,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAO7D;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAK1E;AAED,mGAAmG;AACnG,wBAAgB,cAAc,IAAI;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAUtE"}