@netnodeag/kraftwerk 0.67.0 → 0.69.0

package/README.md

@@ -65,11 +65,12 @@ foreground; Ctrl-C stops it. That is all most people need.
 
 **Several workspaces: `kraftwerk daemon`.** With more than one workspace,
 run one kraftwerk for all of them instead of a server and a port each.
-Start the daemon once and leave it running (a terminal tab, or a login
-item):
+Start the daemon once and leave it running, or let your Mac start it at
+login:
 
 ```bash
 kraftwerk daemon                       # the machine's kraftwerk, on http://localhost:1980
+kraftwerk daemon install               # or: start it at login from now on (macOS; `uninstall` undoes it)
 
 cd ~/work/team-blau && kraftwerk ui    # opens this workspace in the daemon:
                                        #   http://team-blau.localhost:1980
@@ -94,13 +95,18 @@ you when it opens.
 `kraftwerk ui` hands the workspace to the daemon whenever one is running;
 `kraftwerk ui --standalone` starts a server of its own anyway.
 
-**From your phone or another computer.** Add `--lan` (`kraftwerk ui --lan`,
-or `kraftwerk daemon --lan`) and kraftwerk also listens on your network.
-Anyone who opens it there gets a pairing screen, nothing else, until you
-pair that device: `kraftwerk devices pair` on this machine prints a
-one-time code. A paired device reaches the daemon's workspaces at
-`/w/<slug>/` on the address it used, and the workspace menu links them
-that way (see [Inspector on your phone](#inspector-on-your-phone-paired-devices)).
+**From your phone or another computer** on the same network:
+
+1. Let the daemon listen on your network: `kraftwerk daemon install --lan`
+   (or run `kraftwerk daemon --lan`). It prints the address, for example
+   `http://192.168.1.20:1980`.
+2. Open that address on the phone. It shows a pairing form, nothing else.
+3. On this computer, run `kraftwerk devices pair` (or settings → devices →
+   pair a device) and type the code on the phone.
+
+The phone now sees your workspaces, each at `/w/<slug>/` on that address,
+and the workspace menu switches between them. One pairing covers all of them
+(see [Inspector on your phone](#inspector-on-your-phone-paired-devices)).
 
 **What to do first in the inspector.** Talk to **Ralv**, the workspace's
 general chat, in plain words: it knows what is in the workspace and helps
@@ -230,6 +236,7 @@ kraftwerk runs                          # past runs from output/*/trace.jsonl; r
 kraftwerk knowledge                     # Knowledge: OKF bundles (list/get/put/verify/search/...)
 kraftwerk ui                            # start this workspace: http://localhost:1981 (or open it in the daemon); --port, --lan, --standalone
 kraftwerk daemon                        # one kraftwerk for every open workspace: http://<slug>.localhost:1980; --port, --lan
+kraftwerk daemon install                # start the daemon at login (macOS LaunchAgent); --lan, --port; `daemon uninstall` removes it
 kraftwerk workspaces                    # every workspace on this machine; workspaces start|stop|forget <ref>
 kraftwerk devices                       # paired devices (a phone, another computer); devices pair|revoke
 kraftwerk projects                      # goal-scoped project folders; projects create|show|link|log|remove
@@ -382,13 +389,15 @@ follows to author the workflow folder and validate and smoke it with this CLI.
 
 ### Inspector on your phone (paired devices)
 
-`kraftwerk ui --lan` (or `kraftwerk daemon --lan`) also listens on your
-network and prints the addresses (for example `http://192.168.1.20:1981`).
-On the daemon, a device opens a workspace at `/w/<slug>/` on that address
+`kraftwerk ui --lan` (or `kraftwerk daemon --lan`, `kraftwerk daemon install
+--lan` for the login item) also listens on your network and prints the
+addresses (for example `http://192.168.1.20:1981`). On the daemon, a device
+opens a workspace at `/w/<slug>/` on that address
 (`http://192.168.1.20:1980/w/team-blau/`), because `<slug>.localhost` only
-works on this machine. The daemon's own address lists them, and the
-workspace menu links the others the same way. Anyone who opens one gets a
-pairing screen, nothing else. To let a device in, make a one-time code on
+works on this machine. The daemon's own address lists them once the device
+is paired, and pairs it when it is not, and the workspace menu links the
+others the same way. Anyone who opens one gets a pairing screen, nothing
+else. To let a device in, make a one-time code on
 the machine kraftwerk runs on, with `kraftwerk devices pair` or settings →
 devices → pair a device, and enter it on the device. The code works once,
 for 10 minutes. The device stays paired until you unpair it in the same

package/dist/cli/daemon-login.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `kraftwerk daemon install` / `uninstall`: the daemon as a macOS login item
+ * (a LaunchAgent), so it runs after a reboot without a terminal or the
+ * desktop app. launchd starts the same `kraftwerk daemon` a terminal would —
+ * this node, this install — with the PATH of the shell that installed it,
+ * because launchd's own PATH would not find the agents (claude, codex, pi).
+ * The daemon's supervisor restarts it after a self-update; launchd only
+ * starts it at login.
+ */
+export declare const LAUNCH_LABEL = "ch.netnode.kraftwerk.daemon";
+/** The LaunchAgent: `program` at login, `env` set, output appended to `log`. */
+export declare function renderPlist(program: string[], env: Record<string, string>, log: string): string;
+export declare function installDaemon(opts: {
+    port?: string;
+    lan?: boolean;
+}): Promise<void>;
+export declare function uninstallDaemon(): Promise<void>;
+/** For doctor: whether the login item is installed. */
+export declare const daemonLoginItem: () => string | null;

package/dist/cli/daemon-login.js

@@ -0,0 +1,106 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import { findDaemon } from "../core/daemon.js";
+import { selfCommand } from "../core/self-command.js";
+import { tildify } from "../core/instances.js";
+/**
+ * `kraftwerk daemon install` / `uninstall`: the daemon as a macOS login item
+ * (a LaunchAgent), so it runs after a reboot without a terminal or the
+ * desktop app. launchd starts the same `kraftwerk daemon` a terminal would —
+ * this node, this install — with the PATH of the shell that installed it,
+ * because launchd's own PATH would not find the agents (claude, codex, pi).
+ * The daemon's supervisor restarts it after a self-update; launchd only
+ * starts it at login.
+ */
+export const LAUNCH_LABEL = "ch.netnode.kraftwerk.daemon";
+const plistPath = () => path.join(os.homedir(), "Library", "LaunchAgents", `${LAUNCH_LABEL}.plist`);
+const logPath = () => path.join(os.homedir(), ".kraftwerk", "logs", "daemon.log");
+/** A stand-in launchctl (tests); the real one otherwise. */
+const launchctl = () => process.env.KRAFTWERK_LAUNCHCTL || "launchctl";
+const domain = () => `gui/${os.userInfo().uid}`;
+const xml = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[c]);
+/** The LaunchAgent: `program` at login, `env` set, output appended to `log`. */
+export function renderPlist(program, env, log) {
+    const strings = (xs) => xs.map((x) => `\t\t<string>${xml(x)}</string>`).join("\n");
+    const vars = Object.entries(env)
+        .map(([k, v]) => `\t\t<key>${xml(k)}</key>\n\t\t<string>${xml(v)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t<string>${LAUNCH_LABEL}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+${strings(program)}
+\t</array>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+${vars}
+\t</dict>
+\t<key>WorkingDirectory</key>
+\t<string>${xml(os.homedir())}</string>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>StandardOutPath</key>
+\t<string>${xml(log)}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+}
+function requireMac() {
+    if (process.platform !== "darwin") {
+        console.error(chalk.red("✖ a login item is macOS only for now — run `kraftwerk daemon` from your system's startup instead"));
+        process.exit(2);
+    }
+}
+export async function installDaemon(opts) {
+    requireMac();
+    const { cmd, args } = selfCommand(["daemon", ...(opts.port ? ["--port", opts.port] : []), ...(opts.lan ? ["--lan"] : [])]);
+    const env = { PATH: process.env.PATH ?? "/usr/bin:/bin" };
+    if (process.env.KRAFTWERK_DAEMON_PORT && !opts.port)
+        env.KRAFTWERK_DAEMON_PORT = process.env.KRAFTWERK_DAEMON_PORT;
+    const file = plistPath();
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.mkdir(path.dirname(logPath()), { recursive: true });
+    await fs.writeFile(file, renderPlist([cmd, ...args], env, logPath()));
+    // An older version of the item is replaced: unload it first (an error just means it was not loaded).
+    spawnSync(launchctl(), ["bootout", `${domain()}/${LAUNCH_LABEL}`], { stdio: "ignore" });
+    const running = await findDaemon();
+    if (running) {
+        // Loading now would start a second daemon, which refuses to run. launchd loads the file at the next login.
+        console.log(`${chalk.green("✔")} login item installed: ${chalk.dim(tildify(file))}`);
+        console.log(chalk.dim(`  a daemon already runs (pid ${running.pid}); from the next login on, launchd starts it`));
+        return;
+    }
+    const r = spawnSync(launchctl(), ["bootstrap", domain(), file], { encoding: "utf8" });
+    if (r.status !== 0) {
+        console.error(chalk.red(`✖ launchctl bootstrap failed: ${(r.stderr || r.stdout || "").trim() || `exit ${r.status}`}`));
+        console.error(chalk.dim(`  the file is in place (${tildify(file)}) and loads at the next login`));
+        process.exit(1);
+    }
+    console.log(`${chalk.green("✔")} login item installed and started: ${chalk.dim(tildify(file))}`);
+    if (opts.lan)
+        console.log(chalk.dim("  on your network too: devices pair first (`kraftwerk devices pair`)"));
+    console.log(chalk.dim(`  log: ${tildify(logPath())} · \`kraftwerk daemon uninstall\` removes it`));
+}
+export async function uninstallDaemon() {
+    requireMac();
+    const file = plistPath();
+    if (!existsSync(file)) {
+        console.log(chalk.dim("No login item installed."));
+        return;
+    }
+    // Unloading stops the daemon launchd started; one started from a terminal keeps running.
+    spawnSync(launchctl(), ["bootout", `${domain()}/${LAUNCH_LABEL}`], { stdio: "ignore" });
+    await fs.rm(file, { force: true });
+    console.log(`${chalk.green("✔")} login item removed ${chalk.dim(`(${tildify(file)})`)}`);
+}
+/** For doctor: whether the login item is installed. */
+export const daemonLoginItem = () => (existsSync(plistPath()) ? plistPath() : null);

