@netnodeag/kraftwerk 0.32.1 → 0.33.0

package/dist/cli/doctor.js

@@ -1,8 +1,8 @@
 import { spawnSync } from "node:child_process";
-import { readFile, stat } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { resolveProject } from "../config.js";
+import { isDir, resolveProject } from "../config.js";
 import { discoverWorkflows } from "../discover.js";
 import { missingEnv } from "../yaml.js";
 const ICONS = {
@@ -90,7 +90,6 @@ export async function runDoctor(cwd) {
         report("ok", `${path.basename(project.configPath)} well-formed`, keys.length ? keys.map((k) => `${k}: ${cfg[k]}`).join(", ") : "empty — defaults apply");
         if (!cfg.name)
             report("info", "name not set in kraftwerk.yml", "inspector header falls back to the folder name");
-        const isDir = async (p) => (await stat(p).catch(() => null))?.isDirectory() ?? false;
         for (const key of ["workflows", "knowledge", "agents", "output"]) {
             const value = cfg[key];
             if (!value)

package/dist/cli/kraftwerk.js

@@ -12,6 +12,7 @@ import { renderCreateBrief } from "./create-brief.js";
 import { runDoctor } from "./doctor.js";
 import { runInit } from "./init.js";
 import { registerKnowledgeCommands } from "./knowledge.js";
+import { registerProjectCommands } from "./projects.js";
 import { registerRoutineCommands } from "./routines.js";
 import { listRuns, showRun } from "./runs.js";
 import { runUi } from "./ui.js";
@@ -25,6 +26,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk knowledge ...           Context & Knowledge: OKF bundles (list/get/put/verify/...)
  *   kraftwerk routines ...            per-agent scheduled prompts (list/add/remove/enable/run)
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
+ *   kraftwerk projects ...            known projects on this machine (list/start/forget)
  *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
  *   kraftwerk validate [paths...]     validate without executing
  *
@@ -256,6 +258,7 @@ runs
 });
 registerKnowledgeCommands(program);
 registerRoutineCommands(program);
+registerProjectCommands(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/cli/projects.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerProjectCommands(program: Command): void;

package/dist/cli/projects.js

@@ -0,0 +1,126 @@
+import path from "node:path";
+import chalk from "chalk";
+import Table from "cli-table3";
+import { discoverWorkspaces, forgetProject, startProject, tildify, } from "../inspector/instances.js";
+/**
+ * `kraftwerk projects` — every project that ever ran the inspector on this
+ * machine (~/.kraftwerk/projects), joined with what is running right now.
+ * The answer to "where did I start that UI, and how do I get it back":
+ *
+ *   kraftwerk projects                 list: name, root, running/stopped
+ *   kraftwerk projects start <ref>     relaunch `kraftwerk ui` in that root, detached
+ *   kraftwerk projects forget <ref>    drop the record (the folder stays)
+ *
+ * <ref> is a project name, the root's folder name, or the root path.
+ */
+const fmtAgo = (iso) => {
+    if (!iso)
+        return "—";
+    const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+    if (s < 90)
+        return "just now";
+    if (s < 5400)
+        return `${Math.round(s / 60)} min ago`;
+    if (s < 129600)
+        return `${Math.round(s / 3600)} h ago`;
+    return `${Math.round(s / 86400)} d ago`;
+};
+/**
+ * Running → its url. Not running: "stopped" after a clean shutdown, "died"
+ * when the last start has no matching stop (killed, crashed, terminal
+ * closed) — the case this command exists for.
+ */
+const status = (e) => {
+    if (e.live)
+        return chalk.green(`● ${e.url.replace(/^https?:\/\//, "")}`);
+    if (e.exists === false)
+        return chalk.red("path missing");
+    const clean = !!e.lastStopped && !!e.lastStarted && e.lastStopped >= e.lastStarted;
+    return clean ? chalk.dim("stopped") : chalk.yellow("died");
+};
+async function resolveRef(ref) {
+    const all = (await discoverWorkspaces()).filter((e) => e.root);
+    const abs = path.resolve(ref);
+    const hits = all.filter((e) => e.root === abs ||
+        e.root === ref ||
+        e.name === ref ||
+        path.basename(e.root) === ref);
+    if (hits.length === 1)
+        return hits[0];
+    if (hits.length === 0) {
+        console.error(chalk.red(`No known project "${ref}". See \`kraftwerk projects\`.`));
+        process.exit(2);
+    }
+    console.error(chalk.red(`"${ref}" is ambiguous — use the root path:`));
+    for (const h of hits)
+        console.error(`  ${h.root}`);
+    process.exit(2);
+}
+export function registerProjectCommands(program) {
+    const projects = program
+        .command("projects")
+        .description("Known kraftwerk projects on this machine: list, start a stopped UI, forget");
+    projects
+        .command("list", { isDefault: true })
+        .description("List known projects with their root and whether the UI is running")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        const entries = await discoverWorkspaces();
+        if (opts.json) {
+            console.log(JSON.stringify(entries, null, 2));
+            return;
+        }
+        if (entries.length === 0) {
+            console.log(chalk.dim("No projects known yet — `kraftwerk ui` registers the current one."));
+            return;
+        }
+        const table = new Table({
+            head: ["project", "root", "status", "last started"].map((h) => chalk.bold(h)),
+            wordWrap: true,
+            colWidths: [22, 48, 24, 14],
+        });
+        for (const e of entries) {
+            table.push([
+                `${e.icon ? e.icon + " " : ""}${chalk.cyan(e.name)}`,
+                e.rootLabel ?? chalk.dim("(no root recorded)"),
+                status(e),
+                fmtAgo(e.lastStarted),
+            ]);
+        }
+        console.log(table.toString());
+    });
+    projects
+        .command("start")
+        .description("Relaunch the UI of a stopped project (detached; logs in ~/.kraftwerk/logs)")
+        .argument("<ref>", "Project name, folder name, or root path")
+        .action(async (ref) => {
+        const entry = await resolveRef(ref);
+        if (entry.live) {
+            console.log(`${chalk.green("✔")} ${entry.name} already running: ${chalk.cyan(entry.url)}`);
+            return;
+        }
+        const r = await startProject(entry.root);
+        if (!r.ok) {
+            console.error(chalk.red(`Could not start ${entry.name}: ${r.error}`));
+            if (r.log)
+                console.error(chalk.dim(`log: ${tildify(r.log)}`));
+            process.exit(1);
+        }
+        console.log(`${chalk.green("✔")} ${entry.name} ${r.live ? "running" : "starting"}: ${chalk.cyan(r.url)}` +
+            chalk.dim(` (pid ${r.pid}${r.log ? `, log ${tildify(r.log)}` : ""})`));
+    });
+    projects
+        .command("forget")
+        .description("Remove a project from the registry (its folder is untouched)")
+        .argument("<ref>", "Project name, folder name, or root path")
+        .action(async (ref) => {
+        const entry = await resolveRef(ref);
+        if (await forgetProject(entry.root)) {
+            console.log(`${chalk.green("✔")} forgot ${entry.name} (${entry.rootLabel})`);
+        }
+        else {
+            console.error(chalk.red(`No record for ${entry.root}`));
+            process.exit(1);
+        }
+    });
+}

