@netnodeag/kraftwerk 0.32.1 → 0.34.0

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, pid: rec.pid };
     }));
     const entries = probed
         .filter((e) => e != null)
@@ -92,3 +117,339 @@ 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;
+}
+const countDirs = async (dir, marker) => {
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        const dirs = entries.filter((e) => e.isDirectory() && !e.name.startsWith("."));
+        if (!marker)
+            return dirs.length;
+        const flags = await Promise.all(dirs.map((d) => fs.stat(path.join(dir, d.name, marker)).then(() => true, () => false)));
+        return flags.filter(Boolean).length;
+    }
+    catch {
+        return 0;
+    }
+};
+const countEntries = async (dir) => {
+    try {
+        return (await fs.readdir(dir)).filter((n) => !n.startsWith(".")).length;
+    }
+    catch {
+        return 0;
+    }
+};
+/**
+ * Every workspace including this one, with config presence, counts of
+ * what lives in the root, and a single derived state. Not cached — the
+ * admin screen polls slowly and wants fresh counts.
+ */
+export async function listWorkspacesDetailed() {
+    const others = await discoverWorkspaces();
+    const all = [...others];
+    if (selfRoot && selfPort) {
+        const d = await describeRoot(selfRoot);
+        const rec = await readProject(projectFile(selfRoot));
+        all.unshift({
+            name: d.name,
+            icon: d.icon,
+            url: `http://localhost:${selfPort}`,
+            live: true,
+            root: selfRoot,
+            rootLabel: tildify(selfRoot),
+            exists: true,
+            lastStarted: rec?.lastStarted,
+            lastStopped: rec?.lastStopped,
+        });
+    }
+    return Promise.all(all.map(async (e) => {
+        const current = !!selfRoot && e.root === selfRoot;
+        const base = { ...e, current, state: e.live ? "running" : "stopped" };
+        if (!e.root)
+            return base;
+        const rec = await readProject(projectFile(e.root));
+        base.firstSeen = rec?.firstSeen;
+        base.startCount = rec?.startCount;
+        // "missing" = the folder is gone; "orphaned" = it is still there but
+        // no longer a project of its own (kraftwerk.yml removed, or it now
+        // resolves to an ancestor). Both are removable from the registry.
+        const dirGone = !(await isDir(e.root));
+        base.dirGone = dirGone;
+        if (!e.live) {
+            if (dirGone)
+                base.state = "missing";
+            else if (e.exists === false)
+                base.state = "orphaned";
+            else if (!(rec?.lastStopped && rec.lastStarted && rec.lastStopped >= rec.lastStarted))
+                base.state = "died";
+        }
+        if (e.exists === false) {
+            base.hasConfig = false;
+            return base;
+        }
+        try {
+            const project = await resolveProject(e.root);
+            base.hasConfig = !!project.configPath && path.dirname(project.configPath) === path.resolve(e.root);
+            const [agents, workflows, runs, chats] = await Promise.all([
+                countDirs(path.resolve(project.root, project.config.agents ?? "agents"), "agent.yml"),
+                project.workflowsRoot ? countDirs(project.workflowsRoot, "workflow.yml") : Promise.resolve(0),
+                countDirs(path.join(project.outputDir, "runs")),
+                countEntries(path.join(project.outputDir, "chats")),
+            ]);
+            base.counts = { agents, workflows, runs, chats };
+        }
+        catch {
+            base.hasConfig = false;
+        }
+        return base;
+    }));
+}
+/**
+ * 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 };
+}
+/* ---------- stop a project ---------- */
+/**
+ * Stop a running workspace: SIGTERM to its server process, which
+ * unregisters, stamps lastStopped and exits; the `kraftwerk ui` supervisor
+ * follows. Matched by root, or by url for instances from older versions
+ * that registered no root. Waits up to ~5s for the port to go quiet.
+ */
+export async function stopProject(target) {
+    if (target.root && path.resolve(target.root) === selfRoot) {
+        return { ok: false, error: "that is this workspace — stop it from its own terminal or pid" };
+    }
+    cache = wsCache = null;
+    const live = await discoverInstances();
+    const inst = live.find((i) => (target.root && i.root === path.resolve(target.root)) || (target.url && i.url === target.url));
+    if (!inst)
+        return { ok: false, error: "not running" };
+    try {
+        process.kill(inst.pid, "SIGTERM");
+    }
+    catch (err) {
+        return { ok: false, error: `could not signal pid ${inst.pid}: ${err.message}` };
+    }
+    const port = Number(new URL(inst.url).port);
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 250));
+        if (!(await probe(port))) {
+            cache = wsCache = null;
+            return { ok: true };
+        }
+    }
+    return { ok: false, error: `pid ${inst.pid} still answers on ${inst.url} after 5s` };
+}

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[];
+};

package/dist/inspector/self-command.js