package/dist/cli/daemon.js

@@ -4,6 +4,7 @@ import { tildify } from "../core/instances.js";
 import { networkUrls } from "../server/bind.js";
 import { startHub } from "../server/server.js";
 import { ensureBuilt, supervise } from "./ui.js";
+import { installDaemon, uninstallDaemon } from "./daemon-login.js";
 /**
  * `kraftwerk daemon` — the machine's kraftwerk: one process serving every
  * open workspace, each at `<slug>.localhost:<port>` (and its own port, when
@@ -49,12 +50,28 @@ export async function runDaemon(opts) {
         console.log(`${chalk.green("✔")} On your network: ${lan.map((u) => chalk.cyan(u)).join(", ")} ${chalk.dim("(add /w/<slug>/; devices pair first)")}`);
 }
 export function registerDaemonCommand(program) {
-    program
+    const daemon = program
         .command("daemon")
-        .description("Run the machine's kraftwerk: one process serving every open workspace at <slug>.localhost")
+        .description("Run the machine's kraftwerk: one process serving every open workspace at <slug>.localhost; install it as a login item")
         .option("--port <port>", `Port (default: KRAFTWERK_DAEMON_PORT, else ${DAEMON_PORT})`)
         .option("--lan", "Listen on the network too, for paired devices")
         .action(async (opts) => {
         await runDaemon(opts);
     });
+    daemon
+        .command("install")
+        .description("Start the daemon at login (macOS LaunchAgent), and now unless one runs")
+        .option("--port <port>", `Port (default: KRAFTWERK_DAEMON_PORT, else ${DAEMON_PORT})`)
+        .option("--lan", "Listen on the network too, for paired devices (a phone on the same Wi-Fi)")
+        .action(async (opts) => {
+        // `--port`/`--lan` after `install` are taken by `daemon` itself, which has the same options.
+        const parent = daemon.opts();
+        await installDaemon({ port: opts.port ?? parent.port, lan: opts.lan ?? parent.lan });
+    });
+    daemon
+        .command("uninstall")
+        .description("Remove the login item (stops a daemon launchd started)")
+        .action(async () => {
+        await uninstallDaemon();
+    });
 }

package/dist/cli/doctor.js

@@ -9,6 +9,8 @@ import { applyDotenv, DOTENV_FILE } from "../dotenv.js";
 import { legacyFindings, versionLt } from "./doctor-legacy.js";
 import { listDevices } from "../core/devices.js";
 import { slugClashes } from "../core/instances.js";
+import { findDaemon } from "../core/daemon.js";
+import { daemonLoginItem } from "./daemon-login.js";
 const ICONS = {
     ok: chalk.green("✔"),
     warn: chalk.yellow("⚠"),
@@ -210,6 +212,16 @@ export async function runDoctor(cwd) {
     if (process.env.KRAFTWERK_UI_TRUST_NETWORK === "1")
         report("warn", "KRAFTWERK_UI_TRUST_NETWORK=1", "anyone who reaches the UI over the network uses it without pairing — unset it and pair devices instead (`kraftwerk devices pair`)");
     report("info", devices.length ? `${devices.length} paired device(s)` : "no paired devices", devices.length ? devices.map((d) => d.name).join(", ") : "a phone or another computer can use kraftwerk once paired: `kraftwerk ui --lan`, then `kraftwerk devices pair`");
+    // The daemon: whether one runs, and whether it starts at login.
+    const daemon = await findDaemon();
+    const loginItem = daemonLoginItem();
+    report("info", daemon ? `kraftwerk daemon running on :${daemon.port}` : "no kraftwerk daemon running", loginItem
+        ? "starts at login (`kraftwerk daemon uninstall` removes that)"
+        : process.platform === "darwin"
+            ? "`kraftwerk daemon install` starts it at login"
+            : daemon
+                ? undefined
+                : "`kraftwerk daemon` serves every workspace in one process");
     // Legacy: what older versions left behind, and what still runs or is installed at one.
     for (const f of await legacyFindings(project, pkg.version))
         report(f.level, f.label, f.detail);

package/dist/server/server.d.ts

@@ -25,6 +25,8 @@ export interface OpenWorkspace {
     /** Its own port too (kraftwerk.yml `port`), when the hub listens there for it — old links keep working. */
     aliasPort?: number;
     ws: Workspace;
