@netnodeag/kraftwerk 0.46.2 → 0.48.0

package/README.md

@@ -164,6 +164,8 @@ kraftwerk create "was der Workflow tun soll"   # for LLM agents: prints a build
 kraftwerk runner build                  # build the Docker sandbox image (once)
 kraftwerk run --sandbox website-check "https://..."   # isolated container per run; --ssh forwards the agent
 kraftwerk runner ps / stop <run-id>     # see / stop running sandbox containers
+kraftwerk tunnel setup kw.example.com   # Cloudflare Tunnel to the inspector: login, create, route dns, kraftwerk.yml
+kraftwerk tunnel                        # run that tunnel alone (the UI runs elsewhere)
 ```
 
 The inspector binds `127.0.0.1` — it has no authentication of its own and
@@ -177,8 +179,9 @@ overrides the default either way. A reverse proxy in front of it must set
 `X-Forwarded-Host` to the host the browser addressed (Caddy and traefik do
 by default; nginx needs `proxy_set_header X-Forwarded-Host $host;`): the
 loopback bind answers a non-loopback `Host` only when that header is
-present, and state-changing requests are refused when `Origin` names a
-different host.
+present or the name is the project's `public:` hostname, and state-changing
+requests are refused when `Origin` names a different host. See
+[Inspector through a Cloudflare Tunnel](#inspector-through-a-cloudflare-tunnel).
 
 ### The kraftwerk.yml project config
 
@@ -187,6 +190,18 @@ fields are optional. `workflows:` sets the workflows root, `output:` the
 run-artifact directory (default `output/`), `knowledge:` the OKF bundle root
 (default `knowledge/`), and `agents:` the agent-definition root (default
 `agents/`). `repos:` turns on the [repositories](#repositories) folder.
+`public:` and `tunnel:` expose the inspector through a
+[Cloudflare Tunnel](#inspector-through-a-cloudflare-tunnel).
+
+A `.env` next to kraftwerk.yml (`KEY=value` lines, `#` comments, quotes)
+is loaded into every kraftwerk process at start: `kraftwerk ui` and the
+server it supervises, so a restart from the UI re-reads the file; the chat
+agents, routines and workflow runs the inspector spawns; the tunnel
+(`TUNNEL_TOKEN`); `requires:` checks in `run` and `doctor`. A variable the
+shell already sets wins over the file. A project started from another
+workspace's inspector gets its own `.env`, not the other one's. The file is
+never synced (it is on the workspace git's deny list and in the .gitignore
+`kraftwerk init` writes); `kraftwerk doctor` lists the names it loaded.
 
 `switcher:` links other kraftwerk workspaces from the inspector header. The
 workspace name becomes a dropdown listing them:
@@ -283,6 +298,111 @@ repo. Agent logins made inside the container persist in the `agent-home`
 volume. This is a different image from the `kraftwerk-runner` sandbox
 (`runner/Dockerfile`) used by `run --sandbox`.
 
