@cat-factory/cli 0.10.5 → 0.11.0

package/README.md

@@ -45,6 +45,14 @@ It does the fiddly setup for you:
   is **not** needed to boot; add providers/keys through the UI after sign-in (the `.env` leaves
   them as commented hints), so the generated file runs local mode with no manual edits.
 - **`cat-factory k3s`**: guided local Kubernetes setup for ephemeral environments (see `--help`).
+  It probes the host, creates or reuses a cluster, applies a least-privilege ServiceAccount, mints a
+  token, and hands the values to the SPA's connect form. It also CHECKS, rather than assumes, whether
+  the cluster can serve an ingress-derived environment URL: that needs an ingress controller inside
+  the cluster and a host port published into it (`--ingress-port`, default 80). When either is
+  missing the summary says so and names the fix instead of printing a host template that resolves to
+  nothing. A published host port is fixed when the cluster is created, so `--recreate` destroys the
+  named k3d/kind cluster and builds it again from the current flags. It names what is on the cluster
+  before deleting it, and `-y` on its own never selects it.
 - **`cat-factory supervise`**: run a dev command under a self-healing watchdog (see
   [Supervising local dev](#supervising-local-dev)).
 

package/dist/args.d.ts

@@ -32,6 +32,21 @@ export interface CliOptions {
     clusterName?: string;
     /** `k3s` command: the Kubernetes distribution to provision/target. */
     k3sRuntime?: K3sRuntime;
+    /**
+     * `k3s` command: host port published into the cluster's ingress controller, so an
+     * ingress-template environment URL resolves to something. Fixed at cluster-create time.
+     */
+    ingressPort?: number;
+    /**
+     * `k3s` command: DESTROY the named local cluster and build it again from the current flags.
+     *
+     * A flag rather than a subcommand because everything a recreate needs (`--cluster-name`,
+     * `--runtime`, `--ingress-port`) is already `k3s`'s own option surface, and the flow around it
+     * (probe, RBAC, token, hand-off) is byte-for-byte the create path's: a subcommand would be the
+     * same command with one step in front of it. It is also what makes destructive intent EXPLICIT
+     * rather than inferred, since `--yes` alone can never select a recreate.
+     */
+    recreate?: boolean;
     /** `k3s` command: base URL of the running SPA, opened (deep-linked) to wire the handler. */
     appUrl?: string;
     /** `supervise` command: the command to run and keep alive — everything after `--`. */
@@ -75,5 +90,5 @@ export declare const OPTION_DEFAULTS: {
     readonly appUrl: 'http://localhost:3000';
     readonly healthPath: '/health';
 };
-export declare const HELP_TEXT = "cat-factory \u2014 bootstrap a local cat-factory deployment\n\nUsage:\n  cat-factory [init] [options]\n  cat-factory env [options]\n  cat-factory k3s [options]\n  cat-factory supervise [options] -- <command...>\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  env    Generate ONLY a ready-to-run local-mode .env in the current dir (or --dir): all three\n         crypto secrets, a minted GitHub/GitLab PAT, and the execution mode \u2014 so local mode\n         boots with no manual edits. Use it in an existing deployment dir (e.g. deploy/local).\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  supervise  Run a dev command under a self-healing watchdog. 'node --watch' PARKS on crash\n         (it restarts only on a file change), so a laptop sleep leaves the server dead with\n         the port unbound and the SPA showing only \"can't reach backend\" \u2014 indefinitely. This\n         probes the real signal (port listening AND /health 200), notices a resume, brings the\n         database/cluster back, and restarts the command.\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>  Pin the executor-harness image (default: unset \u2014 the backend runs the version it was built against)\n      --container-runtime <r>  Agent container runtime: docker | podman | orbstack | colima | apple\n      --execution-mode <m>  How agents run: pool (Docker container pool) | native (host CLI)\n      --native-harnesses <l>  Native mode: harnesses to run natively (claude-code,codex)\n      --harness-entry <p>  Native mode: path to the executor-harness server entry\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 (env):\n  -d, --dir <path>        Directory to write .env into (default: current directory)\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      --port <n>          Backend HTTP port (default: 8787)\n      --harness-image <ref>  Pin the executor-harness image (default: unset \u2014 the backend runs the version it was built against)\n      --container-runtime <r>  Agent container runtime: docker | podman | orbstack | colima | apple\n      --execution-mode <m>  How agents run: pool (Docker container pool) | native (host CLI)\n      --native-harnesses <l>  Native mode: harnesses to run natively (claude-code,codex)\n      --harness-entry <p>  Native mode: path to the executor-harness server entry\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 an existing .env\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      --app-url <url>     SPA base URL to deep-link for wiring (default: http://localhost:3000)\n      --no-open           Don't open the browser at the pre-filled connect form (still prints it)\n  -y, --yes               Non-interactive: pick the recommended path + skip confirms\n\n  After provisioning, the values are printed and the SPA's Local k3s connect form is opened\n  pre-filled (paste the token, then Test -> Save). A hands-free --register flag that POSTs the\n  handler to the local API directly is a planned follow-up.\n\nOptions (supervise):\n      --port <n>          Port the supervised server binds (default: 8787)\n      --health-path <p>   Health endpoint probed on that port (default: /health)\n  -d, --dir <path>        Working directory for the command (default: current directory)\n      --compose-service <s>  docker compose service to keep up (e.g. postgres)\n      --compose-dir <path>   Directory holding docker-compose.yml (default: --dir)\n      --k3s-cluster <name>   Local k3d/kind cluster to keep running (started if stopped)\n      --runtime <r>       Cluster distribution for --k3s-cluster: k3d | kind (default: k3d).\n                          'k3s' is refused: a host service has no cluster to start from here.\n      --poll <seconds>    Health probe interval, whole seconds (default: 10)\n      --boot-grace <seconds>  Ignore failures for this long after a (re)start (default: 60)\n      --failures <n>      Consecutive failed probes before repairing (default: 3)\n\n  Everything after `--` is the supervised command, passed through untouched:\n      cat-factory supervise --compose-service postgres -- pnpm dev\n\n  A cluster that is merely STOPPED is started automatically. A cluster whose restart is blocked\n  by a stale cgroup (\"device or resource busy\" \u2014 a state a suspend can leave behind) cannot be\n  fixed from here: clearing it needs the container ENGINE restarted, which would kill every other\n  container. That case is reported once, with the fix, instead of retried forever.\n\n  The same rule applies to the supervised command itself: restarts that never reach a serving\n  state are capped, and hitting the cap reports why and exits NON-ZERO rather than looping. A\n  command that is simply broken cannot be repaired by killing it again.\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 env [options]\n  cat-factory k3s [options]\n  cat-factory supervise [options] -- <command...>\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  env    Generate ONLY a ready-to-run local-mode .env in the current dir (or --dir): all three\n         crypto secrets, a minted GitHub/GitLab PAT, and the execution mode \u2014 so local mode\n         boots with no manual edits. Use it in an existing deployment dir (e.g. deploy/local).\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  supervise  Run a dev command under a self-healing watchdog. 'node --watch' PARKS on crash\n         (it restarts only on a file change), so a laptop sleep leaves the server dead with\n         the port unbound and the SPA showing only \"can't reach backend\" \u2014 indefinitely. This\n         probes the real signal (port listening AND /health 200), notices a resume, brings the\n         database/cluster back, and restarts the command.\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>  Pin the executor-harness image (default: unset \u2014 the backend runs the version it was built against)\n      --container-runtime <r>  Agent container runtime: docker | podman | orbstack | colima | apple\n      --execution-mode <m>  How agents run: pool (Docker container pool) | native (host CLI)\n      --native-harnesses <l>  Native mode: harnesses to run natively (claude-code,codex)\n      --harness-entry <p>  Native mode: path to the executor-harness server entry\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 (env):\n  -d, --dir <path>        Directory to write .env into (default: current directory)\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      --port <n>          Backend HTTP port (default: 8787)\n      --harness-image <ref>  Pin the executor-harness image (default: unset \u2014 the backend runs the version it was built against)\n      --container-runtime <r>  Agent container runtime: docker | podman | orbstack | colima | apple\n      --execution-mode <m>  How agents run: pool (Docker container pool) | native (host CLI)\n      --native-harnesses <l>  Native mode: harnesses to run natively (claude-code,codex)\n      --harness-entry <p>  Native mode: path to the executor-harness server entry\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 an existing .env\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      --ingress-port <n>  Host port published into the cluster's ingress controller (default: 80).\n                          Fixed when the cluster is created: changing it needs --recreate.\n      --recreate          DESTROY the named k3d/kind cluster and build it again from these flags.\n                          Names what is on it first and asks before deleting. Never selected for\n                          you: -y alone cannot pick this path.\n      --app-url <url>     SPA base URL to deep-link for wiring (default: http://localhost:3000)\n      --no-open           Don't open the browser at the pre-filled connect form (still prints it)\n  -y, --yes               Non-interactive: pick the recommended path + skip confirms\n\n  After provisioning, the values are printed and the SPA's Local k3s connect form is opened\n  pre-filled (paste the token, then Test -> Save). A hands-free --register flag that POSTs the\n  handler to the local API directly is a planned follow-up.\n\n  Ingress-derived environment URLs need TWO things, and both are checked rather than assumed: an\n  ingress controller in the cluster, and a host port published into it. A published host port\n  cannot be added to a running k3d/kind cluster, which is what --recreate is for.\n\nOptions (supervise):\n      --port <n>          Port the supervised server binds (default: 8787)\n      --health-path <p>   Health endpoint probed on that port (default: /health)\n  -d, --dir <path>        Working directory for the command (default: current directory)\n      --compose-service <s>  docker compose service to keep up (e.g. postgres)\n      --compose-dir <path>   Directory holding docker-compose.yml (default: --dir)\n      --k3s-cluster <name>   Local k3d/kind cluster to keep running (started if stopped)\n      --runtime <r>       Cluster distribution for --k3s-cluster: k3d | kind (default: k3d).\n                          'k3s' is refused: a host service has no cluster to start from here.\n      --poll <seconds>    Health probe interval, whole seconds (default: 10)\n      --boot-grace <seconds>  Ignore failures for this long after a (re)start (default: 60)\n      --failures <n>      Consecutive failed probes before repairing (default: 3)\n\n  Everything after `--` is the supervised command, passed through untouched:\n      cat-factory supervise --compose-service postgres -- pnpm dev\n\n  A cluster that is merely STOPPED is started automatically. A cluster whose restart is blocked\n  by a stale cgroup (\"device or resource busy\" \u2014 a state a suspend can leave behind) cannot be\n  fixed from here: clearing it needs the container ENGINE restarted, which would kill every other\n  container. That case is reported once, with the fix, instead of retried forever.\n\n  The same rule applies to the supervised command itself: restarts that never reach a serving\n  state are capped, and hitting the cap reports why and exits NON-ZERO rather than looping. A\n  command that is simply broken cannot be repaired by killing it again.\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,EAEL,KAAK,gBAAgB,EAErB,KAAK,aAAa,EAElB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAA;AACvB,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;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,CAAA;IAClE,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,uFAAuF;IACvF,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,4FAA4F;IAC5F,eAAe,CAAC,EAAE,aAAa,EAAE,CAAA;IACjC,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC3B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,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,CAiCpD;AAwRD,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;aAGV,gBAAgB,EAAc,gBAAgB;aAC9C,aAAa,EAAY,aAAa;aAEtC,cAAc,EAAE,aAAa;aAC7B,UAAU,EAAW,UAAU;aAG/B,MAAM,EAAE,uBAAuB;aAE/B,UAAU,EAAE,SAAS;CACb,CAAA;AAEV,eAAO,MAAM,SAAS,yvMA6FrB,CAAA"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,aAAa,EAElB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAA;AACvB,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;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,WAAW,GAAG,MAAM,GAAG,SAAS,CAAA;IAClE,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,uFAAuF;IACvF,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,4FAA4F;IAC5F,eAAe,CAAC,EAAE,aAAa,EAAE,CAAA;IACjC,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC3B,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,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,CAiCpD;AA6SD,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;aAGV,gBAAgB,EAAc,gBAAgB;aAC9C,aAAa,EAAY,aAAa;aAEtC,cAAc,EAAE,aAAa;aAC7B,UAAU,EAAW,UAAU;aAG/B,MAAM,EAAE,uBAAuB;aAE/B,UAAU,EAAE,SAAS;CACb,CAAA;AAEV,eAAO,MAAM,SAAS,o9NAsGrB,CAAA"}

package/dist/args.js

@@ -104,11 +104,44 @@ function applyCommandToken(flag, opts, commandSet) {
             return { handled: false, commandSet };
     }
 }
+/**
+ * The flags that name a local Kubernetes CLUSTER: which one, how it is built, and how the SPA is
+ * reached to wire it. Split out of {@link applyOptionFlag} so the one table stays under the
+ * complexity ratchet, and because they are the group that grows together (`--ingress-port` and
+ * `--recreate` arrived as a pair with the ingress work). Returns `false` for anything not its own.
+ */
+function applyClusterFlag(flag, opts, take) {
+    switch (flag) {
+        case '--cluster-name':
+            opts.clusterName = take(flag);
+            break;
+        case '--runtime':
+            opts.k3sRuntime = parseK3sRuntime(take(flag));
+            break;
+        case '--ingress-port':
+            opts.ingressPort = parsePort(take(flag), flag);
+            break;
+        case '--recreate':
+            opts.recreate = true;
+            break;
+        case '--app-url':
+            opts.appUrl = parseAppUrl(take(flag));
+            break;
+        case '--k3s-cluster':
+            opts.k3sCluster = take(flag);
+            break;
+        default:
+            return false;
+    }
+    return true;
+}
 /**
  * Apply a single option flag, consuming its value from the queue (via `take`) where one is
  * required. Returns `false` for an unrecognised flag so the caller can raise the error.
  */
 function applyOptionFlag(flag, opts, take) {
+    if (applyClusterFlag(flag, opts, take))
+        return true;
     switch (flag) {
         case '--dir':
         case '-d':
@@ -150,15 +183,6 @@ function applyOptionFlag(flag, opts, take) {
         case '--harness-entry':
             opts.harnessEntry = take(flag);
             break;
-        case '--cluster-name':
-            opts.clusterName = take(flag);
-            break;
-        case '--runtime':
-            opts.k3sRuntime = parseK3sRuntime(take(flag));
-            break;
-        case '--app-url':
-            opts.appUrl = parseAppUrl(take(flag));
-            break;
         case '--health-path':
             opts.healthPath = parseHealthPath(take(flag));
             break;
@@ -168,9 +192,6 @@ function applyOptionFlag(flag, opts, take) {
         case '--compose-service':
             opts.composeService = take(flag);
             break;
-        case '--k3s-cluster':
-            opts.k3sCluster = take(flag);
-            break;
         case '--poll':
             opts.pollSeconds = parseWholeSeconds(flag, take(flag), 1);
             break;
@@ -270,10 +291,10 @@ function parseFailures(value) {
     }
     return n;
 }
-function parsePort(value) {
+function parsePort(value, flag = '--port') {
     const n = Number(value);
     if (!Number.isInteger(n) || n < 1 || n > 65535) {
-        throw new ArgError(`Invalid --port "${value}" (expected an integer 1-65535)`);
+        throw new ArgError(`Invalid ${flag} "${value}" (expected an integer 1-65535)`);
     }
     return n;
 }
@@ -380,6 +401,11 @@ Options (env):
 Options (k3s):
       --cluster-name <n>  Name for a provisioned local cluster (default: cat-factory)
       --runtime <r>       Kubernetes distribution: k3d | kind | k3s (default: k3d)
+      --ingress-port <n>  Host port published into the cluster's ingress controller (default: 80).
+                          Fixed when the cluster is created: changing it needs --recreate.
+      --recreate          DESTROY the named k3d/kind cluster and build it again from these flags.
+                          Names what is on it first and asks before deleting. Never selected for
+                          you: -y alone cannot pick this path.
       --app-url <url>     SPA base URL to deep-link for wiring (default: http://localhost:3000)
       --no-open           Don't open the browser at the pre-filled connect form (still prints it)
   -y, --yes               Non-interactive: pick the recommended path + skip confirms
@@ -388,6 +414,10 @@ Options (k3s):
   pre-filled (paste the token, then Test -> Save). A hands-free --register flag that POSTs the
   handler to the local API directly is a planned follow-up.
 
+  Ingress-derived environment URLs need TWO things, and both are checked rather than assumed: an
+  ingress controller in the cluster, and a host port published into it. A published host port
+  cannot be added to a running k3d/kind cluster, which is what --recreate is for.
+
 Options (supervise):
       --port <n>          Port the supervised server binds (default: 8787)
       --health-path <p>   Health endpoint probed on that port (default: /health)

package/dist/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAElB,eAAe,EAEf,gBAAgB,GAEjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,aAAa,EAAoB,MAAM,UAAU,CAAA;AAE1D,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAU,CAAA;AA0D3D,MAAM,QAAQ,GAAG;IACf,MAAM,EAAE,KAAK;IACb,GAAG,EAAE,KAAK;IACV,KAAK,EAAE,KAAK;CACJ,CAAA;AAEV,MAAM,OAAO,QAAS,SAAQ,KAAK;CAAG;AAEtC,mGAAmG;AACnG,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,MAAM,IAAI,GAAe,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAA;IACzD,IAAI,UAAU,GAAG,KAAK,CAAA;IAEtB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;IACvB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,EAAY,CAAA;QAEnC,8FAA8F;QAC9F,0DAA0D;QAC1D,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,IAAI,CAAC,gBAAgB,GAAG,CAAC,GAAG,KAAK,CAAC,CAAA;YAClC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAA;YAChB,MAAK;QACP,CAAC;QAED,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;QACvE,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QAEhF,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,CAAA;QACzD,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpB,UAAU,GAAG,OAAO,CAAC,UAAU,CAAA;YAC/B,SAAQ;QACV,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAA;QACrE,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,QAAQ,CAAC,qBAAqB,GAAG,EAAE,CAAC,CAAA;QAChD,CAAC;IACH,CAAC;IACD,iCAAiC,CAAC,IAAI,CAAC,CAAA;IACvC,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,oBAAoB,GAA8C;IACtE,CAAC,kBAAkB,EAAE,IAAI,CAAC;IAC1B,CAAC,YAAY,EAAE,eAAe,CAAC;IAC/B,CAAC,YAAY,EAAE,eAAe,CAAC;IAC/B,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;IACvC,CAAC,YAAY,EAAE,eAAe,CAAC;IAC/B,CAAC,aAAa,EAAE,QAAQ,CAAC;IACzB,CAAC,kBAAkB,EAAE,cAAc,CAAC;IACpC,CAAC,UAAU,EAAE,YAAY,CAAC;CAC3B,CAAA;AAED,SAAS,iCAAiC,CAAC,IAAgB;IACzD,IAAI,IAAI,CAAC,OAAO,KAAK,WAAW,IAAI,IAAI,CAAC,OAAO,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,OAAM;IACjG,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,oBAAoB,EAAE,CAAC;QAC/C,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,QAAQ,CAChB,GAAG,IAAI,sDAAsD,IAAI,CAAC,OAAO,GAAG,CAC7E,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,0FAA0F;AAC1F,SAAS,eAAe,CAAC,IAAY,EAAE,MAA0B,EAAE,IAAc;IAC/E,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAA;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,CAAA;IACzB,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,QAAQ,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAA;IACvE,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CACxB,IAAY,EACZ,IAAgB,EAChB,UAAmB;IAEnB,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,KAAK,CAAC;QACX,KAAK,KAAK,CAAC;QACX,KAAK,WAAW;YACd,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;gBACnB,UAAU,GAAG,IAAI,CAAA;YACnB,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAA;QACtC,KAAK,MAAM,CAAC;QACZ,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI;YACP,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;YACrB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAA;QAC5C,KAAK,SAAS,CAAC;QACf,KAAK,WAAW,CAAC;QACjB,KAAK,IAAI;YACP,IAAI,CAAC,OAAO,GAAG,SAAS,CAAA;YACxB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAA;QAC5C;YACE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAA;IACzC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,IAAY,EAAE,IAAgB,EAAE,IAA8B;IACrF,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,OAAO,CAAC;QACb,KAAK,IAAI;YACP,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YACrB,MAAK;QACP,KAAK,QAAQ;YACX,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YAC7B,MAAK;QACP,KAAK,SAAS;YACZ,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YAC1B,MAAK;QACP,KAAK,YAAY;YACf,IAAI,CAAC,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YACzC,MAAK;QACP,KAAK,SAAS;YACZ,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YACvB,MAAK;QACP,KAAK,UAAU;YACb,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YAC7B,MAAK;QACP,KAAK,YAAY;YACf,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YACzB,MAAK;QACP,KAAK,QAAQ;YACX,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YACjC,MAAK;QACP,KAAK,iBAAiB;YACpB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YAC9B,MAAK;QACP,KAAK,qBAAqB;YACxB,IAAI,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YACzD,MAAK;QACP,KAAK,kBAAkB;YACrB,IAAI,CAAC,aAAa,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YACnD,MAAK;QACP,KAAK,oBAAoB;YACvB,IAAI,CAAC,eAAe,GAAG,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YACvD,MAAK;QACP,KAAK,iBAAiB;YACpB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YAC9B,MAAK;QACP,KAAK,gBAAgB;YACnB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YAC7B,MAAK;QACP,KAAK,WAAW;YACd,IAAI,CAAC,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YAC7C,MAAK;QACP,KAAK,WAAW;YACd,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YACrC,MAAK;QACP,KAAK,eAAe;YAClB,IAAI,CAAC,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YAC7C,MAAK;QACP,KAAK,eAAe;YAClB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YAC5B,MAAK;QACP,KAAK,mBAAmB;YACtB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YAChC,MAAK;QACP,KAAK,eAAe;YAClB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;YAC5B,MAAK;QACP,KAAK,QAAQ;YACX,IAAI,CAAC,WAAW,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;YACzD,MAAK;QACP,KAAK,cAAc;YACjB,4EAA4E;YAC5E,IAAI,CAAC,gBAAgB,GAAG,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAA;YAC9D,MAAK;QACP,KAAK,YAAY;YACf,IAAI,CAAC,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;YACzC,MAAK;QACP,KAAK,WAAW;YACd,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;YAClB,MAAK;QACP,KAAK,OAAO,CAAC;QACb,KAAK,IAAI;YACP,IAAI,CAAC,GAAG,GAAG,IAAI,CAAA;YACf,MAAK;QACP,KAAK,SAAS,CAAC;QACf,KAAK,IAAI;YACP,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;YACjB,MAAK;QACP;YACE,OAAO,KAAK,CAAA;IAChB,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAA;IAC7B,IAAK,aAAmC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAgB,CAAA;IAC7E,MAAM,IAAI,QAAQ,CAAC,uBAAuB,KAAK,gBAAgB,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;AAC9F,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAa;IAC1C,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAA;IAC7B,IAAK,kBAAwC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAqB,CAAA;IACvF,MAAM,IAAI,QAAQ,CAChB,gCAAgC,KAAK,gBAAgB,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CACvF,CAAA;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa;IACvC,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAA;IAC7B,IAAK,eAAqC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAkB,CAAA;IACjF,MAAM,IAAI,QAAQ,CAChB,6BAA6B,KAAK,gBAAgB,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CACjF,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,KAAa;IACzC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAiB,CAAA;IACpC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QACtE,IAAI,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,QAAQ;YAAE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;aAChE,IAAI,GAAG,KAAK,OAAO;YAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;aACrC,IAAI,GAAG,KAAK,EAAE;YACjB,MAAM,IAAI,QAAQ,CAChB,+BAA+B,KAAK,gBAAgB,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CACpF,CAAA;IACL,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,QAAQ,CAChB,+BAA+B,KAAK,gCAAgC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CACpG,CAAA;IACH,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAA;AACjB,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAA;IAC7B,IAAK,YAAkC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAe,CAAA;IAC3E,MAAM,IAAI,QAAQ,CAAC,sBAAsB,KAAK,gBAAgB,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;AAC5F,CAAC;AAED,qGAAqG;AACrG,SAAS,eAAe,CAAC,KAAa;IACpC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,QAAQ,CAAC,0BAA0B,KAAK,0CAA0C,CAAC,CAAA;IAC/F,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,IAAY,EAAE,KAAa,EAAE,GAAW;IACjE,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IACvB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACpC,MAAM,IAAI,QAAQ,CAAC,WAAW,IAAI,KAAK,KAAK,4CAA4C,GAAG,GAAG,CAAC,CAAA;IACjG,CAAC;IACD,OAAO,CAAC,CAAA;AACV,CAAC;AAED,SAAS,aAAa,CAAC,KAAa;IAClC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IACvB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,QAAQ,CAAC,uBAAuB,KAAK,8BAA8B,CAAC,CAAA;IAChF,CAAC;IACD,OAAO,CAAC,CAAA;AACV,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IACvB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC;QAC/C,MAAM,IAAI,QAAQ,CAAC,mBAAmB,KAAK,iCAAiC,CAAC,CAAA;IAC/E,CAAC;IACD,OAAO,CAAC,CAAA;AACV,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,KAAa;IAChC,IAAI,GAAQ,CAAA;IACZ,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAA;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,sBAAsB,KAAK,kEAAkE,CAC9F,CAAA;IACH,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,QAAQ,CAAC,sBAAsB,KAAK,yCAAyC,CAAC,CAAA;IAC1F,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,qEAAqE;AACrE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,WAAW,EAAE,aAAa;IAC1B,QAAQ,EAAE,0BAA0B;IACpC,QAAQ,EAAE,QAAuB;IACjC,WAAW,EAAE,8CAA8C;IAC3D,0EAA0E;IAC1E,0FAA0F;IAC1F,gCAAgC;IAChC,IAAI,EAAE,IAAI;IACV,gGAAgG;IAChG,0FAA0F;IAC1F,gBAAgB,EAAE,QAA4B;IAC9C,aAAa,EAAE,MAAuB;IACtC,0BAA0B;IAC1B,cAAc,EAAE,aAAa;IAC7B,UAAU,EAAE,KAAmB;IAC/B,iGAAiG;IACjG,oEAAoE;IACpE,MAAM,EAAE,uBAAuB;IAC/B,8DAA8D;IAC9D,UAAU,EAAE,SAAS;CACb,CAAA;AAEV,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6FxB,CAAA"}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/host-shell.d.ts

@@ -10,6 +10,20 @@ export interface ShellResult {
 }
 /** Conventional exit code for a missing binary — returned by {@link HostShell.run} on `ENOENT`. */
 export declare const COMMAND_NOT_FOUND = 127;
+/**
+ * A single command to run through the {@link HostShell}, optionally with stdin `input`.
+ *
+ * Lives here rather than beside one of its planners because several modules now plan commands
+ * (provisioning, the ingress probe) and a shared type in either of them would make the pair
+ * import each other.
+ */
+export interface Command {
+    cmd: string;
+    args: string[];
+    input?: string;
+    /** Per-command watchdog override (ms). Absent ⇒ the {@link HostShell} default applies. */
+    timeoutMs?: number;
+}
 /** Conventional exit code for a command killed by the watchdog timeout (mirrors `timeout(1)`). */
 export declare const COMMAND_TIMED_OUT = 124;
 /**
@@ -47,6 +61,18 @@ export interface HostShell {
         cwd?: string;
     }): Promise<ShellResult>;
 }
+/**
+ * Run a planned {@link Command} through a shell, honouring every field it carries.
+ *
+ * Use this for a READ whose non-zero exit is data rather than a failure (a probe, a best-effort
+ * list). `shell.run(command.cmd, command.args)` at a call site looks equivalent and is not: it
+ * silently drops `input` and the per-command `timeoutMs`, and hard-codes the binary the planner
+ * was there to name, so changing `cmd` keeps invoking the old one and the read gets the 10s
+ * default watchdog instead of its own.
+ */
+export declare function runCommand(shell: HostShell, command: Command): Promise<ShellResult>;
+/** A planned command rendered as the shell line a human would type, for printed guidance. */
+export declare function renderCommandLine(command: Command): string;
 /** The real, process-backed {@link HostShell}. */
 export declare function createNodeShell(): HostShell;
 //# sourceMappingURL=host-shell.d.ts.map

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

@@ -1 +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;;;;;;;;;;;;;;OAcG;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,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1D,OAAO,CAAC,WAAW,CAAC,CAAA;CACxB;AAED,kDAAkD;AAClD,wBAAgB,eAAe,IAAI,SAAS,CA2D3C"}
+{"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;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,kGAAkG;AAClG,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAS,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;;;OAcG;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,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1D,OAAO,CAAC,WAAW,CAAC,CAAA;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAKnF;AAED,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE1D;AAED,kDAAkD;AAClD,wBAAgB,eAAe,IAAI,SAAS,CA2D3C"}

package/dist/host-shell.js

@@ -10,6 +10,25 @@ export const COMMAND_TIMED_OUT = 124;
  * {@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;
+/**
+ * Run a planned {@link Command} through a shell, honouring every field it carries.
+ *
+ * Use this for a READ whose non-zero exit is data rather than a failure (a probe, a best-effort
+ * list). `shell.run(command.cmd, command.args)` at a call site looks equivalent and is not: it
+ * silently drops `input` and the per-command `timeoutMs`, and hard-codes the binary the planner
+ * was there to name, so changing `cmd` keeps invoking the old one and the read gets the 10s
+ * default watchdog instead of its own.
+ */
+export function runCommand(shell, command) {
+    return shell.run(command.cmd, command.args, {
+        input: command.input,
+        timeoutMs: command.timeoutMs,
+    });
+}
+/** A planned command rendered as the shell line a human would type, for printed guidance. */
+export function renderCommandLine(command) {
+    return [command.cmd, ...command.args].join(' ');
+}
 /** The real, process-backed {@link HostShell}. */
 export function createNodeShell() {
     return {

package/dist/host-shell.js.map

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

package/dist/index.d.ts

@@ -2,10 +2,11 @@ export { type CliOptions, HELP_TEXT, K3S_RUNTIMES, type K3sRuntime, OPTION_DEFAU
 export { bootstrap, type BootstrapDeps, BootstrapError } from './bootstrap.js';
 export { type EnvCommandDeps, EnvCommandError, generateEnv } from './envCommand.js';
 export { type FileSystem } from './fs.js';
-export { COMMAND_NOT_FOUND, COMMAND_TIMED_OUT, createNodeShell, DEFAULT_COMMAND_TIMEOUT_MS, type HostShell, type ShellResult, } from './host-shell.js';
+export { type Command, COMMAND_NOT_FOUND, COMMAND_TIMED_OUT, createNodeShell, DEFAULT_COMMAND_TIMEOUT_MS, type HostShell, renderCommandLine, runCommand, type ShellResult, } from './host-shell.js';
 export { K3S_INSTALL_COMMAND, type K3sDeps, type K3sResult, setupK3s } from './k3s.js';
-export { buildK3sHandler, buildK3sSetupUrl, DEFAULT_INGRESS_HOST_TEMPLATE, DEFAULT_NAMESPACE_TEMPLATE, handlerLabel, type K3sHandlerInput, KUBERNETES_ENV_TOKEN_SECRET_KEY, } from './k3s-handler.js';
-export { classifyHost, hasServerVersion, type HostDetections, type HostState, type Offer, type OfferId, parseK3dClusters, parseKindClusters, probeHost, type ToolDetection, } from './k3s-probe.js';
+export { buildK3sHandler, buildK3sSetupUrl, DEFAULT_NAMESPACE_TEMPLATE, handlerLabel, type K3sHandlerInput, KUBERNETES_ENV_TOKEN_SECRET_KEY, } from './k3s-handler.js';
+export { DEFAULT_INGRESS_PORT, INGRESS_HOST_TEMPLATE, type IngressReadiness, ingressHostTemplate, ingressUrlPort, } from './k3s-ingress.js';
+export { classifyHost, hasServerVersion, type HostDetections, type HostState, isRecreateOffer, type Offer, type OfferId, parseK3dClusters, parseKindClusters, probeHost, RECREATE_OFFERS, recreateOfferFor, recreateTargetForContext, 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,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,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC9E,OAAO,EAAE,KAAK,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACnF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,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,eAAe,EACf,gBAAgB,EAChB,6BAA6B,EAC7B,0BAA0B,EAC1B,YAAY,EACZ,KAAK,eAAe,EACpB,+BAA+B,GAChC,MAAM,kBAAkB,CAAA;AACzB,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,EACL,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,eAAe,EACf,KAAK,aAAa,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AACvB,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,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC9E,OAAO,EAAE,KAAK,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACnF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,EACL,KAAK,OAAO,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,0BAA0B,EAC1B,KAAK,SAAS,EACd,iBAAiB,EACjB,UAAU,EACV,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,eAAe,EACf,gBAAgB,EAChB,0BAA0B,EAC1B,YAAY,EACZ,KAAK,eAAe,EACpB,+BAA+B,GAChC,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,eAAe,EACf,KAAK,KAAK,EACV,KAAK,OAAO,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,wBAAwB,EACxB,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,EACL,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,eAAe,EACf,KAAK,aAAa,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,EACb,KAAK,WAAW,GACjB,MAAM,UAAU,CAAA"}

package/dist/index.js

@@ -4,10 +4,11 @@ export { HELP_TEXT, K3S_RUNTIMES, OPTION_DEFAULTS, parseArgs, ArgError, } from '
 export { bootstrap, BootstrapError } from './bootstrap.js';
 export { EnvCommandError, generateEnv } from './envCommand.js';
 export {} from './fs.js';
-export { COMMAND_NOT_FOUND, COMMAND_TIMED_OUT, createNodeShell, DEFAULT_COMMAND_TIMEOUT_MS, } from './host-shell.js';
+export { COMMAND_NOT_FOUND, COMMAND_TIMED_OUT, createNodeShell, DEFAULT_COMMAND_TIMEOUT_MS, renderCommandLine, runCommand, } from './host-shell.js';
 export { K3S_INSTALL_COMMAND, setupK3s } from './k3s.js';
-export { buildK3sHandler, buildK3sSetupUrl, DEFAULT_INGRESS_HOST_TEMPLATE, DEFAULT_NAMESPACE_TEMPLATE, handlerLabel, KUBERNETES_ENV_TOKEN_SECRET_KEY, } from './k3s-handler.js';
-export { classifyHost, hasServerVersion, parseK3dClusters, parseKindClusters, probeHost, } from './k3s-probe.js';
+export { buildK3sHandler, buildK3sSetupUrl, DEFAULT_NAMESPACE_TEMPLATE, handlerLabel, KUBERNETES_ENV_TOKEN_SECRET_KEY, } from './k3s-handler.js';
+export { DEFAULT_INGRESS_PORT, INGRESS_HOST_TEMPLATE, ingressHostTemplate, ingressUrlPort, } from './k3s-ingress.js';
+export { classifyHost, hasServerVersion, isRecreateOffer, parseK3dClusters, parseKindClusters, probeHost, RECREATE_OFFERS, recreateOfferFor, recreateTargetForContext, } 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,EAEL,SAAS,EACT,YAAY,EAEZ,eAAe,EACf,SAAS,EACT,QAAQ,GACT,MAAM,WAAW,CAAA;AAClB,OAAO,EAAE,SAAS,EAAsB,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC9E,OAAO,EAAuB,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACnF,OAAO,EAAmB,MAAM,SAAS,CAAA;AACzC,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,eAAe,EACf,gBAAgB,EAChB,6BAA6B,EAC7B,0BAA0B,EAC1B,YAAY,EAEZ,+BAA+B,GAChC,MAAM,kBAAkB,CAAA;AACzB,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,EACL,kBAAkB,EAElB,eAAe,EAEf,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,GAEjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EAGnB,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AACvB,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,EAAsB,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC9E,OAAO,EAAuB,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACnF,OAAO,EAAmB,MAAM,SAAS,CAAA;AACzC,OAAO,EAEL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,0BAA0B,EAE1B,iBAAiB,EACjB,UAAU,GAEX,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,mBAAmB,EAAgC,QAAQ,EAAE,MAAM,UAAU,CAAA;AACtF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,0BAA0B,EAC1B,YAAY,EAEZ,+BAA+B,GAChC,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EAErB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAGhB,eAAe,EAGf,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,wBAAwB,GAEzB,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,EACL,kBAAkB,EAElB,eAAe,EAEf,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,GAEjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EAGnB,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,aAAa,EACb,aAAa,GAEd,MAAM,UAAU,CAAA"}

package/dist/k3s-handler.d.ts

@@ -1,24 +1,22 @@
 import { type ResolvedConnection } from './k3s-provision.js';
 /**
  * The secret-bundle key the Kubernetes env backend reads the ServiceAccount token from. Mirrors
- * the contracts constant `KUBERNETES_ENV_TOKEN_SECRET_KEY` — kept inline so the CLI stays free of a
+ * the contracts constant `KUBERNETES_ENV_TOKEN_SECRET_KEY`, kept inline so the CLI stays free of a
  * backend/contract RUNTIME dependency (the unit test validates the built handler against the real
  * `registerEnvironmentHandlerSchema`, so any drift from the contract fails a test).
  */
 export declare const KUBERNETES_ENV_TOKEN_SECRET_KEY = "apiToken";
 /** Default per-PR namespace name template written into the handler (rendered with the PR number). */
 export declare const DEFAULT_NAMESPACE_TEMPLATE = "cf-env-{{pullNumber}}";
-/**
- * Default ingress host template. `nip.io` is a wildcard DNS service that resolves
- * `<anything>.127.0.0.1.nip.io` to loopback with no local DNS setup, so a per-branch env URL works
- * against a local k3s/k3d/kind ingress out of the box.
- */
-export declare const DEFAULT_INGRESS_HOST_TEMPLATE = "{{branch}}.127.0.0.1.nip.io";
 /**
  * The `RegisterEnvironmentHandlerInput` shape for the `local-k3s` engine, mirrored structurally
  * here so the CLI stays free of a backend/contract runtime dependency. `k3s-handler.test.ts`
  * validates a built value against the real `registerEnvironmentHandlerSchema`, so this can't drift
  * from the contract without failing a test.
+ *
+ * `url.port` carries a non-default host port. It is deliberately NOT folded into `hostTemplate`:
+ * the rendered template is also the Ingress `host` a service's manifests declare, and Kubernetes
+ * rejects a `host` with a port in it.
  */
 export interface K3sHandlerInput {
     provisionType: 'kubernetes';
@@ -32,6 +30,8 @@ export interface K3sHandlerInput {
             url: {
                 source: 'ingressTemplate';
                 hostTemplate: string;
+                port?: number;
+                scheme: 'http';
             };
         };
     };
@@ -40,20 +40,35 @@ export interface K3sHandlerInput {
 /** Human label for the auto-provisioned connection (names the created cluster when there is one). */
 export declare function handlerLabel(connection: ResolvedConnection): string;
 /**
- * Build the `local-k3s` infra handler registration input from a provisioned connection. The minted
- * ServiceAccount token rides ONLY in the write-only `secrets` bundle (never in the config, never in
- * the deep-link). Everything else — the loopback apiserver URL, the skip-TLS flag (a local k3s
- * apiserver self-signs its cert), the per-PR namespace + nip.io ingress host defaults — is
- * non-secret config. The result is exactly what the Settings → Infrastructure → Local k3s form's
- * Test/Save posts, so the guided flow reuses the #557 probe + registration unchanged.
+ * Build the `local-k3s` infra handler registration input from a provisioned connection, or `null`
+ * when there is nothing honest to register. The minted ServiceAccount token rides ONLY in the
+ * write-only `secrets` bundle (never in the config, never in the deep-link). Everything else (the
+ * loopback apiserver URL, the skip-TLS flag for a self-signed local apiserver, the per-PR namespace
+ * and the nip.io ingress host) is non-secret config. The result is exactly what the
+ * Settings → Infrastructure → Local k3s form's Test/Save posts, so the guided flow reuses the #557
+ * probe + registration unchanged.
+ *
+ * `null` is the whole point of the return type. The contract REQUIRES a `url` source, and
+ * `ingressTemplate` is the only one the CLI can fill on its own (the status-backed sources name a
+ * Service or Ingress that belongs to the operator's manifests), so a cluster whose ingress path the
+ * probe did not establish has no handler to build: filling the host template in anyway is how the
+ * unserved URL got saved. It used to fall back to the literal template, which was worse than stale
+ * on a `--ingress-port 8080` run, naming a port that run had not even asked for.
  */
-export declare function buildK3sHandler(connection: ResolvedConnection): K3sHandlerInput;
+export declare function buildK3sHandler(connection: ResolvedConnection): K3sHandlerInput | null;
 /**
- * Build the deep-link that opens the SPA's Local k3s connect form pre-filled with the handler's
- * NON-SECRET fields. The ServiceAccount token is deliberately omitted — a secret in a URL would
- * leak into browser history / server logs — so the user pastes it (printed once to the terminal)
- * before running Test → Save. Slice 4 teaches the SPA to read these params; until then the link
- * simply opens the app. Param names mirror the connect form's fields.
+ * Build the deep-link that opens the SPA's Local k3s connect form pre-filled with the connection's
+ * NON-SECRET fields. The ServiceAccount token is deliberately omitted (a secret in a URL would leak
+ * into browser history / server logs), so the user pastes it (printed once to the terminal) before
+ * running Test → Save. Param names mirror the connect form's fields.
+ *
+ * The URL params are prefilled ONLY when the ingress probe established that the cluster can serve
+ * them, and that is read off the CONNECTION rather than passed in: the withholding used to ride an
+ * `{ ingressVerified }` option DEFAULTED to true, so every caller that forgot it (the integration
+ * spec among them) re-established the promise this exists to remove. The connect form treats the
+ * host template as required for an `ingressTemplate` source, so an operator whose cluster has no
+ * ingress path cannot save a URL nothing answers, and the printed summary tells them what to fix or
+ * which source to pick instead.
  */
-export declare function buildK3sSetupUrl(spaBaseUrl: string, handler: K3sHandlerInput): string;
+export declare function buildK3sSetupUrl(spaBaseUrl: string, connection: ResolvedConnection): string;
 //# sourceMappingURL=k3s-handler.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"k3s-handler.d.ts","sourceRoot":"","sources":["../src/k3s-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,aAAa,CAAA;AAEzD,qGAAqG;AACrG,eAAO,MAAM,0BAA0B,0BAA0B,CAAA;AAEjE;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,gCAAgC,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,YAAY,CAAA;IAC3B,MAAM,EAAE;QACN,MAAM,EAAE,WAAW,CAAA;QACnB,UAAU,EAAE;YACV,KAAK,EAAE,MAAM,CAAA;YACb,YAAY,EAAE,MAAM,CAAA;YACpB,qBAAqB,EAAE,IAAI,CAAA;YAC3B,iBAAiB,EAAE,MAAM,CAAA;YACzB,GAAG,EAAE;gBAAE,MAAM,EAAE,iBAAiB,CAAC;gBAAC,YAAY,EAAE,MAAM,CAAA;aAAE,CAAA;SACzD,CAAA;KACF,CAAA;IACD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAEnE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,kBAAkB,GAAG,eAAe,CAe/E;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAWrF"}
+{"version":3,"file":"k3s-handler.d.ts","sourceRoot":"","sources":["../src/k3s-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,aAAa,CAAA;AAEzD,qGAAqG;AACrG,eAAO,MAAM,0BAA0B,0BAA0B,CAAA;AAEjE;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,YAAY,CAAA;IAC3B,MAAM,EAAE;QACN,MAAM,EAAE,WAAW,CAAA;QACnB,UAAU,EAAE;YACV,KAAK,EAAE,MAAM,CAAA;YACb,YAAY,EAAE,MAAM,CAAA;YACpB,qBAAqB,EAAE,IAAI,CAAA;YAC3B,iBAAiB,EAAE,MAAM,CAAA;YACzB,GAAG,EAAE;gBAAE,MAAM,EAAE,iBAAiB,CAAC;gBAAC,YAAY,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAAC,MAAM,EAAE,MAAM,CAAA;aAAE,CAAA;SACxF,CAAA;KACF,CAAA;IACD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,kBAAkB,GAAG,eAAe,GAAG,IAAI,CA0BtF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAgB3F"}

package/dist/k3s-handler.js

@@ -1,32 +1,39 @@
+import { ingressHostTemplate, ingressUrlPort } from './k3s-ingress.js';
 import {} from './k3s-provision.js';
 /**
  * The secret-bundle key the Kubernetes env backend reads the ServiceAccount token from. Mirrors
- * the contracts constant `KUBERNETES_ENV_TOKEN_SECRET_KEY` — kept inline so the CLI stays free of a
+ * the contracts constant `KUBERNETES_ENV_TOKEN_SECRET_KEY`, kept inline so the CLI stays free of a
  * backend/contract RUNTIME dependency (the unit test validates the built handler against the real
  * `registerEnvironmentHandlerSchema`, so any drift from the contract fails a test).
  */
 export const KUBERNETES_ENV_TOKEN_SECRET_KEY = 'apiToken';
 /** Default per-PR namespace name template written into the handler (rendered with the PR number). */
 export const DEFAULT_NAMESPACE_TEMPLATE = 'cf-env-{{pullNumber}}';
-/**
- * Default ingress host template. `nip.io` is a wildcard DNS service that resolves
- * `<anything>.127.0.0.1.nip.io` to loopback with no local DNS setup, so a per-branch env URL works
- * against a local k3s/k3d/kind ingress out of the box.
- */
-export const DEFAULT_INGRESS_HOST_TEMPLATE = '{{branch}}.127.0.0.1.nip.io';
 /** Human label for the auto-provisioned connection (names the created cluster when there is one). */
 export function handlerLabel(connection) {
     return connection.clusterName ? `Local k3s (${connection.clusterName})` : 'Local k3s';
 }
 /**
- * Build the `local-k3s` infra handler registration input from a provisioned connection. The minted
- * ServiceAccount token rides ONLY in the write-only `secrets` bundle (never in the config, never in
- * the deep-link). Everything else — the loopback apiserver URL, the skip-TLS flag (a local k3s
- * apiserver self-signs its cert), the per-PR namespace + nip.io ingress host defaults — is
- * non-secret config. The result is exactly what the Settings → Infrastructure → Local k3s form's
- * Test/Save posts, so the guided flow reuses the #557 probe + registration unchanged.
+ * Build the `local-k3s` infra handler registration input from a provisioned connection, or `null`
+ * when there is nothing honest to register. The minted ServiceAccount token rides ONLY in the
+ * write-only `secrets` bundle (never in the config, never in the deep-link). Everything else (the
+ * loopback apiserver URL, the skip-TLS flag for a self-signed local apiserver, the per-PR namespace
+ * and the nip.io ingress host) is non-secret config. The result is exactly what the
+ * Settings → Infrastructure → Local k3s form's Test/Save posts, so the guided flow reuses the #557
+ * probe + registration unchanged.
+ *
+ * `null` is the whole point of the return type. The contract REQUIRES a `url` source, and
+ * `ingressTemplate` is the only one the CLI can fill on its own (the status-backed sources name a
+ * Service or Ingress that belongs to the operator's manifests), so a cluster whose ingress path the
+ * probe did not establish has no handler to build: filling the host template in anyway is how the
+ * unserved URL got saved. It used to fall back to the literal template, which was worse than stale
+ * on a `--ingress-port 8080` run, naming a port that run had not even asked for.
  */
 export function buildK3sHandler(connection) {
+    const hostTemplate = ingressHostTemplate(connection.ingress);
+    if (hostTemplate === null)
+        return null;
+    const port = ingressUrlPort(connection.ingress);
     return {
         provisionType: 'kubernetes',
         config: {
@@ -36,29 +43,50 @@ export function buildK3sHandler(connection) {
                 apiServerUrl: connection.apiServerUrl,
                 insecureSkipTlsVerify: true,
                 namespaceTemplate: DEFAULT_NAMESPACE_TEMPLATE,
-                url: { source: 'ingressTemplate', hostTemplate: DEFAULT_INGRESS_HOST_TEMPLATE },
+                url: {
+                    source: 'ingressTemplate',
+                    hostTemplate,
+                    ...(port === null ? {} : { port }),
+                    // A local ingress controller serves TLS with a self-signed certificate, so the derived
+                    // environment URL is plain HTTP: the derivation's own default is `https`, which would
+                    // hand the tester a URL that fails on the certificate rather than on the connection.
+                    scheme: 'http',
+                },
             },
         },
         secrets: { [KUBERNETES_ENV_TOKEN_SECRET_KEY]: connection.apiToken },
     };
 }
 /**
- * Build the deep-link that opens the SPA's Local k3s connect form pre-filled with the handler's
- * NON-SECRET fields. The ServiceAccount token is deliberately omitted — a secret in a URL would
- * leak into browser history / server logs — so the user pastes it (printed once to the terminal)
- * before running Test → Save. Slice 4 teaches the SPA to read these params; until then the link
- * simply opens the app. Param names mirror the connect form's fields.
+ * Build the deep-link that opens the SPA's Local k3s connect form pre-filled with the connection's
+ * NON-SECRET fields. The ServiceAccount token is deliberately omitted (a secret in a URL would leak
+ * into browser history / server logs), so the user pastes it (printed once to the terminal) before
+ * running Test → Save. Param names mirror the connect form's fields.
+ *
+ * The URL params are prefilled ONLY when the ingress probe established that the cluster can serve
+ * them, and that is read off the CONNECTION rather than passed in: the withholding used to ride an
+ * `{ ingressVerified }` option DEFAULTED to true, so every caller that forgot it (the integration
+ * spec among them) re-established the promise this exists to remove. The connect form treats the
+ * host template as required for an `ingressTemplate` source, so an operator whose cluster has no
+ * ingress path cannot save a URL nothing answers, and the printed summary tells them what to fix or
+ * which source to pick instead.
  */
-export function buildK3sSetupUrl(spaBaseUrl, handler) {
-    const k = handler.config.kubernetes;
+export function buildK3sSetupUrl(spaBaseUrl, connection) {
     const url = new URL(spaBaseUrl);
     const params = url.searchParams;
     params.set('infraSetup', 'local-k3s');
-    params.set('label', k.label);
-    params.set('apiServerUrl', k.apiServerUrl);
-    params.set('namespaceTemplate', k.namespaceTemplate);
-    params.set('hostTemplate', k.url.hostTemplate);
-    if (k.insecureSkipTlsVerify)
+    params.set('label', handlerLabel(connection));
+    params.set('apiServerUrl', connection.apiServerUrl);
+    params.set('namespaceTemplate', DEFAULT_NAMESPACE_TEMPLATE);
+    const handler = buildK3sHandler(connection);
+    if (handler) {
+        const k = handler.config.kubernetes.url;
+        params.set('hostTemplate', k.hostTemplate);
+        params.set('scheme', k.scheme);
+        if (k.port !== undefined)
+            params.set('ingressPort', String(k.port));
+    }
+    if (connection.insecureSkipTlsVerify)
         params.set('insecureSkipTlsVerify', '1');
     return url.toString();
 }