+    /** Its instance file being written (see openNow): closing waits for it, so no file lands after the close. */
+    registered?: Promise<void>;
 }
 /**
  * One HTTP server serving workspaces by slug (see target.ts): a daemon

package/dist/server/server.js

@@ -169,8 +169,8 @@ function installExitHandlers() {
     });
 }
 /**
- * Listen on `port`. On the default bind (127.0.0.1) the same port on ::1
- * feeds the same server: macOS resolves localhost and <slug>.localhost to
+ * Listen on `port`. On the default bind (127.0.0.1), and on 0.0.0.0
+ * (`--lan`, IPv4 only), the same port on ::1 feeds the same server: macOS resolves localhost and <slug>.localhost to
  * ::1 first, and a client that does not fall back to IPv4 (a native app's
  * HTTP library) would find nothing there. Best effort — without IPv6, or
  * with ::1:port taken, it stays IPv4 only, as before.
@@ -184,7 +184,7 @@ async function listen(server, port) {
             resolve(typeof addr === "object" && addr ? addr.port : port);
         });
     });
-    if (INSPECTOR_HOST !== "127.0.0.1")
+    if (INSPECTOR_HOST !== "127.0.0.1" && INSPECTOR_HOST !== "0.0.0.0")
         return bound;
     const twin = net.createServer((socket) => server.emit("connection", socket));
     const ok = await new Promise((resolve) => {
@@ -205,18 +205,35 @@ async function listen(server, port) {
 /**
  * A small page at a daemon's own address: the open workspaces, each a link —
  * <slug>.localhost on this machine, the path form on the address a paired
- * device used (it cannot resolve <slug>.localhost).
+ * device used (it cannot resolve <slug>.localhost). A device that is not
+ * paired yet gets a pairing form instead, and no workspace names: the code
+ * comes from this machine (`kraftwerk devices pair`), and the cookie it earns
+ * covers every workspace on this address.
  */
