@cat-factory/cli 0.2.2 → 0.4.0

package/dist/args.d.ts

@@ -1,9 +1,12 @@
 import { type ContainerRuntime } from './templates.js';
 import { type VcsProvider } from './vcs.js';
+/** The Kubernetes distribution `cat-factory k3s` can provision/target. */
+export declare const K3S_RUNTIMES: readonly ['k3d', 'kind', 'k3s'];
+export type K3sRuntime = (typeof K3S_RUNTIMES)[number];
 /** Parsed, validated CLI options. Unset optionals are resolved later (defaults / prompts). */
 export interface CliOptions {
-    /** The subcommand. Only `init` exists today; the default when omitted. */
-    command: 'init' | 'help' | 'version';
+    /** The subcommand. `init` (the default when omitted) or `k3s` (guided local-cluster setup). */
+    command: 'init' | 'k3s' | 'help' | 'version';
     dir?: string;
     projectName?: string;
     appTitle?: string;
@@ -15,6 +18,10 @@ export interface CliOptions {
     harnessImage?: string;
     /** Container runtime that spawns agent jobs (`LOCAL_CONTAINER_RUNTIME`). */
     containerRuntime?: ContainerRuntime;
+    /** `k3s` command: name for a provisioned local cluster. */
+    clusterName?: string;
+    /** `k3s` command: the Kubernetes distribution to provision/target. */
+    k3sRuntime?: K3sRuntime;
     /** Skip opening the browser at the token-creation URL (still prints it). */
     noOpen: boolean;
     /** Non-interactive: never prompt; use defaults/flags. Fails if a required value is missing. */
@@ -35,6 +42,8 @@ export declare const OPTION_DEFAULTS: {
     readonly port: 8787;
     readonly harnessImage: "ghcr.io/kibertoad/cat-factory-executor:latest";
     readonly containerRuntime: ContainerRuntime;
+    readonly k3sClusterName: 'cat-factory';
+    readonly k3sRuntime: K3sRuntime;
 };
-export declare const HELP_TEXT = "cat-factory \u2014 bootstrap a local cat-factory deployment\n\nUsage:\n  cat-factory [init] [options]\n\nScaffolds a local-mode backend (local/) and frontend SPA (frontend/), generates the\ncrypto secrets, mints a GitHub/GitLab personal access token (opens your browser), and\nwrites gitignored .env files.\n\nOptions:\n  -d, --dir <path>        Target directory (default: ./<name>)\n      --name <name>       Project name slug (default: cat-factory)\n      --title <title>     Frontend app title (default: Agent Architecture Board)\n      --provider <p>      Source control: github | gitlab (default: github)\n      --token <token>     PAT value (skips the browser/paste flow)\n      --db-url <url>      Postgres DATABASE_URL\n      --api-base <url>   Backend API base for the SPA (default: http://localhost:<port>)\n      --port <n>          Backend HTTP port (default: 8787; also sets the SPA's api-base)\n      --harness-image <ref>  Executor-harness image (default: ghcr.io ...:latest)\n      --container-runtime <r>  Agent container runtime: docker | podman | orbstack | colima | apple\n      --no-open           Don't open the browser (just print the token URL)\n  -y, --yes               Non-interactive: use defaults/flags, never prompt\n  -f, --force             Overwrite existing files\n  -h, --help              Show this help\n  -v, --version           Show the CLI version\n";
+export declare const HELP_TEXT = "cat-factory \u2014 bootstrap a local cat-factory deployment\n\nUsage:\n  cat-factory [init] [options]\n  cat-factory k3s [options]\n\nCommands:\n  init   Scaffold a local-mode backend (local/) + frontend SPA (frontend/): generate the\n         crypto secrets, mint a GitHub/GitLab PAT (opens your browser), write gitignored .env.\n  k3s    Guided local Kubernetes setup: probe the host for a usable cluster, then create (or\n         reuse) one + a least-privilege ServiceAccount and print the values to wire the\n         Local k3s environment handler. A k3s install needs sudo, so it is only ever printed.\n\nOptions (init):\n  -d, --dir <path>        Target directory (default: ./<name>)\n      --name <name>       Project name slug (default: cat-factory)\n      --title <title>     Frontend app title (default: Agent Architecture Board)\n      --provider <p>      Source control: github | gitlab (default: github)\n      --token <token>     PAT value (skips the browser/paste flow)\n      --db-url <url>      Postgres DATABASE_URL\n      --api-base <url>   Backend API base for the SPA (default: http://localhost:<port>)\n      --port <n>          Backend HTTP port (default: 8787; also sets the SPA's api-base)\n      --harness-image <ref>  Executor-harness image (default: ghcr.io ...:latest)\n      --container-runtime <r>  Agent container runtime: docker | podman | orbstack | colima | apple\n      --no-open           Don't open the browser (just print the token URL)\n  -y, --yes               Non-interactive: use defaults/flags, never prompt\n  -f, --force             Overwrite existing files\n  -h, --help              Show this help\n  -v, --version           Show the CLI version\n\nOptions (k3s):\n      --cluster-name <n>  Name for a provisioned local cluster (default: cat-factory)\n      --runtime <r>       Kubernetes distribution: k3d | kind | k3s (default: k3d)\n  -y, --yes               Non-interactive: pick the recommended path + skip confirms\n";
 //# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,gBAAgB,EAAyB,MAAM,gBAAgB,CAAA;AACjG,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAA;AAE1D,8FAA8F;AAC9F,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACpC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAA;IACf,+FAA+F;IAC/F,GAAG,EAAE,OAAO,CAAA;IACZ,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAA;CACf;AAQD,qBAAa,QAAS,SAAQ,KAAK;CAAG;AAEtC,mGAAmG;AACnG,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAoFpD;AAwBD,qEAAqE;AACrE,eAAO,MAAM,eAAe;aAC1B,WAAW,EAAE,aAAa;aAC1B,QAAQ,EAAE,0BAA0B;aACpC,QAAQ,EAAc,WAAW;aACjC,WAAW,EAAE,8CAA8C;aAI3D,IAAI,EAAE,IAAI;aACV,YAAY;aACZ,gBAAgB,EAAc,gBAAgB;CACtC,CAAA;AAEV,eAAO,MAAM,SAAS,k3CAyBrB,CAAA"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,gBAAgB,EAAyB,MAAM,gBAAgB,CAAA;AACjG,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,UAAU,CAAA;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,YAAY,YAAI,KAAK,EAAE,MAAM,EAAE,KAAK,CAAU,CAAA;AAC3D,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtD,8FAA8F;AAC9F,MAAM,WAAW,UAAU;IACzB,+FAA+F;IAC/F,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAA;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAA;IACf,+FAA+F;IAC/F,GAAG,EAAE,OAAO,CAAA;IACZ,oDAAoD;IACpD,KAAK,EAAE,OAAO,CAAA;CACf;AAQD,qBAAa,QAAS,SAAQ,KAAK;CAAG;AAEtC,mGAAmG;AACnG,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAgGpD;AA8BD,qEAAqE;AACrE,eAAO,MAAM,eAAe;aAC1B,WAAW,EAAE,aAAa;aAC1B,QAAQ,EAAE,0BAA0B;aACpC,QAAQ,EAAc,WAAW;aACjC,WAAW,EAAE,8CAA8C;aAI3D,IAAI,EAAE,IAAI;aACV,YAAY;aACZ,gBAAgB,EAAc,gBAAgB;aAE9C,cAAc,EAAE,aAAa;aAC7B,UAAU,EAAW,UAAU;CACvB,CAAA;AAEV,eAAO,MAAM,SAAS,y7DAkCrB,CAAA"}

package/dist/args.js

@@ -1,5 +1,7 @@
 import { CONTAINER_RUNTIMES, DEFAULT_HARNESS_IMAGE } from './templates.js';
 import { VCS_PROVIDERS } from './vcs.js';
+/** The Kubernetes distribution `cat-factory k3s` can provision/target. */
+export const K3S_RUNTIMES = ['k3d', 'kind', 'k3s'];
 const DEFAULTS = {
     noOpen: false,
     yes: false,
@@ -32,6 +34,12 @@ export function parseArgs(argv) {
                     commandSet = true;
                 }
                 break;
+            case 'k3s':
+                if (!commandSet) {
+                    opts.command = 'k3s';
+                    commandSet = true;
+                }
+                break;
             case 'help':
             case '--help':
             case '-h':
@@ -75,6 +83,12 @@ export function parseArgs(argv) {
             case '--container-runtime':
                 opts.containerRuntime = parseContainerRuntime(takeValue(flag, inline, queue));
                 break;
+            case '--cluster-name':
+                opts.clusterName = takeValue(flag, inline, queue);
+                break;
+            case '--runtime':
+                opts.k3sRuntime = parseK3sRuntime(takeValue(flag, inline, queue));
+                break;
             case '--no-open':
                 opts.noOpen = true;
                 break;
@@ -104,6 +118,12 @@ function parseContainerRuntime(value) {
         return v;
     throw new ArgError(`Invalid --container-runtime "${value}" (expected: ${CONTAINER_RUNTIMES.join(' | ')})`);
 }
+function parseK3sRuntime(value) {
+    const v = value.toLowerCase();
+    if (K3S_RUNTIMES.includes(v))
+        return v;
+    throw new ArgError(`Invalid --runtime "${value}" (expected: ${K3S_RUNTIMES.join(' | ')})`);
+}
 function parsePort(value) {
     const n = Number(value);
     if (!Number.isInteger(n) || n < 1 || n > 65535) {
@@ -123,17 +143,24 @@ export const OPTION_DEFAULTS = {
     port: 8787,
     harnessImage: DEFAULT_HARNESS_IMAGE,
     containerRuntime: 'docker',
+    // `k3s` command defaults.
+    k3sClusterName: 'cat-factory',
+    k3sRuntime: 'k3d',
 };
 export const HELP_TEXT = `cat-factory — bootstrap a local cat-factory deployment
 
 Usage:
   cat-factory [init] [options]
+  cat-factory k3s [options]
 
-Scaffolds a local-mode backend (local/) and frontend SPA (frontend/), generates the
-crypto secrets, mints a GitHub/GitLab personal access token (opens your browser), and
-writes gitignored .env files.
+Commands:
+  init   Scaffold a local-mode backend (local/) + frontend SPA (frontend/): generate the
+         crypto secrets, mint a GitHub/GitLab PAT (opens your browser), write gitignored .env.
+  k3s    Guided local Kubernetes setup: probe the host for a usable cluster, then create (or
+         reuse) one + a least-privilege ServiceAccount and print the values to wire the
+         Local k3s environment handler. A k3s install needs sudo, so it is only ever printed.
 
-Options:
+Options (init):
   -d, --dir <path>        Target directory (default: ./<name>)
       --name <name>       Project name slug (default: cat-factory)
       --title <title>     Frontend app title (default: Agent Architecture Board)
@@ -149,5 +176,10 @@ Options:
   -f, --force             Overwrite existing files
   -h, --help              Show this help
   -v, --version           Show the CLI version
+
+Options (k3s):
+      --cluster-name <n>  Name for a provisioned local cluster (default: cat-factory)
+      --runtime <r>       Kubernetes distribution: k3d | kind | k3s (default: k3d)
+  -y, --yes               Non-interactive: pick the recommended path + skip confirms
 `;
 //# sourceMappingURL=args.js.map

package/dist/args.js.map

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

package/dist/bin.js

@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { ArgError, HELP_TEXT, parseArgs } from './args.js';
 import { bootstrap } from './bootstrap.js';
+import { setupK3s } from './k3s.js';
 function readVersion() {
     try {
         const pkgUrl = new URL('../package.json', import.meta.url);
@@ -33,6 +34,10 @@ async function main() {
         process.stdout.write(`${readVersion()}\n`);
         return;
     }
+    if (options.command === 'k3s') {
+        await setupK3s(options);
+        return;
+    }
     await bootstrap(options);
 }
 main().catch((err) => {

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAA;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAyB,CAAA;QAC3F,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAA;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAA;IAChB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,IAAI,OAAO,CAAA;IACX,IAAI,CAAC;QACH,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,OAAO,SAAS,EAAE,CAAC,CAAA;YACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QAC/B,OAAM;IACR,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,EAAE,IAAI,CAAC,CAAA;QAC1C,OAAM;IACR,CAAC;IAED,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC5F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAA;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAyB,CAAA;QAC3F,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAA;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAA;IAChB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,IAAI,OAAO,CAAA;IACX,IAAI,CAAC;QACH,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;YAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,OAAO,SAAS,EAAE,CAAC,CAAA;YACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QAC/B,OAAM;IACR,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,EAAE,IAAI,CAAC,CAAA;QAC1C,OAAM;IACR,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;QAC9B,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAA;QACvB,OAAM;IACR,CAAC;IAED,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kBAAkB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC5F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/host-shell.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The result of running a host command. `code` is the process exit code; the special value
+ * {@link COMMAND_NOT_FOUND} (127) is used when the binary itself is missing (spawn `ENOENT`),
+ * so callers can distinguish "not installed" from "ran but failed".
+ */
+export interface ShellResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Conventional exit code for a missing binary — returned by {@link HostShell.run} on `ENOENT`. */
+export declare const COMMAND_NOT_FOUND = 127;
+/** Conventional exit code for a command killed by the watchdog timeout (mirrors `timeout(1)`). */
+export declare const COMMAND_TIMED_OUT = 124;
+/**
+ * Default per-command watchdog (ms). A probe must stay responsive, but some detections shell out to
+ * `kubectl`, which contacts the apiserver — a kubeconfig pointing at a down/unroutable cluster would
+ * otherwise block on the TCP/HTTP timeout. The watchdog kills such a child and reports
+ * {@link COMMAND_TIMED_OUT} so the probe treats it as "ran but failed" (not reachable), never hangs.
+ */
+export declare const DEFAULT_COMMAND_TIMEOUT_MS = 10000;
+/**
+ * Host shell-out seam. The k3s flow depends on this interface (never on `node:child_process`
+ * directly), so probing/provisioning can be driven by a fake in tests. The real implementation
+ * ({@link createNodeShell}) spawns real processes; tests inject their own. Mirrors the `Io` /
+ * `FileSystem` seams used by the `init` command.
+ */
+export interface HostShell {
+    /**
+     * Run `cmd` with `args`, capturing stdout/stderr. Resolves with the exit code — it NEVER
+     * rejects: a missing binary resolves to `{ code: COMMAND_NOT_FOUND }` so the probe can treat
+     * "not installed" uniformly, and a command that overruns `timeoutMs` is killed and resolves to
+     * `{ code: COMMAND_TIMED_OUT }`. Output is returned to the caller, never logged here.
+     *
+     * `opts.input`, when set, is written to the child's stdin and the stream is closed — used to
+     * feed a manifest to `kubectl apply -f -` WITHOUT writing it (or the token Secret it creates)
+     * to a temp file on disk.
+     */
+    run(cmd: string, args: string[], opts?: {
+        timeoutMs?: number;
+        input?: string;
+    }): Promise<ShellResult>;
+}
+/** The real, process-backed {@link HostShell}. */
+export declare function createNodeShell(): HostShell;
+//# sourceMappingURL=host-shell.d.ts.map

package/dist/host-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-shell.d.ts","sourceRoot":"","sources":["../src/host-shell.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC,kGAAkG;AAClG,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;OASG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC,WAAW,CAAC,CAAA;CACxB;AAED,kDAAkD;AAClD,wBAAgB,eAAe,IAAI,SAAS,CA2D3C"}

package/dist/host-shell.js

@@ -0,0 +1,73 @@
+import { spawn } from 'node:child_process';
+/** Conventional exit code for a missing binary — returned by {@link HostShell.run} on `ENOENT`. */
+export const COMMAND_NOT_FOUND = 127;
+/** Conventional exit code for a command killed by the watchdog timeout (mirrors `timeout(1)`). */
+export const COMMAND_TIMED_OUT = 124;
+/**
+ * Default per-command watchdog (ms). A probe must stay responsive, but some detections shell out to
+ * `kubectl`, which contacts the apiserver — a kubeconfig pointing at a down/unroutable cluster would
+ * otherwise block on the TCP/HTTP timeout. The watchdog kills such a child and reports
+ * {@link COMMAND_TIMED_OUT} so the probe treats it as "ran but failed" (not reachable), never hangs.
+ */
+export const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+/** The real, process-backed {@link HostShell}. */
+export function createNodeShell() {
+    return {
+        run(cmd, args, opts) {
+            const timeoutMs = opts?.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+            return new Promise((resolve) => {
+                let stdout = '';
+                let stderr = '';
+                let settled = false;
+                let timer;
+                const finish = (result) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    if (timer)
+                        clearTimeout(timer);
+                    resolve(result);
+                };
+                // Feed stdin only when there's input; otherwise leave it closed (`ignore`).
+                const stdin = opts?.input !== undefined ? 'pipe' : 'ignore';
+                let child;
+                try {
+                    child = spawn(cmd, args, { stdio: [stdin, 'pipe', 'pipe'] });
+                }
+                catch {
+                    finish({ code: COMMAND_NOT_FOUND, stdout: '', stderr: `${cmd}: not found` });
+                    return;
+                }
+                if (opts?.input !== undefined && child.stdin) {
+                    // A child that exits before draining stdin raises EPIPE on the write; swallow it so a
+                    // fast-failing command surfaces as its exit code, not an unhandled stream error.
+                    child.stdin.on('error', () => { });
+                    child.stdin.end(opts.input);
+                }
+                // Watchdog: kill a child that runs past the deadline (e.g. `kubectl` stuck dialing an
+                // unreachable apiserver) and report it as timed-out rather than blocking the probe forever.
+                timer = setTimeout(() => {
+                    child.kill('SIGKILL');
+                    finish({ code: COMMAND_TIMED_OUT, stdout, stderr: stderr || `${cmd}: timed out` });
+                }, timeoutMs);
+                timer.unref?.();
+                child.stdout?.on('data', (chunk) => {
+                    stdout += chunk.toString();
+                });
+                child.stderr?.on('data', (chunk) => {
+                    stderr += chunk.toString();
+                });
+                child.on('error', (err) => {
+                    // ENOENT ⇒ the binary is missing; anything else ⇒ a genuine spawn failure. Both are
+                    // surfaced as a non-zero result rather than a throw so the caller stays branch-free.
+                    const code = err.code === 'ENOENT' ? COMMAND_NOT_FOUND : 1;
+                    finish({ code, stdout, stderr: stderr || err.message });
+                });
+                child.on('close', (code) => {
+                    finish({ code: code ?? 1, stdout, stderr });
+                });
+            });
+        },
+    };
+}
+//# sourceMappingURL=host-shell.js.map

package/dist/host-shell.js.map

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

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-export { type CliOptions, HELP_TEXT, OPTION_DEFAULTS, parseArgs, ArgError } from './args.js';
+export { type CliOptions, HELP_TEXT, K3S_RUNTIMES, type K3sRuntime, OPTION_DEFAULTS, parseArgs, ArgError, } from './args.js';
 export { bootstrap, type BootstrapDeps, type FileSystem, BootstrapError } from './bootstrap.js';
+export { COMMAND_NOT_FOUND, COMMAND_TIMED_OUT, createNodeShell, DEFAULT_COMMAND_TIMEOUT_MS, type HostShell, type ShellResult, } from './host-shell.js';
+export { K3S_INSTALL_COMMAND, type K3sDeps, type K3sResult, setupK3s } from './k3s.js';
+export { classifyHost, hasServerVersion, type HostDetections, type HostState, type Offer, type OfferId, parseK3dClusters, parseKindClusters, probeHost, type ToolDetection, } from './k3s-probe.js';
 export { buildFrontendEnv, buildLocalEnv, type EnvEntry, type FrontendEnvInput, type LocalEnvInput, renderEnvFile, } from './env.js';
 export { buildGitignore, mergeGitignore, REQUIRED_GITIGNORE_RULES } from './gitignore.js';
 export { type Io, createConsoleIo } from './io.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC5F,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/F,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AACzF,OAAO,EAAE,KAAK,EAAE,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,KAAK,cAAc,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5E,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACjG,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,EACb,KAAK,WAAW,GACjB,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,UAAU,EACf,SAAS,EACT,YAAY,EACZ,KAAK,UAAU,EACf,eAAe,EACf,SAAS,EACT,QAAQ,GACT,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/F,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,0BAA0B,EAC1B,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,mBAAmB,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACtF,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,KAAK,EACV,KAAK,OAAO,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AACzF,OAAO,EAAE,KAAK,EAAE,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,KAAK,cAAc,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAC5E,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAA;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACjG,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,EACb,KAAK,WAAW,GACjB,MAAM,UAAU,CAAA"}

package/dist/index.js

@@ -1,7 +1,10 @@
 // Public, programmatic API of @cat-factory/cli. The `cat-factory` command (bin.ts) is a thin
 // shell over these; they are also exported so the bootstrap can be embedded in other tooling.
-export { HELP_TEXT, OPTION_DEFAULTS, parseArgs, ArgError } from './args.js';
+export { HELP_TEXT, K3S_RUNTIMES, OPTION_DEFAULTS, parseArgs, ArgError, } from './args.js';
 export { bootstrap, BootstrapError } from './bootstrap.js';
+export { COMMAND_NOT_FOUND, COMMAND_TIMED_OUT, createNodeShell, DEFAULT_COMMAND_TIMEOUT_MS, } from './host-shell.js';
+export { K3S_INSTALL_COMMAND, setupK3s } from './k3s.js';
+export { classifyHost, hasServerVersion, parseK3dClusters, parseKindClusters, probeHost, } from './k3s-probe.js';
 export { buildFrontendEnv, buildLocalEnv, renderEnvFile, } from './env.js';
 export { buildGitignore, mergeGitignore, REQUIRED_GITIGNORE_RULES } from './gitignore.js';
 export { createConsoleIo } from './io.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,8FAA8F;AAC9F,OAAO,EAAmB,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC5F,OAAO,EAAE,SAAS,EAAuC,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/F,OAAO,EACL,gBAAgB,EAChB,aAAa,EAIb,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AACzF,OAAO,EAAW,eAAe,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAuB,SAAS,EAAoB,MAAM,WAAW,CAAA;AAC5E,OAAO,EAAE,eAAe,EAA2C,MAAM,cAAc,CAAA;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAyB,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACjG,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,GAEd,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,8FAA8F;AAC9F,OAAO,EAEL,SAAS,EACT,YAAY,EAEZ,eAAe,EACf,SAAS,EACT,QAAQ,GACT,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,SAAS,EAAuC,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC/F,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,0BAA0B,GAG3B,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,mBAAmB,EAAgC,QAAQ,EAAE,MAAM,UAAU,CAAA;AACtF,OAAO,EACL,YAAY,EACZ,gBAAgB,EAKhB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,GAEV,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,gBAAgB,EAChB,aAAa,EAIb,aAAa,GACd,MAAM,UAAU,CAAA;AACjB,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AACzF,OAAO,EAAW,eAAe,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAuB,SAAS,EAAoB,MAAM,WAAW,CAAA;AAC5E,OAAO,EAAE,eAAe,EAA2C,MAAM,cAAc,CAAA;AACvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAyB,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACjG,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,GAEd,MAAM,UAAU,CAAA"}

package/dist/k3s-probe.d.ts

@@ -0,0 +1,69 @@
+import { type K3sRuntime } from './args.js';
+import { type HostShell } from './host-shell.js';
+/** Whether a host CLI is installed, and its reported version string when detectable. */
+export interface ToolDetection {
+    installed: boolean;
+    version?: string;
+}
+/**
+ * The raw facts detected about the host, produced by {@link probeHost} and consumed by the pure
+ * {@link classifyHost}. Kept as plain data so classification is unit-testable with no shell.
+ */
+export interface HostDetections {
+    kubectl: ToolDetection;
+    k3d: ToolDetection;
+    kind: ToolDetection;
+    k3s: ToolDetection;
+    docker: {
+        installed: boolean;
+        running: boolean;
+    };
+    /** A cluster is reachable via the current kubeconfig (apiserver answered a version request). */
+    reachableCluster: boolean;
+    /** The current kubeconfig context name, when one is set. */
+    clusterContext?: string;
+    /** Names of existing k3d-managed clusters (Docker). */
+    k3dClusters: string[];
+    /** Names of existing kind-managed clusters (Docker). */
+    kindClusters: string[];
+}
+/** The setup paths the probe can offer. */
+export type OfferId = 'use-existing' | 'create-k3d' | 'create-kind' | 'install-k3s';
+/** One offered setup path, with whether it's currently possible + why not. */
+export interface Offer {
+    id: OfferId;
+    label: string;
+    available: boolean;
+    recommended: boolean;
+    /** When `available` is false, a short reason the UI can show. */
+    reason?: string;
+}
+/** The classified host state: the raw detections plus the offered paths and the recommendation. */
+export interface HostState {
+    detections: HostDetections;
+    offers: Offer[];
+    recommended: OfferId;
+}
+/**
+ * Classify the host from its detected facts into the offered setup paths. Pure — no IO — so it's
+ * the primary unit-test target. `recommended` is the highest-priority AVAILABLE offer for the
+ * `preferred` runtime (default `k3d`, the no-root Docker path).
+ */
+export declare function classifyHost(d: HostDetections, preferred?: K3sRuntime): HostState;
+/** Parse `k3d cluster list --output json` (an array of `{ name }`) into cluster names. */
+export declare function parseK3dClusters(stdout: string): string[];
+/** Parse `kind get clusters` (newline-separated names; a "No kind clusters" note ⇒ empty). */
+export declare function parseKindClusters(stdout: string): string[];
+/** Detect whether a `kubectl version --output=json` payload reports a reachable apiserver. */
+export declare function hasServerVersion(stdout: string): boolean;
+/**
+ * Probe the host over the {@link HostShell} seam and classify it for the `preferred` runtime. Runs
+ * each tool's detection command, treats {@link COMMAND_NOT_FOUND} as "not installed", and folds the
+ * results through the pure {@link classifyHost}. Tested with a scripted fake shell.
+ *
+ * `kubectl version` / `config current-context` contact the apiserver, so they carry an explicit
+ * `--request-timeout` — a kubeconfig pointing at a down cluster then fails fast instead of hanging
+ * the probe (the {@link HostShell} watchdog is the outer backstop).
+ */
+export declare function probeHost(shell: HostShell, preferred?: K3sRuntime): Promise<HostState>;
+//# sourceMappingURL=k3s-probe.d.ts.map

package/dist/k3s-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"k3s-probe.d.ts","sourceRoot":"","sources":["../src/k3s-probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEnE,wFAAwF;AACxF,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,aAAa,CAAA;IACtB,GAAG,EAAE,aAAa,CAAA;IAClB,IAAI,EAAE,aAAa,CAAA;IACnB,GAAG,EAAE,aAAa,CAAA;IAClB,MAAM,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IAChD,gGAAgG;IAChG,gBAAgB,EAAE,OAAO,CAAA;IACzB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,wDAAwD;IACxD,YAAY,EAAE,MAAM,EAAE,CAAA;CACvB;AAED,2CAA2C;AAC3C,MAAM,MAAM,OAAO,GAAG,cAAc,GAAG,YAAY,GAAG,aAAa,GAAG,aAAa,CAAA;AAEnF,8EAA8E;AAC9E,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,OAAO,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,OAAO,CAAA;IAClB,WAAW,EAAE,OAAO,CAAA;IACpB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,mGAAmG;AACnG,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,cAAc,CAAA;IAC1B,MAAM,EAAE,KAAK,EAAE,CAAA;IACf,WAAW,EAAE,OAAO,CAAA;CACrB;AAmBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,cAAc,EAAE,SAAS,GAAE,UAAkB,GAAG,SAAS,CAsDxF;AAgBD,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAYzD;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAK1D;AAED,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOxD;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,SAAS,EAChB,SAAS,GAAE,UAAkB,GAC5B,OAAO,CAAC,SAAS,CAAC,CA0CpB"}

package/dist/k3s-probe.js

@@ -0,0 +1,154 @@
+import {} from './args.js';
+import { COMMAND_NOT_FOUND } from './host-shell.js';
+/**
+ * Priority order for picking the recommendation, given the user's preferred runtime. A live cluster
+ * always wins; otherwise the preferred distribution's create/install path is tried first, then the
+ * others as fallbacks. Every list ends with `install-k3s`, which is always available.
+ */
+function offerPriority(preferred) {
+    switch (preferred) {
+        case 'kind':
+            return ['use-existing', 'create-kind', 'create-k3d', 'install-k3s'];
+        case 'k3s':
+            // An explicit k3s preference favours the guided single-node install over the Docker paths.
+            return ['use-existing', 'install-k3s', 'create-k3d', 'create-kind'];
+        default:
+            return ['use-existing', 'create-k3d', 'create-kind', 'install-k3s'];
+    }
+}
+/**
+ * Classify the host from its detected facts into the offered setup paths. Pure — no IO — so it's
+ * the primary unit-test target. `recommended` is the highest-priority AVAILABLE offer for the
+ * `preferred` runtime (default `k3d`, the no-root Docker path).
+ */
+export function classifyHost(d, preferred = 'k3d') {
+    const useExisting = {
+        id: 'use-existing',
+        label: d.clusterContext
+            ? `Use the existing cluster (context: ${d.clusterContext})`
+            : 'Use the existing reachable cluster',
+        available: d.reachableCluster,
+        recommended: false,
+        reason: d.reachableCluster ? undefined : 'No cluster is reachable via your kubeconfig',
+    };
+    const dockerReason = !d.docker.installed
+        ? 'Docker is not installed'
+        : !d.docker.running
+            ? 'Docker is not running'
+            : undefined;
+    const createK3d = {
+        id: 'create-k3d',
+        label: 'Create a local k3d cluster (Docker, no root)',
+        available: d.docker.running && d.k3d.installed,
+        recommended: false,
+        reason: dockerReason ?? (!d.k3d.installed ? 'k3d is not installed (https://k3d.io)' : undefined),
+    };
+    const createKind = {
+        id: 'create-kind',
+        label: 'Create a local kind cluster (Docker, no root)',
+        available: d.docker.running && d.kind.installed,
+        recommended: false,
+        reason: dockerReason ??
+            (!d.kind.installed ? 'kind is not installed (https://kind.sigs.k8s.io)' : undefined),
+    };
+    // The guided k3s path is always available: when k3s is already installed it only points the user
+    // at starting the service; otherwise it PRINTS the install command (needs sudo). Never auto-runs.
+    const installK3s = {
+        id: 'install-k3s',
+        label: d.k3s.installed
+            ? 'Start your already-installed k3s (needs sudo — not run for you)'
+            : 'Show the k3s install command (needs sudo — not run for you)',
+        available: true,
+        recommended: false,
+    };
+    const offers = [useExisting, createK3d, createKind, installK3s];
+    const recommended = offerPriority(preferred).find((id) => offers.find((o) => o.id === id)?.available) ??
+        'install-k3s';
+    for (const o of offers)
+        o.recommended = o.id === recommended;
+    return { detections: d, offers, recommended };
+}
+/** True when a `run` result indicates the binary exists (it ran, even if the subcommand failed). */
+function isInstalled(code) {
+    return code !== COMMAND_NOT_FOUND;
+}
+/** First non-empty trimmed line of a command's stdout (used for `--version` style output). */
+function firstLine(stdout) {
+    const line = stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    return line && line.length > 0 ? line : undefined;
+}
+/** Parse `k3d cluster list --output json` (an array of `{ name }`) into cluster names. */
+export function parseK3dClusters(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .map((c) => typeof c === 'object' && c !== null ? c.name : undefined)
+            .filter((n) => typeof n === 'string' && n.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/** Parse `kind get clusters` (newline-separated names; a "No kind clusters" note ⇒ empty). */
+export function parseKindClusters(stdout) {
+    return stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && !l.toLowerCase().startsWith('no kind clusters'));
+}
+/** Detect whether a `kubectl version --output=json` payload reports a reachable apiserver. */
+export function hasServerVersion(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return typeof parsed.serverVersion === 'object' && parsed.serverVersion !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Probe the host over the {@link HostShell} seam and classify it for the `preferred` runtime. Runs
+ * each tool's detection command, treats {@link COMMAND_NOT_FOUND} as "not installed", and folds the
+ * results through the pure {@link classifyHost}. Tested with a scripted fake shell.
+ *
+ * `kubectl version` / `config current-context` contact the apiserver, so they carry an explicit
+ * `--request-timeout` — a kubeconfig pointing at a down cluster then fails fast instead of hanging
+ * the probe (the {@link HostShell} watchdog is the outer backstop).
+ */
+export async function probeHost(shell, preferred = 'k3d') {
+    const [kubectlVersion, kubectlContext, k3dVersion, k3dList, kindVersion, kindList, k3sVersion, dockerVersion,] = await Promise.all([
+        shell.run('kubectl', ['version', '--output=json', '--request-timeout=3s']),
+        shell.run('kubectl', ['config', 'current-context']),
+        shell.run('k3d', ['version']),
+        shell.run('k3d', ['cluster', 'list', '--output', 'json']),
+        shell.run('kind', ['version']),
+        shell.run('kind', ['get', 'clusters']),
+        shell.run('k3s', ['--version']),
+        shell.run('docker', ['version', '--format', '{{.Server.Version}}']),
+    ]);
+    const context = kubectlContext.code === 0 ? firstLine(kubectlContext.stdout) : undefined;
+    const detections = {
+        kubectl: {
+            installed: isInstalled(kubectlVersion.code),
+            version: firstLine(kubectlVersion.stdout),
+        },
+        k3d: { installed: isInstalled(k3dVersion.code), version: firstLine(k3dVersion.stdout) },
+        kind: { installed: isInstalled(kindVersion.code), version: firstLine(kindVersion.stdout) },
+        k3s: { installed: isInstalled(k3sVersion.code), version: firstLine(k3sVersion.stdout) },
+        docker: {
+            installed: isInstalled(dockerVersion.code),
+            running: dockerVersion.code === 0 && firstLine(dockerVersion.stdout) !== undefined,
+        },
+        reachableCluster: kubectlVersion.code === 0 && hasServerVersion(kubectlVersion.stdout),
+        clusterContext: context,
+        k3dClusters: k3dList.code === 0 ? parseK3dClusters(k3dList.stdout) : [],
+        kindClusters: kindList.code === 0 ? parseKindClusters(kindList.stdout) : [],
+    };
+    return classifyHost(detections, preferred);
+}
+//# sourceMappingURL=k3s-probe.js.map

package/dist/k3s-probe.js.map

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