@@ -0,0 +1,18 @@
+import { existsSync } from "node:fs";
+/**
+ * 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 function selfCommand(args) {
+    const bin = process.argv[1];
+    if (bin && existsSync(bin))
+        return { cmd: process.execPath, args: [bin, ...args] };
+    return { cmd: "npx", args: ["-y", "@netnodeag/kraftwerk", ...args] };
+}

package/dist/inspector/server.js

@@ -10,7 +10,7 @@ import { cancelChat, createChat, deleteChat, disposeAllBackends, getChat, listCh
 import { bundleDetail, conceptDetail, createBundle, knowledgeIndex, putConcept, verifyFromUi, } from "./knowledge.js";
 import { deleteMember, getMember, listMembers, saveMember, setMemberArchived, teamRoot, } from "./team.js";
 import { deleteAgentSkill, getSkill, listAgentSkills, listSkills, readSkill, saveAgentSkill, skillsRoot, } from "./skills.js";
-import { discoverInstances, registerInstance, unregisterInstance } from "./instances.js";
+import { discoverWorkspaces, forgetProject, listWorkspacesDetailed, markProjectStopped, registerInstance, registerProject, startProject, stopProject, tildify, unregisterInstance, } from "./instances.js";
 import { getSettings, saveSettings } from "./settings.js";
 import { deleteRoutine, routineStatuses, runRoutineNow, saveRoutine, startRoutineScheduler, } from "./routines.js";
 /**
@@ -98,15 +98,17 @@ async function handleApi(req, res, url) {
         const project = await resolveProject(getProjectRoot()).catch(() => null);
         const projectName = project?.config.name ?? (project ? path.basename(project.root) : "");
         const manual = project?.config.switcher ?? [];
-        const discovered = url.searchParams.get("probe") === "1" ? [] : await discoverInstances();
+        const discovered = url.searchParams.get("probe") === "1" ? [] : await discoverWorkspaces();
         // Manual switcher entries keep their configured name/icon; discovered
-        // instances that duplicate one only contribute the live flag.
+        // workspaces that duplicate one (same url, running) only contribute
+        // the live flag. Stopped projects never collide — they carry a root,
+        // and a manual entry pointing at the same port is just a link.
         const norm = (u) => u.replace(/\/+$/, "").replace("127.0.0.1", "localhost").toLowerCase();
         const manualUrls = new Set(manual.map((e) => norm(e.url)));
-        const liveUrls = new Set(discovered.map((d) => norm(d.url)));
+        const liveUrls = new Set(discovered.filter((d) => d.live).map((d) => norm(d.url)));
         const switcher = [
             ...manual.map((e) => (liveUrls.has(norm(e.url)) ? { ...e, live: true } : e)),
-            ...discovered.filter((d) => !manualUrls.has(norm(d.url))),
+            ...discovered.filter((d) => !(d.live && manualUrls.has(norm(d.url)))),
         ];
         return json(res, {
             version: await getPkgVersion(),
@@ -116,9 +118,54 @@ async function handleApi(req, res, url) {
             restartable: supervised(),
             projectName,
             projectIcon: project?.config.icon ?? "",
+            projectRoot: project?.root ?? getProjectRoot(),
+            projectRootLabel: tildify(project?.root ?? getProjectRoot()),
             switcher,
         });
     }
+    // GET /api/projects — every known workspace incl. this one, with state + counts (admin screen)
+    if (seg.length === 2 && seg[1] === "projects" && method === "GET") {
+        return json(res, await listWorkspacesDetailed());
+    }
+    // POST /api/projects/start {root} — launch `kraftwerk ui` for a known
+    // project as a detached process (the switcher's Start button).
+    if (seg.length === 3 && seg[1] === "projects" && seg[2] === "start" && method === "POST") {
+        try {
+            const { root } = JSON.parse(await readBody(req));
+            if (!root)
+                return json(res, { error: "root required" }, 400);
+            const result = await startProject(root);
+            return json(res, result, result.ok ? 200 : 409);
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // POST /api/projects/stop {root | url} — SIGTERM a running workspace's server
+    if (seg.length === 3 && seg[1] === "projects" && seg[2] === "stop" && method === "POST") {
+        try {
+            const target = JSON.parse(await readBody(req));
+            if (!target.root && !target.url)
+                return json(res, { error: "root or url required" }, 400);
+            const result = await stopProject(target);
+            return json(res, result, result.ok ? 200 : 409);
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // POST /api/projects/forget {root} — drop a project from the registry
+    if (seg.length === 3 && seg[1] === "projects" && seg[2] === "forget" && method === "POST") {
+        try {
+            const { root } = JSON.parse(await readBody(req));
+            if (!root)
+                return json(res, { error: "root required" }, 400);
+            return json(res, { ok: await forgetProject(root) });
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
     // GET /api/settings — kraftwerk.yml (parsed + resolved paths) for the settings page
     if (seg.length === 2 && seg[1] === "settings" && method === "GET") {
         return json(res, await getSettings());
@@ -618,12 +665,16 @@ export function startInspector(opts) {
         process.once(sig, () => {
             disposeAllBackends();
             unregisterInstance();
+            markProjectStopped();
             process.exit(sig === "SIGINT" ? 130 : 143);
         });
     }
-    process.once("exit", () => {
+    process.once("exit", (code) => {
         disposeAllBackends();
         unregisterInstance();
+        // A self-restart (new version) is not a stop — the project stays "running".
+        if (code !== RESTART_EXIT_CODE)
+            markProjectStopped();
     });
     const server = http.createServer(async (req, res) => {
         try {
@@ -641,7 +692,9 @@ export function startInspector(opts) {
         server.once("error", reject);
         server.listen(opts.port, () => {
             const addr = server.address();
-            void registerInstance(typeof addr === "object" && addr ? addr.port : opts.port);
+            const port = typeof addr === "object" && addr ? addr.port : opts.port;
+            void registerInstance(port, getProjectRoot());
+            void registerProject(getProjectRoot());
             resolve(server);
         });
     });