-function hubPage(req, res, open) {
+function hubPage(req, res, open, trust) {
     const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
     // Behind a proxy on this machine the browser's name is the forwarded one.
     const host = hostnameOf(forwardedHost(req) ?? req.headers.host ?? "");
     const local = LOOPBACK_NAMES.has(host) || host.endsWith(".localhost");
+    const head = `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>kraftwerk</title>` +
+        `<style>:root{color-scheme:light dark}body{font:16px/1.6 system-ui,sans-serif;max-width:560px;margin:40px auto;padding:0 16px}` +
+        `code{opacity:.7;font-size:13px}ul{list-style:none;padding:0}li{border-bottom:1px solid #8884}li a{display:block;padding:12px 0;font-weight:600;text-decoration:none;color:inherit}` +
+        `input,button{font:inherit;padding:10px 12px;border-radius:10px;border:1px solid #8888;width:100%;box-sizing:border-box;margin:6px 0}` +
+        `input[name=code]{letter-spacing:.2em;text-transform:uppercase}button{background:#5b4bd5;color:#fff;border:0;font-weight:600}#err{color:#c62828}</style><h1>kraftwerk</h1>`;
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+    if (trust.kind === "none") {
+        return void res.end(head +
+            `<p>Pair this device to use kraftwerk on this computer. On the computer, run <code>kraftwerk devices pair</code> (or settings → devices → pair a device) and enter the code here.</p>` +
+            `<form id="pair"><input name="code" placeholder="code" autocomplete="one-time-code" autocapitalize="characters" required>` +
+            `<input name="name" placeholder="this device's name, e.g. Lukas' iPhone"><button>pair</button><p id="err"></p></form>` +
+            `<script>document.getElementById("pair").onsubmit=async(e)=>{e.preventDefault();const f=new FormData(e.target);` +
+            `const r=await fetch("/api/pair",{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({code:String(f.get("code")).trim(),name:String(f.get("name")||navigator.platform||"device")})});` +
+            `if(r.ok)location.reload();else document.getElementById("err").textContent=(await r.json().catch(()=>({}))).error||"pairing failed"}</script>`);
+    }
     const rows = open.length
-        ? open.map((o) => `<li><a href="${esc(local ? `${o.url}/` : `/w/${o.slug}/`)}">${esc(o.name)}</a> <code>${esc(o.slug)}</code></li>`).join("")
+        ? open.map((o) => `<li><a href="${esc(local ? `${o.url}/` : `/w/${o.slug}/`)}">${esc(o.name)} <code>${esc(o.slug)}</code></a></li>`).join("")
         : "<li>No workspace is open. Run <code>kraftwerk ui</code> in a workspace folder.</li>";
-    res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
-    res.end(`<!doctype html><meta charset="utf-8"><title>kraftwerk</title><style>body{font:15px/1.6 system-ui,sans-serif;max-width:640px;margin:48px auto;padding:0 16px;color:#1b1b1f}code{color:#46464f}</style><h1>kraftwerk</h1><ul>${rows}</ul>`);
+    res.end(`${head}<ul>${rows}</ul>`);
 }
 export async function startHub(opts) {
     const trustOpts = { trustLoopback: opts.trustLoopback !== false && !REQUIRE_PAIRING, trustNetwork: TRUST_NETWORK };
@@ -260,7 +277,7 @@ export async function startHub(opts) {
             }
             // A daemon's own address lists its workspaces; anywhere else, the web UI's shell (public: an unpaired browser needs it to pair).
             if (!open && (url.pathname === "/" || url.pathname === "/index.html"))
-                return hubPage(req, res, [...bySlug.values()]);
+                return hubPage(req, res, [...bySlug.values()], trust);
             await serveStatic(res, opts.staticDir, url.pathname);
         }
         catch (err) {
@@ -388,7 +405,7 @@ export async function startHub(opts) {
             startRoutineScheduler();
             startGitSync();
             // Best-effort, in the background: none of them may hold up (or, failing, break) the open.
-            void registerInstance(entry.aliasPort ?? port, abs, opts.daemon ? { hub: true, slug, url: entry.url } : {}).catch(() => { });
+            entry.registered = registerInstance(entry.aliasPort ?? port, abs, opts.daemon ? { hub: true, slug, url: entry.url } : {}).catch(() => { });
             void registerWorkspace(abs).catch(() => { });
             void startCloudSync(entry.url, version).catch(() => { });
         }));
@@ -419,6 +436,7 @@ export async function startHub(opts) {
             await cloudGoodbye();
             stopCloudSync();
         }));
+        await entry.registered;
         unregisterInstance(abs);
         markWorkspaceStopped(abs);
         entry.ws.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netnodeag/kraftwerk",
-  "version": "0.67.0",
+  "version": "0.69.0",
   "description": "Open-source agentic workspace for teams — where people and AI agents get work done together: agents (Claude Code, Codex, Pi), skills, shared knowledge, repeatable workflows, and deterministic verification",
   "keywords": [
     "agents",