+### Inspector through a Cloudflare Tunnel
+
+The other way to reach a laptop's or server's inspector from elsewhere: no
+open port, no reverse proxy, no certificate. `kraftwerk ui` runs
+[cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
+next to the inspector and the loopback bind becomes reachable at a hostname
+on a domain you have on Cloudflare.
+
+You need a Cloudflare account with a domain added to it (the free plan is
+enough), and cloudflared on the machine:
+
+```bash
+brew install cloudflared          # macOS; Linux packages: developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
+```
+
+**1. Create the tunnel and route a hostname to it.** From the project root:
+
+```bash
+kraftwerk tunnel setup kw.example.com
+```
+
+This opens the browser for `cloudflared tunnel login` when there is no
+certificate yet (pick the zone `kw.example.com` belongs to), creates a
+tunnel named `kraftwerk-<project name>` (or `--name`), adds the CNAME from
+the hostname to it, and writes the result into kraftwerk.yml:
+
+```yaml
+public: https://kw.example.com   # the hostname the tunnel routes to
+tunnel:
+  name: kraftwerk-agent-playground
+```
+
+A second run reuses the login and the tunnel. If the hostname already has a
+DNS record, setup says so and `--overwrite-dns` replaces it. If cloudflared
+quietly routed `kw.example.com.other-zone.com` instead, because the hostname
+is outside the zone you logged in to, setup refuses and names the stray
+record to delete before you log in to the right zone and run it again.
+
+**2. Put a Cloudflare Access policy on the hostname.** The UI has no login
+of its own and its chat runs coding agents against the workspace, so the
+tunnel must never be the only thing between the internet and it. In the
+[Zero Trust dashboard](https://one.dash.cloudflare.com/) go to Access →
+Applications → Add an application → Self-hosted, enter `kw.example.com` as
+the domain, and add a policy: emails ending in your domain with a one-time
+PIN, a Google or GitHub login, whatever fits. Access is free for up to 50
+users. From then on Cloudflare shows a login page before anything reaches
+the tunnel.
+
+**3. Let the inspector verify that login.** On the application's overview
+page copy the Application Audience (AUD) tag, and take your team name from
+the team domain `https://<team>.cloudflareaccess.com`:
+
+```yaml
+tunnel:
+  name: kraftwerk-agent-playground
+  access:
+    team: my-team
+    aud: 4714c1358e65fe4b408ad6d432a5f878f08194bdb4752441fd56faefa9b2b6f2
+```
+
+With this block the inspector checks the `Cf-Access-Jwt-Assertion` token
+Access adds to every request, against the team's public keys, the audience
+tag and the clock. A removed or misconfigured policy then fails closed with
+a 401 instead of exposing the UI. Skipping the block works, and
+`kraftwerk doctor` warns about it every time.
+
+**4. Start.** `kraftwerk ui` now starts cloudflared with the inspector,
+keeps it across UI restarts and stops it with the UI:
+
+```
+✔ Kraftwerk UI: http://localhost:1981
+✔ Public URL: https://kw.example.com
+↗ tunnel: running kraftwerk-agent-playground → https://kw.example.com → http://127.0.0.1:1981
+  cloudflared │ ... Registered tunnel connection ...
+```
+
+Open `https://kw.example.com` from anywhere, log in through Access, and you
+are in the same inspector. `localhost:1981` on the machine itself keeps
+working without a login. `kraftwerk doctor` reports the tunnel, the Access
+block and whether cloudflared is installed.
+
+**Variants.** `kraftwerk tunnel` runs the configured tunnel alone, for an
+inspector that already runs elsewhere (started by `kraftwerk projects
+start`, or in a container). For a tunnel created in the Zero Trust
+dashboard instead (Networks → Tunnels), leave `name` out, route the
+hostname to `http://localhost:<port>` there and export its token as
+`TUNNEL_TOKEN` before `kraftwerk ui`. `public:` on its own, without
+`tunnel:`, is for any other proxy that forwards the browser's `Host`
+without setting `X-Forwarded-Host`.
+
+**Troubleshooting.** cloudflared's lines appear prefixed with
+`cloudflared │`. "Cannot determine default origin certificate path" means no
+login on this machine: run `cloudflared tunnel login` or setup again. "tunnel
+not found" means the name in kraftwerk.yml does not exist in the account
+that logged in; `cloudflared tunnel list` shows what does. A tunnel that
+dies three times right after launch is given up and the UI stays local
+until the next start. A 421 "unexpected Host header" in the browser means
+`public:` does not match the hostname you opened. A 401 means Access is
+configured in kraftwerk.yml but the token is missing or wrong: the
+hostname has no Access application, or `team`/`aud` do not match it.
+
+Quick tunnels (`trycloudflare.com`) are deliberately not supported: Access
+cannot be attached to them, which would leave the UI open to anyone with
+the URL.
+
 ## Persistent agents
 
 The inspector's "agents" screen turns chat agents into persistent teammates. An

package/dist/cli/doctor.js

@@ -2,9 +2,10 @@ import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { ignoreEntryFor, isDir, reposRootFor, resolveProject } from "../config.js";
+import { ignoreEntryFor, isDir, publicHostFor, reposRootFor, resolveProject, tunnelFor } from "../config.js";
 import { discoverWorkflows } from "../discover.js";
 import { missingEnv } from "../yaml.js";
+import { applyDotenv, DOTENV_FILE } from "../dotenv.js";
 const ICONS = {
     ok: chalk.green("✔"),
     warn: chalk.yellow("⚠"),
@@ -106,6 +107,16 @@ export async function runDoctor(cwd) {
             }
         }
     }
+    // .env next to kraftwerk.yml: already applied by the CLI hook; this call
+    // only reports what it holds (names, never values).
+    const dotenv = await applyDotenv(project.root);
+    if (dotenv.file) {
+        const names = [...dotenv.applied, ...dotenv.kept.map((k) => `${k} (shell wins)`)];
+        report("ok", `${DOTENV_FILE}: ${names.length} variable(s) loaded`, names.join(", ") || "empty");
+    }
+    else {
+        report("info", `no ${DOTENV_FILE}`, "variables for agents, workflows and the tunnel can live there — loaded on every start and restart");
+    }
     // Repositories: the clones root must stay out of the workspace git. git
     // itself decides — that covers worktrees (.git is a file), a workspace
     // nested in a larger repo, a .gitignore at the toplevel, global excludes.
@@ -123,6 +134,33 @@ export async function runDoctor(cwd) {
         else
             report("ok", label, "not inside a git repository");
     }
+    // Public hostname + Cloudflare Tunnel. The UI has no login of its own, so
+    // a tunnel without Access verification is worth a warning every time.
+    const publicHost = publicHostFor(project);
+    const tunnel = tunnelFor(project);
+    if (publicHost && !tunnel)
+        report("info", `public: ${publicHost}`, "served when a tunnel or reverse proxy delivers that Host");
+    if (tunnel) {
+        const cloudflared = cliVersion("cloudflared");
+        if (cloudflared)
+            report("ok", `cloudflared`, cloudflared);
+        else {
+            report("fail", "cloudflared missing", "needed by tunnel: — brew install cloudflared (or see developers.cloudflare.com)");
+            failures++;
+        }
+        if (tunnel.name)
+            report("ok", `tunnel: ${tunnel.name} → ${publicHost}`, `cloudflared tunnel run --url http://127.0.0.1:${project.config.port ?? 1981} ${tunnel.name}`);
+        else if (process.env.TUNNEL_TOKEN)
+            report("ok", `tunnel: dashboard-managed → ${publicHost}`, "TUNNEL_TOKEN is set");
+        else {
+            report("fail", "tunnel: nothing to run", "set tunnel.name (locally-managed) or the TUNNEL_TOKEN env var (dashboard-managed)");
+            failures++;
+        }
+        if (tunnel.access)
+            report("ok", "tunnel.access", `tokens verified against ${tunnel.access.team}.cloudflareaccess.com`);
+        else
+            report("warn", "tunnel without access", "the UI has no login of its own — put a Cloudflare Access policy on the hostname and set tunnel.access so a removed policy fails closed");
+    }
     const found = project.workflowsRoot ? await discoverWorkflows(cwd) : [];
     if (!project.workflowsRoot) {
         report("warn", "no workflows root", "expected src/workflows/ or workflows/ — `kraftwerk init` scaffolds one");

package/dist/cli/init.js

@@ -2,6 +2,7 @@ import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
 import { CONFIG_SCHEMA_URL, gitignoreHas, SCHEMA_URL } from "../config.js";
+import { DOTENV_FILE } from "../dotenv.js";
 import { initBundle, writeConcept } from "../okf.js";
 /**
  * `kraftwerk init` — make any repository a kraftwerk consumer in one
@@ -25,6 +26,12 @@ skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packag
 # repos:                          # git repositories the agents work on (uncomment both lines to enable)
 #   root: ${DATA_DIR}/repos       # clones land here (git-ignored); a bare \`repos:\` uses repos/ instead
 # vibeables:                      # small apps built live in a chat with a preview pane (uncomment to enable; one folder per app under ${DATA_DIR}/vibeables, versioned with the workspace)
+# public: https://kw.example.com  # hostname the inspector is reached at through a tunnel or reverse proxy
+# tunnel:                         # Cloudflare Tunnel run by \`kraftwerk ui\` (needs public:; put a Cloudflare Access policy on the hostname — the UI has no login of its own)
+#   name: kraftwerk               # locally-managed tunnel (cloudflared tunnel create/route dns); omit and export TUNNEL_TOKEN for a dashboard-managed one
+#   access:                       # verify the Access login on every request via public: (team = Zero Trust team name, aud = the application's audience tag)
+#     team: my-team
+#     aud: 4714c1358e65fe4b408ad6d432a5f878f08194bdb4752441fd56faefa9b2b6f2
 `;
 const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
 name: hello
@@ -127,24 +134,24 @@ export async function runInit(cwd) {
         await writeConcept(knowledgeRoot, DEMO_BUNDLE, "playbooks/refunds", DEMO_CONCEPT, "kraftwerk-init");
         created.push(bundleRel);
     }
-    // .gitignore: the output dir and the repos root (clones must never become
-    // gitlinks of the workspace repo). A missing file gets both in one write;
-    // an existing one only the entries it lacks.
+    // .gitignore: the output dir, the repos root (clones must never become
+    // gitlinks of the workspace repo) and .env (secrets). A missing file gets
+    // all in one write; an existing one only the entries it lacks.
     const gitignorePath = path.join(cwd, ".gitignore");
     const gitignore = (await readFile(gitignorePath, "utf8").catch(() => null)) ?? null;
-    const entries = [`${DATA_DIR}/output`, `${DATA_DIR}/repos`];
+    const entries = [`${DATA_DIR}/output/`, `${DATA_DIR}/repos/`, DOTENV_FILE];
     if (gitignore === null) {
-        await writeFile(gitignorePath, entries.map((e) => `${e}/\n`).join(""));
+        await writeFile(gitignorePath, entries.map((e) => `${e}\n`).join(""));
         created.push(".gitignore");
     }
     else {
-        const missing = entries.filter((e) => !gitignoreHas(gitignore, e));
+        const missing = entries.filter((e) => !gitignoreHas(gitignore, e.replace(/\/$/, "")));
         if (missing.length === 0) {
             skipped.push(".gitignore");
         }
         else {
-            await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}${missing.map((e) => `${e}/\n`).join("")}`);
-            created.push(`.gitignore (${missing.map((e) => `${e}/`).join(", ")} added)`);
+            await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}${missing.map((e) => `${e}\n`).join("")}`);
+            created.push(`.gitignore (${missing.join(", ")} added)`);
         }
     }
     for (const f of created)

package/dist/cli/kraftwerk.js

@@ -15,6 +15,9 @@ import { registerKnowledgeCommands } from "./knowledge.js";
 import { registerProjectCommands } from "./projects.js";
 import { registerRepoCommands } from "./repos.js";
 import { registerVibeableCommands } from "./vibeables.js";
+import { registerTunnelCommands } from "./tunnel.js";
+import { applyDotenv } from "../dotenv.js";
+import { resolveProject } from "../config.js";
 import { registerRoutineCommands } from "./routines.js";
 import { listRuns, showRun } from "./runs.js";
 import { runUi } from "./ui.js";
@@ -30,6 +33,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
  *   kraftwerk projects ...            known projects on this machine (list/start/forget)
  *   kraftwerk repos ...               repositories the agents work on (list/add/update/remove)
+ *   kraftwerk tunnel [setup <host>]   Cloudflare Tunnel to the inspector: run it alone, or set one up
  *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
  *   kraftwerk validate [paths...]     validate without executing
  *
@@ -59,7 +63,15 @@ const pkg = JSON.parse(await readFile(new URL("../../package.json", import.meta.
 const program = new Command()
     .name("kraftwerk")
     .description("kraftwerk — agentic workspace for teams: agents, skills, knowledge, workflows, and the inspector UI")
-    .version(pkg.version);
+    .version(pkg.version)
+    // The project's .env, before any command runs (and so before `kraftwerk
+    // ui` spawns its server, and again in that server on every restart). A
+    // broken kraftwerk.yml is the command's own error to report, not the hook's.
+    .hook("preAction", async () => {
+    const project = await resolveProject(process.cwd()).catch(() => null);
+    if (project)
+        await applyDotenv(project.root);
+});
 const agentLabel = (workflow) => workflow.meta.agents
     .map((a) => {
     const where = [a.harness && a.harness !== "claude" ? a.harness : "", a.protocol === "acp" ? "acp" : ""]
@@ -270,6 +282,7 @@ registerRoutineCommands(program);
 registerProjectCommands(program);
 registerRepoCommands(program);
 registerVibeableCommands(program);
+registerTunnelCommands(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/cli/tunnel.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type Project } from "../config.js";
+export interface RunningTunnel {
+    stop(): void;
+    /** Settles when the tunnel was stopped, or gave up on a cloudflared that keeps dying. */
+    done: Promise<"stopped" | "failed">;
+}
+/** Start cloudflared for the project's tunnel, or return undefined (nothing to run, or told why not). */
+export declare function startTunnel(project: Project, port: number): RunningTunnel | undefined;
+export declare function registerTunnelCommands(program: Command): void;

package/dist/cli/tunnel.js

@@ -0,0 +1,280 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import { parseDocument } from "yaml";
+import { parsePublic, publicHostFor, resolveProject, tunnelFor } from "../config.js";
+/**
+ * Cloudflare Tunnel next to the inspector. `kraftwerk ui` runs cloudflared
+ * as a sibling of the server so the loopback bind is reachable at the
+ * project's public hostname without opening a port. The tunnel itself is
+ * created once, by `kraftwerk tunnel setup` or by hand:
+ *
+ *   locally-managed      cloudflared tunnel login
+ *                        cloudflared tunnel create kraftwerk
+ *                        cloudflared tunnel route dns kraftwerk kw.example.com
+ *                        → tunnel: { name: kraftwerk }; everything routes to the inspector port
+ *   dashboard-managed    create the tunnel in Zero Trust → Networks → Tunnels, route the
+ *                        public hostname to http://localhost:<port> there, export TUNNEL_TOKEN
+ *                        → tunnel: {} ; cloudflared reads the token from the environment
+ *
+ * cloudflared reconnects on its own; this only respawns it when the process
+ * itself dies, after a pause. A process that keeps dying right after launch
+ * (no login, unknown tunnel name) is a configuration problem: after a few
+ * such exits the tunnel gives up and says so, and the UI stays local.
+ *
+ *   kraftwerk tunnel                   run the configured tunnel alone (the UI runs elsewhere)
+ *   kraftwerk tunnel setup <hostname>  login, create, route dns, write public: + tunnel.name
+ */
+const RESPAWN_DELAY = 5_000;
+/** An exit this soon after launch is a configuration problem, not a hiccup. */
+const FAST_EXIT = 10_000;
+const MAX_FAST_EXITS = 3;
+/** Start cloudflared for the project's tunnel, or return undefined (nothing to run, or told why not). */
+export function startTunnel(project, port) {
+    const tunnel = tunnelFor(project);
+    if (!tunnel)
+        return undefined;
+    const host = publicHostFor(project);
+    let args;
+    if (tunnel.name) {
+        args = ["tunnel", "--no-autoupdate", "run", "--url", `http://127.0.0.1:${port}`, tunnel.name];
+    }
+    else if (process.env.TUNNEL_TOKEN) {
+        args = ["tunnel", "--no-autoupdate", "run"];
+    }
+    else {
+        console.error(`${chalk.red("✖")} tunnel: nothing to run — set ${chalk.bold("tunnel.name")} in kraftwerk.yml (locally-managed) ` +
+            `or the ${chalk.bold("TUNNEL_TOKEN")} environment variable (dashboard-managed). The UI stays local.`);
+        return undefined;
+    }
+    let child;
+    let stopped = false;
+    let timer;
+    let fastExits = 0;
+    let settle = () => { };
+    const done = new Promise((resolve) => (settle = resolve));
+    const launch = () => {
+        const startedAt = Date.now();
+        console.log(`${chalk.dim("↗")} tunnel: ${tunnel.name ? `running ${chalk.bold(tunnel.name)}` : "running the dashboard-managed tunnel"}` +
+            chalk.dim(` → https://${host} → http://127.0.0.1:${port}`));
+        child = spawn("cloudflared", args, { stdio: ["ignore", "pipe", "pipe"] });
+        // cloudflared logs on stderr, one line per event; keep them recognisable.
+        const relay = (chunk) => {
+            for (const line of chunk.toString().split("\n"))
+                if (line.trim())
+                    console.log(chalk.dim(`  cloudflared │ ${line}`));
+        };
+        child.stdout?.on("data", relay);
+        child.stderr?.on("data", relay);
+        child.once("error", (err) => {
+            stopped = true;
+            if (err.code === "ENOENT") {
+                console.error(`${chalk.red("✖")} tunnel: cloudflared not found — brew install cloudflared (or see developers.cloudflare.com). The UI stays local.`);
+            }
+            else {
+                console.error(`${chalk.red("✖")} tunnel: cannot start cloudflared: ${err.message}`);
+            }
+            settle("failed");
+        });
+        // "close", not "exit": the last log lines are still in flight when the
+        // process ends, and they are what explains a failed launch.
+        child.once("close", (code, signal) => {
+            child = undefined;
+            if (stopped)
+                return settle("stopped");
+            fastExits = Date.now() - startedAt < FAST_EXIT ? fastExits + 1 : 0;
+            if (fastExits >= MAX_FAST_EXITS) {
+                console.error(`${chalk.red("✖")} tunnel: cloudflared exited ${MAX_FAST_EXITS} times right after launch — giving up. ` +
+                    `Check the messages above (cloudflared tunnel login? does the tunnel exist?), then restart the UI. The UI stays local.`);
+                return settle("failed");
+            }
+            console.error(`${chalk.red("✖")} tunnel: cloudflared exited (${signal ?? `code ${code}`}) — retrying in ${RESPAWN_DELAY / 1000}s`);
+            timer = setTimeout(launch, RESPAWN_DELAY);
+        });
+    };
+    launch();
+    return {
+        done,
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            if (child)
+                child.kill("SIGTERM");
+            else
+                settle("stopped");
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// CLI
+const die = (msg, code = 1) => {
+    console.error(chalk.red(msg));
+    process.exit(code);
+};
+/** cloudflared's version line, or undefined when the binary is not on PATH. */
+function cloudflaredVersion() {
+    const r = spawnSync("cloudflared", ["--version"], { encoding: "utf8", timeout: 10_000 });
+    if (r.error || r.status !== 0)
+        return undefined;
+    return (r.stdout || r.stderr).trim().split("\n")[0];
+}
+/** Run one cloudflared command to completion, capturing its output (stderr carries the log lines). */
+function cloudflared(args) {
+    const r = spawnSync("cloudflared", args, { encoding: "utf8", timeout: 120_000, stdio: ["inherit", "pipe", "pipe"] });
+    return { ok: !r.error && r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+}
+/** Whether something already answers on the inspector port (so the tunnel has an origin). */
+function inspectorListening(port) {
+    return new Promise((resolve) => {
+        const req = http.get({ host: "127.0.0.1", port, path: "/api/meta?probe=1", timeout: 1_500 }, (res) => {
+            res.resume();
+            resolve(true);
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+/** A tunnel name from the project's display name or folder: "kraftwerk-agent-playground". */
+function defaultTunnelName(project) {
+    const base = (project.config.name ?? path.basename(project.root)).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return `kraftwerk-${base || "inspector"}`;
+}
+/** The origin certificate `cloudflared tunnel login` writes; its presence means an authorized zone. */
+function originCertPath() {
+    return process.env.TUNNEL_ORIGIN_CERT || path.join(os.homedir(), ".cloudflared", "cert.pem");
+}
+/** Write public: and tunnel.name into kraftwerk.yml, keeping everything else (comments, an access block) as it is. */
+async function writeTunnelConfig(project, publicUrl, name) {
+    const configPath = project.configPath;
+    const doc = parseDocument(await readFile(configPath, "utf8"));
+    if (doc.errors.length > 0)
+        throw new Error(`${path.basename(configPath)}: ${doc.errors[0].message}`);
+    doc.set("public", publicUrl);
+    const tunnel = doc.get("tunnel");
+    if (tunnel && typeof tunnel === "object") {
+        doc.setIn(["tunnel", "name"], name);
+        doc.deleteIn(["tunnel", "enabled"]);
+    }
+    else {
+        doc.set("tunnel", { name });
+    }
+    await writeFile(configPath, doc.toString());
+    return configPath;
+}
+export function registerTunnelCommands(program) {
+    const tunnel = program
+        .command("tunnel")
+        .description("Cloudflare Tunnel to the inspector: run the configured one alone, or set one up");
+    tunnel
+        .command("run", { isDefault: true })
+        .description("Run the project's tunnel in the foreground (the inspector runs separately, e.g. `kraftwerk ui` elsewhere)")
+        .option("--port <port>", "Inspector port to route to (default: kraftwerk.yml `port`, else 1981)")
+        .action(async (opts) => {
+        const project = await resolveProject(process.cwd()).catch((err) => die(err.message, 2));
+        if (!tunnelFor(project)) {
+            die("tunnel is off — `kraftwerk tunnel setup <hostname>` creates one, or add `public:` and `tunnel:` to kraftwerk.yml (see kraftwerk doctor).");
+        }
+        const port = opts.port ? Number(opts.port) : (project.config.port ?? 1981);
+        if (!Number.isInteger(port) || port <= 0)
+            die("--port must be a port number", 2);
+        if (!(await inspectorListening(port))) {
+            console.log(chalk.yellow(`⚠ nothing answers on http://127.0.0.1:${port} yet — start \`kraftwerk ui\`; the tunnel serves errors until then.`));
+        }
+        const running = startTunnel(project, port);
+        if (!running)
+            process.exit(1);
+        for (const sig of ["SIGINT", "SIGTERM"])
+            process.once(sig, () => running.stop());
+        const outcome = await running.done;
+        process.exit(outcome === "failed" ? 1 : 0);
+    });
+    tunnel
+        .command("setup <hostname>")
+        .description("Create a locally-managed tunnel for this project and route the hostname to it (login, create, route dns, kraftwerk.yml)")
+        .option("--name <name>", "Tunnel name (default: kraftwerk-<project name>)")
+        .option("--overwrite-dns", "Replace an existing DNS record for the hostname")
+        .action(async (hostname, opts) => {
+        const host = parsePublic(hostname)?.hostname ?? die(`"${hostname}" is not a hostname — expected something like kw.example.com`, 2);
+        const project = await resolveProject(process.cwd()).catch((err) => die(err.message, 2));
+        if (!project.configPath)
+            die("no kraftwerk.yml here — `kraftwerk init` scaffolds one, then run setup again.", 2);
+        const name = opts.name ?? defaultTunnelName(project);
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name))
+            die(`"${name}" is not a plain tunnel name (letters, digits, ".", "_", "-")`, 2);
+        const version = cloudflaredVersion();
+        if (!version)
+            die("cloudflared not found — brew install cloudflared (or see developers.cloudflare.com), then run setup again.");
+        console.log(`${chalk.green("✔")} ${version}`);
+        // 1. Login: one authorized zone at a time, stored as cert.pem.
+        if (existsSync(originCertPath())) {
+            console.log(`${chalk.green("✔")} logged in to Cloudflare ${chalk.dim(`(${originCertPath()})`)}`);
+        }
+        else {
+            console.log(`${chalk.dim("↗")} cloudflared tunnel login — pick the zone that ${chalk.bold(host)} belongs to in the browser`);
+            const login = spawnSync("cloudflared", ["tunnel", "login"], { stdio: "inherit" });
+            if (login.error || login.status !== 0 || !existsSync(originCertPath()))
+                die("cloudflared tunnel login did not complete.");
+            console.log(`${chalk.green("✔")} logged in to Cloudflare`);
+        }
+        // 2. The tunnel: reuse one of that name, else create it.
+        const list = cloudflared(["tunnel", "list", "--output", "json", "--name", name]);
+        if (!list.ok)
+            die(`cloudflared tunnel list failed:\n${list.out}`);
+        let existing;
+        try {
+            existing = JSON.parse(list.out || "[]").find((t) => t.name === name);
+        }
+        catch {
+            die(`cloudflared tunnel list returned no JSON:\n${list.out}`);
+        }
+        let id = existing?.id;
+        if (existing) {
+            console.log(`${chalk.green("✔")} tunnel ${chalk.bold(name)} exists ${chalk.dim(id ?? "")}`);
+        }
+        else {
+            const created = cloudflared(["tunnel", "create", "--output", "json", name]);
+            if (!created.ok)
+                die(`cloudflared tunnel create failed:\n${created.out}`);
+            try {
+                id = JSON.parse(created.out).id;
+            }
+            catch {
+                // Not fatal: the route step addresses the tunnel by name.
+            }
+            console.log(`${chalk.green("✔")} created tunnel ${chalk.bold(name)} ${chalk.dim(id ?? "")}`);
+        }
+        // 3. DNS: a CNAME from the hostname to the tunnel. cloudflared can
+        // exit 0 after quietly appending the authorized zone to a hostname
+        // outside it — compare the record it reports with the one asked for.
+        const route = cloudflared(["tunnel", "route", "dns", ...(opts.overwriteDns ? ["--overwrite-dns"] : []), name, host]);
+        const added = /Added CNAME (\S+)/.exec(route.out)?.[1]?.replace(/\.$/, "").toLowerCase();
+        if (!route.ok) {
+            const exists = /already exists/i.test(route.out);
+            die(`cloudflared tunnel route dns failed:\n${route.out}` +
+                (exists && !opts.overwriteDns ? `\n\nA record for ${host} exists. If it should point at this tunnel, run setup again with --overwrite-dns.` : ""));
+        }
+        if (added && added !== host.toLowerCase()) {
+            die(`cloudflared routed ${chalk.bold(added)} instead of ${chalk.bold(host)}: the hostname is outside the zone you logged in to.\n` +
+                `Delete the stray CNAME ${added} in the Cloudflare dashboard, run \`cloudflared tunnel login\` for the right zone, then setup again.`);
+        }
+        console.log(`${chalk.green("✔")} ${host} → tunnel ${name}`);
+        // 4. kraftwerk.yml
+        const publicUrl = `https://${host}`;
+        const configPath = await writeTunnelConfig(project, publicUrl, name).catch((err) => die(err.message));
+        console.log(`${chalk.green("✔")} ${path.basename(configPath)}: public: ${publicUrl}, tunnel.name: ${name}`);
+        const port = project.config.port ?? 1981;
+        console.log(`\n${chalk.bold("Next:")} put a Cloudflare Access policy on ${host} — the UI has no login of its own.\n` +
+            `  Zero Trust → Access → Applications → Add an application → Self-hosted, domain ${host}: https://one.dash.cloudflare.com/\n` +
+            `  Then copy the team name and the application's Audience tag into kraftwerk.yml so the inspector verifies every login:\n` +
+            chalk.dim(`    tunnel:\n      name: ${name}\n      access:\n        team: <team>          # https://<team>.cloudflareaccess.com\n        aud: <audience tag>\n`) +
+            `\n\`kraftwerk ui\` now starts the tunnel with the inspector (port ${port}); \`kraftwerk tunnel\` runs it alone. \`kraftwerk doctor\` checks it.`);
+    });
+}