@netnodeag/kraftwerk 0.67.0 → 0.68.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
@@ -230,6 +231,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); `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

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

@@ -0,0 +1,18 @@
+/**
+ * `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;
+}): 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,104 @@
+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] : [])]);
+    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))}`);
+    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,26 @@ 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})`)
+        .action(async (opts) => {
+        // `--port` after `install` is taken by `daemon` itself, which has the same option.
+        await installDaemon({ port: opts.port ?? daemon.opts().port });
+    });
+    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

@@ -388,7 +388,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 +419,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.68.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",