package/dist/cli/ui.js

@@ -1,9 +1,11 @@
 import { existsSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import chalk from "chalk";
 import { resolveProject } from "../config.js";
+import { selfCommand } from "../inspector/self-command.js";
 import { RESTART_EXIT_CODE, startInspector } from "../inspector/server.js";
 /**
  * `kraftwerk ui` — start the inspector web UI pointed at the current
@@ -59,27 +61,42 @@ export async function runUi(cwd, opts) {
 }
 /**
  * Respawn loop around the real server. Spawns this same bin script via the
- * current node — works identically for global installs, local node_modules,
- * npx, and a file: dev checkout. Any exit other than RESTART_EXIT_CODE
- * (including Ctrl-C, which signals the whole foreground group) ends the loop.
+ * current node (selfCommand) — works identically for global installs,
+ * local node_modules, npx, and a file: dev checkout. Any exit other than
+ * RESTART_EXIT_CODE ends the loop. A SIGTERM/SIGINT to the supervisor is
+ * forwarded to the server, so `kill <supervisor pid>` (what `kraftwerk
+ * projects start` reports) takes the whole UI down; Ctrl-C signals the
+ * foreground group and reaches both anyway.
  */
 async function superviseUi(opts) {
-    const args = [
-        process.argv[1],
+    const { cmd, args } = selfCommand([
         "ui",
         ...(opts.port ? ["--port", opts.port] : []),
         ...(opts.output ? ["--output", opts.output] : []),
-    ];
+    ]);
     for (;;) {
-        const child = spawn(process.execPath, args, {
+        const child = spawn(cmd, args, {
             stdio: "inherit",
             env: { ...process.env, KRAFTWERK_UI_SUPERVISED: "1" },
         });
-        const code = await new Promise((resolve) => {
-            child.once("exit", (c, signal) => resolve(signal ? null : c));
+        const forward = (sig) => () => {
+            child.kill(sig);
+        };
+        const handlers = { SIGTERM: forward("SIGTERM"), SIGINT: forward("SIGINT") };
+        process.on("SIGTERM", handlers.SIGTERM);
+        process.on("SIGINT", handlers.SIGINT);
+        const result = await new Promise((resolve) => {
+            child.once("exit", (code, signal) => resolve({ code, signal }));
         });
-        if (code !== RESTART_EXIT_CODE)
-            process.exit(code ?? 0);
+        process.off("SIGTERM", handlers.SIGTERM);
+        process.off("SIGINT", handlers.SIGINT);
+        if (result.code !== RESTART_EXIT_CODE) {
+            // A signal-killed server is not a clean exit — say so in the exit code
+            // (128 + signal, the shell convention) so callers can tell.
+            if (result.signal)
+                process.exit(128 + (os.constants.signals[result.signal] ?? 1));
+            process.exit(result.code ?? 1);
+        }
         console.log(chalk.dim("↻ relaunching the UI with the current install ..."));
     }
 }

package/dist/config.d.ts

@@ -68,6 +68,8 @@ export interface Project {
     /** Absolute run-artifact directory (may not exist yet). */
     outputDir: string;
 }
+/** True when the path exists and is a directory. */
+export declare const isDir: (p: string) => Promise<boolean>;
 /**
  * Resolve the project for a cwd: walk up until a kraftwerk.yml or a
  * workflows root appears; a .git directory is the fallback root, the cwd

package/dist/config.js

@@ -32,7 +32,8 @@ export const CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kr
 export const CONFIG_FILENAMES = ["kraftwerk.yml", "kraftwerk.yaml"];
 const WORKFLOW_ROOT_CANDIDATES = ["src/workflows", "workflows"];
 const exists = async (p) => !!(await stat(p).catch(() => null));
-const isDir = async (p) => (await stat(p).catch(() => null))?.isDirectory() ?? false;
+/** True when the path exists and is a directory. */
+export const isDir = async (p) => (await stat(p).catch(() => null))?.isDirectory() ?? false;
 async function findConfigFile(dir) {
     for (const name of CONFIG_FILENAMES) {
         const candidate = path.join(dir, name);

package/dist/inspector/instances.d.ts

@@ -1,13 +1,76 @@
+/** Durable per-project record. The root is the key; everything else derives from it. */
+export interface ProjectRecord {
+    root: string;
+    firstSeen: string;
+    lastStarted: string;
+    /** Set on clean shutdown; older than lastStarted means the last run died. */
+    lastStopped?: string;
+    startCount: number;
+}
 /** A verified running instance, shaped like a switcher entry. */
 export interface DiscoveredInstance {
     name: string;
     url: string;
     icon?: string;
     live: true;
+    root?: string;
+}
+/**
+ * One workspace as the switcher shows it: a known project (running or
+ * not) or a running instance the projects registry doesn't know yet.
+ */
+export interface WorkspaceEntry {
+    name: string;
+    /** Where the inspector answers (live) or would answer once started. */
+    url: string;
+    icon?: string;
+    live: boolean;
+    root?: string;
+    /** Root with ~ for the home dir — what the UI prints. */
+    rootLabel?: string;
+    /** False when the root directory is gone (or no longer a project of its own); start is impossible. */
+    exists?: boolean;
+    lastStarted?: string;
+    lastStopped?: string;
 }
+/** ~/… for display. */
+export declare const tildify: (p: string) => string;
 /** Write this instance's registry file (call once the server listens). */
-export declare function registerInstance(port: number): Promise<void>;
+export declare function registerInstance(port: number, root: string): Promise<void>;
 /** Remove this instance's registry file. Sync so exit handlers can call it. */
 export declare function unregisterInstance(): void;
 /** All other running instances, verified live. Cached briefly — /api/meta is polled. */
 export declare function discoverInstances(): Promise<DiscoveredInstance[]>;
+/** Upsert the project record for a root (call on every inspector start). */
+export declare function registerProject(root: string): Promise<void>;
+/** Stamp lastStopped on clean shutdown. Sync so exit handlers can call it. */
+export declare function markProjectStopped(): void;
+/** All known projects, most recently started first. */
+export declare function listProjects(): Promise<ProjectRecord[]>;
+/** Drop a project record (the root itself is untouched). */
+export declare function forgetProject(root: string): Promise<boolean>;
+/**
+ * The switcher's view: every known project joined with the live instances,
+ * plus running instances with no project record yet. The calling instance
+ * itself is left out. Live entries first, then by last start. Cached like
+ * discoverInstances — /api/meta is polled and this stats every root.
+ */
+export declare function discoverWorkspaces(): Promise<WorkspaceEntry[]>;
+export interface StartResult {
+    ok: boolean;
+    url?: string;
+    /** True once the new inspector answered its probe within the wait. */
+    live?: boolean;
+    pid?: number;
+    log?: string;
+    error?: string;
+}
+/**
+ * Launch `kraftwerk ui` for a root as a detached process (selfCommand:
+ * the bin this process runs from), logging to ~/.kraftwerk/logs/<key>.log.
+ * The reported pid is the `kraftwerk ui` supervisor, which forwards
+ * SIGTERM/SIGINT to its server child, so `kill <pid>` stops the whole UI.
+ * Waits up to ~5s for the new inspector to answer so callers can link
+ * straight to it.
+ */
+export declare function startProject(root: string): Promise<StartResult>;

package/dist/inspector/instances.js

@@ -1,23 +1,48 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import fsSync, { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isDir, resolveProject } from "../config.js";
+import { selfCommand } from "./self-command.js";
 /**
- * Instance registry: every running inspector writes a small json file to
- * ~/.kraftwerk/instances/<pid>.json so other local instances can discover
- * it — the workspace switcher lists running workspaces automatically, no
- * kraftwerk.yml `switcher:` config needed. Registered ports are verified
- * by probing /api/meta on read (fresh name/icon, detects port reuse);
- * entries that stop answering are pruned, so crashes leave no ghosts.
+ * Two registries under ~/.kraftwerk, two lifecycles:
+ *
+ * instances/<pid>.json — ephemeral. Every running inspector writes one so
+ * other local instances can discover it (the workspace switcher lists
+ * running workspaces automatically, no kraftwerk.yml `switcher:` needed).
+ * Registered ports are verified by probing /api/meta on read; entries
+ * that stop answering are pruned, so crashes leave no ghosts.
+ *
+ * projects/<hash(root)>.json — durable. One record per project root that
+ * ever ran the inspector on this machine, keyed by the root and never
+ * pruned automatically. Everything else (name, icon, port) is derived from
+ * the root's kraftwerk.yml at read time, so it is always current. A
+ * project that is not running can be started again from the switcher or
+ * `kraftwerk projects start` — that is what makes a killed UI findable.
  */
-const DIR = path.join(os.homedir(), ".kraftwerk", "instances");
-const selfFile = () => path.join(DIR, `${process.pid}.json`);
+const HOME = path.join(os.homedir(), ".kraftwerk");
+const INSTANCES_DIR = path.join(HOME, "instances");
+const PROJECTS_DIR = path.join(HOME, "projects");
+const LOGS_DIR = path.join(HOME, "logs");
+const selfFile = () => path.join(INSTANCES_DIR, `${process.pid}.json`);
 let selfPort = null;
+let selfRoot = null;
+const projectKey = (root) => createHash("sha1").update(path.resolve(root)).digest("hex").slice(0, 16);
+const projectFile = (root) => path.join(PROJECTS_DIR, `${projectKey(root)}.json`);
+/** ~/… for display. */
+export const tildify = (p) => {
+    const home = os.homedir();
+    return p === home || p.startsWith(home + path.sep) ? "~" + p.slice(home.length) : p;
+};
+/* ---------- instances (ephemeral) ---------- */
 /** Write this instance's registry file (call once the server listens). */
-export async function registerInstance(port) {
+export async function registerInstance(port, root) {
     selfPort = port;
+    selfRoot = path.resolve(root);
     try {
-        await fs.mkdir(DIR, { recursive: true });
-        const rec = { pid: process.pid, port, startedAt: new Date().toISOString() };
+        await fs.mkdir(INSTANCES_DIR, { recursive: true });
+        const rec = { pid: process.pid, port, startedAt: new Date().toISOString(), root: selfRoot };
         await fs.writeFile(selfFile(), JSON.stringify(rec));
     }
     catch { } // best-effort — without it discovery just won't see us
@@ -62,7 +87,7 @@ export async function discoverInstances() {
         return cache.entries;
     let files;
     try {
-        files = await fs.readdir(DIR);
+        files = await fs.readdir(INSTANCES_DIR);
     }
     catch {
         return [];
@@ -72,7 +97,7 @@ export async function discoverInstances() {
         .map(async (f) => {
         let rec;
         try {
-            rec = JSON.parse(await fs.readFile(path.join(DIR, f), "utf8"));
+            rec = JSON.parse(await fs.readFile(path.join(INSTANCES_DIR, f), "utf8"));
         }
         catch {
             return null;
@@ -81,10 +106,10 @@ export async function discoverInstances() {
             return null;
         const found = await probe(rec.port);
         if (!found) {
-            await fs.unlink(path.join(DIR, f)).catch(() => { }); // stale — prune
+            await fs.unlink(path.join(INSTANCES_DIR, f)).catch(() => { }); // stale — prune
             return null;
         }
-        return found;
+        return { ...found, root: rec.root };
     }));
     const entries = probed
         .filter((e) => e != null)
@@ -92,3 +117,220 @@ export async function discoverInstances() {
     cache = { at: Date.now(), entries };
     return entries;
 }
+/* ---------- projects (durable) ---------- */
+async function readProject(file) {
+    try {
+        const rec = JSON.parse(await fs.readFile(file, "utf8"));
+        if (typeof rec.root !== "string")
+            return null;
+        return {
+            root: rec.root,
+            firstSeen: rec.firstSeen ?? rec.lastStarted ?? "",
+            lastStarted: rec.lastStarted ?? rec.firstSeen ?? "",
+            lastStopped: rec.lastStopped,
+            startCount: rec.startCount ?? 1,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Upsert the project record for a root (call on every inspector start). */
+export async function registerProject(root) {
+    const abs = path.resolve(root);
+    const now = new Date().toISOString();
+    try {
+        await fs.mkdir(PROJECTS_DIR, { recursive: true });
+        const prev = await readProject(projectFile(abs));
+        const rec = {
+            root: abs,
+            firstSeen: prev?.firstSeen || now,
+            lastStarted: now,
+            startCount: (prev?.startCount ?? 0) + 1,
+        };
+        await fs.writeFile(projectFile(abs), JSON.stringify(rec, null, 2));
+    }
+    catch { } // best-effort, like the instance file
+}
+/** Stamp lastStopped on clean shutdown. Sync so exit handlers can call it. */
+export function markProjectStopped() {
+    if (!selfRoot)
+        return;
+    try {
+        const file = projectFile(selfRoot);
+        const rec = JSON.parse(fsSync.readFileSync(file, "utf8"));
+        rec.lastStopped = new Date().toISOString();
+        fsSync.writeFileSync(file, JSON.stringify(rec, null, 2));
+    }
+    catch { }
+}
+/** All known projects, most recently started first. */
+export async function listProjects() {
+    let files;
+    try {
+        files = await fs.readdir(PROJECTS_DIR);
+    }
+    catch {
+        return [];
+    }
+    const recs = await Promise.all(files.filter((f) => f.endsWith(".json")).map((f) => readProject(path.join(PROJECTS_DIR, f))));
+    return recs
+        .filter((r) => r != null)
+        .sort((a, b) => b.lastStarted.localeCompare(a.lastStarted));
+}
+/** Drop a project record (the root itself is untouched). */
+export async function forgetProject(root) {
+    try {
+        await fs.unlink(projectFile(root));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Name, icon and port a root would run with right now — read from its
+ * kraftwerk.yml. `exists` is false when the directory is gone or when the
+ * project resolves to an ancestor (its kraftwerk.yml was removed, or it
+ * sits inside another project): resolveProject walks up and never fails,
+ * so without this check a stale record would wear its parent's identity.
+ */
+async function describeRoot(root) {
+    const fallback = { name: path.basename(root), port: 1981, exists: false };
+    if (!(await isDir(root)))
+        return fallback;
+    try {
+        const project = await resolveProject(root);
+        if (path.resolve(project.root) !== path.resolve(root))
+            return fallback;
+        return {
+            name: project.config.name ?? path.basename(project.root),
+            icon: project.config.icon || undefined,
+            port: project.config.port ?? 1981,
+            exists: true,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+let wsCache = null;
+/**
+ * The switcher's view: every known project joined with the live instances,
+ * plus running instances with no project record yet. The calling instance
+ * itself is left out. Live entries first, then by last start. Cached like
+ * discoverInstances — /api/meta is polled and this stats every root.
+ */
+export async function discoverWorkspaces() {
+    if (wsCache && Date.now() - wsCache.at < 5_000)
+        return wsCache.entries;
+    const [projects, live] = await Promise.all([listProjects(), discoverInstances()]);
+    const liveByRoot = new Map(live.filter((i) => i.root).map((i) => [i.root, i]));
+    const consumed = new Set();
+    const entries = (await Promise.all(projects
+        .filter((p) => p.root !== selfRoot)
+        .map(async (p) => {
+        const base = { root: p.root, rootLabel: tildify(p.root), lastStarted: p.lastStarted, lastStopped: p.lastStopped };
+        let running = liveByRoot.get(p.root);
+        let d;
+        if (!running) {
+            d = await describeRoot(p.root);
+            // A pre-0.33 inspector still serving this root registered no
+            // root — match it by the port the root would use, else the
+            // switcher shows the same project twice (live + stopped).
+            running = live.find((i) => !i.root && i.url === `http://localhost:${d.port}`);
+        }
+        if (running) {
+            consumed.add(running);
+            return { ...base, name: running.name, url: running.url, icon: running.icon, live: true, exists: true };
+        }
+        return { ...base, name: d.name, url: `http://localhost:${d.port}`, icon: d.icon, live: false, exists: d.exists };
+    }))).concat(await Promise.all(live
+        .filter((i) => !consumed.has(i))
+        .map(async (i) => ({
+        name: i.name,
+        url: i.url,
+        icon: i.icon,
+        live: true,
+        root: i.root,
+        rootLabel: i.root ? tildify(i.root) : undefined,
+        exists: i.root ? await isDir(i.root) : undefined,
+    }))));
+    entries.sort((a, b) => {
+        if (a.live !== b.live)
+            return a.live ? -1 : 1;
+        return (b.lastStarted ?? "").localeCompare(a.lastStarted ?? "") || a.name.localeCompare(b.name);
+    });
+    wsCache = { at: Date.now(), entries };
+    return entries;
+}
+/**
+ * Launch `kraftwerk ui` for a root as a detached process (selfCommand:
+ * the bin this process runs from), logging to ~/.kraftwerk/logs/<key>.log.
+ * The reported pid is the `kraftwerk ui` supervisor, which forwards
+ * SIGTERM/SIGINT to its server child, so `kill <pid>` stops the whole UI.
+ * Waits up to ~5s for the new inspector to answer so callers can link
+ * straight to it.
+ */
+export async function startProject(root) {
+    const abs = path.resolve(root);
+    const { name, port, exists } = await describeRoot(abs);
+    if (!exists)
+        return { ok: false, error: `not a project directory (missing or moved): ${abs}` };
+    const url = `http://localhost:${port}`;
+    if (abs === selfRoot)
+        return { ok: false, url, live: true, error: "that is this workspace" };
+    // Already running, or the port is taken by another kraftwerk?
+    cache = wsCache = null;
+    const live = await discoverInstances();
+    const byRoot = live.find((i) => i.root === abs);
+    if (byRoot)
+        return { ok: true, url: byRoot.url, live: true };
+    if (port === selfPort)
+        return { ok: false, url, error: `port ${port} is used by this workspace` };
+    const byPort = live.find((i) => i.url === url);
+    if (byPort)
+        return { ok: false, url, error: `port ${port} is used by "${byPort.name}"` };
+    let log;
+    let stdio = ["ignore", "ignore", "ignore"];
+    try {
+        await fs.mkdir(LOGS_DIR, { recursive: true });
+        log = path.join(LOGS_DIR, `${projectKey(abs)}.log`);
+        const fd = fsSync.openSync(log, "a");
+        fsSync.writeSync(fd, `\n--- ${new Date().toISOString()} start ${name} (${abs}) ---\n`);
+        stdio = ["ignore", fd, fd];
+    }
+    catch { }
+    const { cmd, args } = selfCommand(["ui"]);
+    let child;
+    try {
+        const env = { ...process.env };
+        delete env.KRAFTWERK_UI_SUPERVISED; // the new one runs its own supervisor
+        child = spawn(cmd, args, { cwd: abs, detached: true, stdio, env });
+        child.unref();
+    }
+    catch (err) {
+        return { ok: false, url, log, error: err.message };
+    }
+    if (typeof stdio[1] === "number") {
+        try {
+            fsSync.closeSync(stdio[1]);
+        }
+        catch { }
+    }
+    let exited = null;
+    child.once("exit", (code, signal) => {
+        exited = signal ? `killed by ${signal}` : `exited with code ${code}`;
+    });
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 300));
+        if (exited)
+            return { ok: false, url, pid: child.pid, log, error: `kraftwerk ui ${exited}` };
+        if (await probe(port)) {
+            cache = wsCache = null;
+            return { ok: true, url, live: true, pid: child.pid, log };
+        }
+    }
+    return { ok: true, url, live: false, pid: child.pid, log };
+}

package/dist/inspector/self-command.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How to run "this same kraftwerk" as a new process: the node we run on
+ * plus the bin script we were started from. Identical for global installs,
+ * local node_modules, npx caches and a dev checkout (bin/kraftwerk.js
+ * picks src/ vs dist/ itself). Shared by the `kraftwerk ui` supervisor and
+ * the project-start feature so bin resolution lives in one place.
+ *
+ * If the bin file is gone (npx cache pruned, package removed) the
+ * fallback is `npx @netnodeag/kraftwerk`, i.e. the registry's latest —
+ * not the running version, but better than nothing.
+ */
+export declare function selfCommand(args: string[]): {
+    cmd: string;
+    args: string[];
+};