@netnodeag/kraftwerk 0.32.0 → 0.33.0

package/README.md

@@ -1,26 +1,31 @@
-# kraftwerk
+# Kraftwerk
 
 **Agentic workspace.** Kraftwerk is an open-source agentic workspace where
-humans and persistent AI coworkers work on real tasks together.
-
-**Why it exists.** We think every team needs a place to bring persistent AI
-coworkers and humans together to get work done. Today, AI work mostly lives in
-individual silos: personal prompts, Claude Code sessions, scripts, and one-off
-automations. Kraftwerk turns individual AI use into shared, repeatable ways of
-working across a team or organisation.
-
-**How it works.** Kraftwerk brings together:
-
-- **Agents** — persistent AI coworkers, each with its own identity and memory,
-  running on Claude Code, Codex, Pi, and others
+humans and persistent AI coworkers work on real tasks together. Agents,
+knowledge, skills and workflows belong to the team, not to the person who
+happened to set them up, and every result is checked before anyone relies on
+it.
+
+**Why teams need it.** AI work today lives in individual silos: personal
+prompts, Claude Code sessions, scripts, and one-off automations. Kraftwerk
+gives a team or organisation one place where AI use becomes shared,
+repeatable practice: agents that remember and are accountable, knowledge that
+is curated and verified, workflows whose results are checked before the work
+moves on.
+
+**What's in the workspace.**
+
+- **Agents** — persistent AI coworkers, each with its own identity, memory
+  and standing orders, running on Claude Code, Codex, Pi, and others
+- **Knowledge** — shared organisational and project context, browsed like a
+  wiki, edited with autosave, verified by humans, exportable as PDF
 - **Skills** — reusable capabilities and ways of working
-- **Knowledge** — shared organisational and project context
 - **Workflows** — repeatable multi-step processes
 - **Verification** — deterministic gates that check the work
+- **Inspector** — the web UI that brings it all together
 
-**The shift.** From everyone using AI individually → to the organisation
-working agentically. Kraftwerk is the shared place where that work lives,
-runs, and improves over time.
+This README is the reference for the framework and CLI. For the overview,
+start at the [project README](https://github.com/NETNODEAG/kraftwerk#readme).
 
 ## Under the hood
 

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>;