@netnodeag/kraftwerk 0.3.0 → 0.4.0

package/README.md

@@ -340,8 +340,10 @@ npm publish         # runs npm run build first via prepublishOnly
 ```
 
 The tarball is whitelisted via `files`: `bin/`, `dist/`, `runner/`
-(Dockerfile for sandboxed runs), `schema/` (workflow JSON schema), and the
-inspector sources (for `kraftwerk ui`; its deps install on first launch) —
-no `src/` or examples. Check with `npm pack --dry-run` before a
-release. Runtime deps stay regular `dependencies`; `tsx` and `typescript`
-are dev-only, so consumers install neither.
+(Dockerfile for sandboxed runs), `schema/` (workflow JSON schema), and
+`inspector/dist/` (the prebuilt web UI for `kraftwerk ui` — built by
+`prepublishOnly`, served by the dependency-free server compiled into
+`dist/inspector/`) — no `src/` or examples. Check with `npm pack
+--dry-run` before a release. Runtime deps stay regular `dependencies`;
+`tsx`, `typescript`, and the inspector's Vite/React toolchain are
+dev-only, so consumers install none of them.

package/dist/cli/ui.js

@@ -1,48 +1,52 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawn, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import chalk from "chalk";
 import { resolveProject } from "../config.js";
+import { startInspector } from "../inspector/server.js";
 /**
- * `kraftwerk ui` — start the inspector web UI (Next.js app shipped in the
- * package under inspector/) pointed at the current project's output dir.
- * First launch installs the inspector's dependencies; the server then runs
- * in the foreground until Ctrl-C.
+ * `kraftwerk ui` — start the inspector web UI pointed at the current
+ * project's output dir. The server is dependency-free node:http (part of
+ * this package); the frontend is a prebuilt Vite bundle shipped in
+ * inspector/dist. Nothing to install at runtime — the server starts
+ * instantly and runs in the foreground until Ctrl-C.
  */
 /** Package root is two levels up from this file (src/cli/ or dist/cli/). */
-const inspectorDir = () => path.join(path.dirname(fileURLToPath(import.meta.url)), "../../inspector");
-export async function runUi(cwd, opts) {
-    const dir = inspectorDir();
-    if (!existsSync(path.join(dir, "package.json"))) {
-        console.error(chalk.red(`Inspector not found at ${dir} — broken install?`));
+const packageRoot = () => path.join(path.dirname(fileURLToPath(import.meta.url)), "../..");
+/**
+ * Published packages ship inspector/dist. A dev checkout builds it on
+ * first use (and after frontend edits: `npm run build` in inspector/).
+ */
+function ensureBuilt() {
+    const inspector = path.join(packageRoot(), "inspector");
+    const dist = path.join(inspector, "dist");
+    if (existsSync(path.join(dist, "index.html")))
+        return dist;
+    if (!existsSync(path.join(inspector, "src"))) {
+        console.error(chalk.red(`Inspector assets missing at ${dist} — broken install?`));
         process.exit(1);
     }
-    const outputDir = opts.output
-        ? path.resolve(cwd, opts.output)
-        : (await resolveProject(cwd)).outputDir;
-    const port = opts.port ?? "4499";
-    if (!existsSync(path.join(dir, "node_modules"))) {
-        console.log(chalk.dim("First launch — installing inspector dependencies ..."));
-        const install = spawnSync("npm", ["install", "--no-fund", "--no-audit"], {
-            cwd: dir,
-            stdio: "inherit",
-        });
-        if (install.status !== 0) {
-            console.error(chalk.red("npm install failed in the inspector directory."));
+    console.log(chalk.dim("Building the inspector frontend (first use in this checkout) ..."));
+    for (const args of [
+        ...(existsSync(path.join(inspector, "node_modules")) ? [] : [["install", "--no-fund", "--no-audit"]]),
+        ["run", "build"],
+    ]) {
+        const r = spawnSync("npm", args, { cwd: inspector, stdio: "inherit" });
+        if (r.status !== 0) {
+            console.error(chalk.red(`npm ${args.join(" ")} failed in inspector/.`));
             process.exit(1);
         }
     }
+    return dist;
+}
+export async function runUi(cwd, opts) {
+    const staticDir = ensureBuilt();
+    const outputDir = opts.output
+        ? path.resolve(cwd, opts.output)
+        : (await resolveProject(cwd)).outputDir;
+    const port = Number(opts.port ?? "4499");
+    await startInspector({ outputDir, staticDir, port });
     console.log(`${chalk.green("✔")} Inspector: ${chalk.cyan(`http://localhost:${port}`)} ` +
         chalk.dim(`(output: ${outputDir})`));
-    const nextBin = path.join(dir, "node_modules", "next", "dist", "bin", "next");
-    const child = spawn(process.execPath, [nextBin, "dev", "-p", port], {
-        cwd: dir,
-        stdio: "inherit",
-        env: { ...process.env, KRAFTWERK_OUTPUT: outputDir },
-    });
-    for (const signal of ["SIGINT", "SIGTERM"]) {
-        process.on(signal, () => child.kill(signal));
-    }
-    child.on("exit", (code) => process.exit(code ?? 0));
 }

package/dist/inspector/context.d.ts

@@ -0,0 +1,5 @@
+export declare function setOutputDir(dir: string): void;
+/** Absolute output directory (one run-* folder per run). */
+export declare function getOutputDir(): string;
+/** The consumer project root is the parent of the output dir. */
+export declare function getProjectRoot(): string;

package/dist/inspector/context.js

@@ -0,0 +1,19 @@
+import path from "node:path";
+/**
+ * Server-side context for the inspector: which consumer project it looks at.
+ * Set once by startInspector() before any request is served.
+ */
+let outputDir = "";
+export function setOutputDir(dir) {
+    outputDir = path.resolve(dir);
+}
+/** Absolute output directory (one run-* folder per run). */
+export function getOutputDir() {
+    if (!outputDir)
+        throw new Error("inspector context not initialized");
+    return outputDir;
+}
+/** The consumer project root is the parent of the output dir. */
+export function getProjectRoot() {
+    return path.dirname(getOutputDir());
+}

package/dist/inspector/runner.d.ts

@@ -0,0 +1,13 @@
+export declare function dockerStatus(): {
+    available: boolean;
+    image: boolean;
+};
+export declare function triggerRun(opts: {
+    workflowName: string;
+    request: string;
+    sandbox: boolean;
+    ssh: boolean;
+}): {
+    runId: string;
+};
+export declare function stopRun(runId: string): boolean;

package/dist/inspector/runner.js

@@ -0,0 +1,66 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, openSync, closeSync } from "node:fs";
+import path from "node:path";
+import { getProjectRoot } from "./context.js";
+/**
+ * Workflow trigger for the web UI. The inspector stays decoupled from the
+ * framework runtime: it shells out to `npx kraftwerk run` in the consumer
+ * project, detached, with a pre-chosen --run-id so the browser can jump to
+ * /runs/<id> immediately and watch the (already polling) live timeline.
+ *
+ * Sandbox mode adds --sandbox: one Docker container per run, workflow
+ * mounted read-only, run dir bind-mounted back into output/ (see
+ * kraftwerk/src/runner/docker.ts).
+ */
+function stamp(d = new Date()) {
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}-${p(d.getSeconds())}`;
+}
+export function dockerStatus() {
+    const daemon = spawnSync("docker", ["version", "--format", "ok"], {
+        stdio: "ignore",
+        timeout: 8000,
+    });
+    if (daemon.status !== 0)
+        return { available: false, image: false };
+    const image = spawnSync("docker", ["image", "inspect", "kraftwerk-runner"], {
+        stdio: "ignore",
+        timeout: 8000,
+    });
+    return { available: true, image: image.status === 0 };
+}
+export function triggerRun(opts) {
+    if (opts.sandbox) {
+        const docker = dockerStatus();
+        if (!docker.available)
+            throw new Error("Docker daemon not reachable — start Docker first.");
+        if (!docker.image)
+            throw new Error('Image "kraftwerk-runner" missing — run `kraftwerk runner build`.');
+    }
+    const runId = `run-${stamp()}`;
+    // Matches the CLI's --run-id resolution: output/<id> under the project root.
+    const runDir = path.join(getProjectRoot(), "output", runId);
+    mkdirSync(runDir, { recursive: true });
+    const log = openSync(path.join(runDir, "trigger.log"), "a");
+    const args = ["kraftwerk", "run", "--yes", "--run-id", runId];
+    if (opts.sandbox)
+        args.push("--sandbox");
+    if (opts.ssh)
+        args.push("--ssh");
+    args.push(opts.workflowName, opts.request);
+    const child = spawn("npx", args, {
+        cwd: getProjectRoot(),
+        detached: true,
+        stdio: ["ignore", log, log],
+        env: { ...process.env, FORCE_COLOR: "0" },
+    });
+    child.unref();
+    closeSync(log);
+    return { runId };
+}
+export function stopRun(runId) {
+    // Sandboxed runs run in container kw-<runId>; docker stop ends them.
+    if (!/^run-[0-9-]+$/.test(runId))
+        return false;
+    return (spawnSync("docker", ["stop", `kw-${runId}`], { stdio: "ignore", timeout: 30_000 }).status === 0);
+}

package/dist/inspector/runs.d.ts

@@ -0,0 +1,57 @@
+export type RunStatus = "running" | "ok" | "failed" | "aborted";
+export interface GateView {
+    gate: string;
+    passed: boolean;
+    failure: string | null;
+}
+export interface PhaseView {
+    phase: string;
+    kind: "agent" | "script";
+    agent?: string;
+    model?: string;
+    harness?: string;
+    status: "running" | "ok" | "failed" | "blocked" | "pending";
+    attempts: number;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    costUsd?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    gates: GateView[];
+    summary?: string;
+    lastActivity?: string;
+    stdout?: string;
+    stderr?: string;
+}
+export interface FileView {
+    name: string;
+    size: number;
+    mtime: string;
+}
+export interface RunListItem {
+    id: string;
+    workflow?: string;
+    request?: string;
+    status: RunStatus;
+    startedAt?: string;
+    updatedAt: string;
+    phasesDone: number;
+    phasesTotal?: number;
+    currentPhase?: string;
+    durationMs?: number;
+    costUsd?: number;
+}
+export interface RunDetail extends RunListItem {
+    description?: string;
+    steps?: string[];
+    phases: PhaseView[];
+    files: FileView[];
+}
+export declare function listRuns(): Promise<RunListItem[]>;
+export declare function safeRunDir(id: string): string;
+export declare function getRun(id: string): Promise<RunDetail | null>;
+export declare function readRunFile(id: string, name: string): Promise<{
+    absPath: string;
+    size: number;
+} | null>;

package/dist/inspector/runs.js

@@ -0,0 +1,240 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { getOutputDir } from "./context.js";
+/**
+ * Filesystem + trace.jsonl reading for the inspector. The output directory
+ * holds one folder per run (run-YYYY-MM-DD-HHMM-SS); every run folder has a
+ * trace.jsonl written by the framework plus the run's working files.
+ */
+/** A run with no trace update for this long and no summary counts as aborted. */
+const STALE_MS = 15 * 60 * 1000;
+async function readTrace(runDir) {
+    let raw;
+    try {
+        raw = await fs.readFile(path.join(runDir, "trace.jsonl"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            /* partially written last line of a live run */
+        }
+    }
+    return events;
+}
+function analyse(events) {
+    const runStart = events.find((e) => e.event === "run_start");
+    const summary = events.find((e) => e.event === "run_summary");
+    const phases = [];
+    const byName = new Map();
+    for (const e of events) {
+        if (e.event === "phase_start") {
+            const p = {
+                phase: e.phase,
+                kind: e.kind === "script" ? "script" : "agent",
+                agent: e.agent,
+                model: e.model,
+                harness: e.harness,
+                status: "running",
+                attempts: 0,
+                startedAt: e.ts,
+                gates: [],
+            };
+            phases.push(p);
+            byName.set(e.phase, p);
+            continue;
+        }
+        const p = byName.get(e.phase);
+        if (!p)
+            continue;
+        switch (e.event) {
+            case "tool_use":
+                p.lastActivity = `${e.tool} ${e.target ? shortenPath(e.target) : ""}`.trim();
+                break;
+            case "agent_result":
+                p.attempts = (e.attempt ?? 0) + 1;
+                break;
+            case "script_result":
+                p.attempts += 1;
+                p.stdout = e.stdout || undefined;
+                p.stderr = e.stderr || undefined;
+                break;
+            case "envelope":
+                p.summary = e.envelope?.summary;
+                break;
+            case "gate_result":
+                p.gates.push({ gate: e.gate, passed: e.passed, failure: e.failure ?? null });
+                break;
+            case "phase_end":
+                p.status = e.status === "ok" ? "ok" : e.status === "blocked" ? "blocked" : "failed";
+                p.endedAt = e.ts;
+                if (e.stats) {
+                    p.durationMs = e.stats.durationMs;
+                    p.costUsd = e.stats.costUsd;
+                    p.tokensIn =
+                        (e.stats.inputTokens ?? 0) +
+                            (e.stats.cacheReadTokens ?? 0) +
+                            (e.stats.cacheCreationTokens ?? 0);
+                    p.tokensOut = e.stats.outputTokens ?? 0;
+                    p.attempts = e.stats.attempts ?? p.attempts;
+                }
+                break;
+        }
+    }
+    // Only keep the last attempt's gate results per gate name.
+    for (const p of phases) {
+        const last = new Map();
+        for (const g of p.gates)
+            last.set(g.gate, g);
+        p.gates = [...last.values()];
+    }
+    // Steps declared at run_start that have not started yet are pending.
+    // run_start.steps is either string[] (older traces) or {name, kind, agent, model}[].
+    const rawSteps = runStart?.steps;
+    const steps = rawSteps?.map((s) => (typeof s === "string" ? s : s.name));
+    if (rawSteps) {
+        for (const s of rawSteps) {
+            const name = typeof s === "string" ? s : s.name;
+            if (!byName.has(name)) {
+                phases.push({
+                    phase: name,
+                    kind: typeof s === "string" ? "script" : s.kind,
+                    agent: typeof s === "string" ? undefined : s.agent,
+                    model: typeof s === "string" ? undefined : s.model,
+                    status: "pending",
+                    attempts: 0,
+                    gates: [],
+                });
+            }
+        }
+    }
+    const failed = phases.some((p) => p.status === "failed" || p.status === "blocked");
+    const lastTs = events.length ? events[events.length - 1].ts : undefined;
+    let status;
+    if (summary)
+        status = failed ? "failed" : "ok";
+    else if (failed)
+        status = "failed";
+    else if (lastTs && Date.now() - Date.parse(lastTs) > STALE_MS)
+        status = "aborted";
+    else
+        status = "running";
+    return { runStart, summary, phases, steps, status, lastTs };
+}
+/**
+ * Sandboxed runs write runner.json (exit code recorded when the container
+ * ends). If the trace looks "running" but the container already exited —
+ * e.g. it crashed before any phase_end — trust the exit code instead of
+ * waiting for the 15-minute stale timeout.
+ */
+async function applyRunnerVerdict(runDir, a) {
+    if (a.status !== "running")
+        return a;
+    try {
+        const meta = JSON.parse(await fs.readFile(path.join(runDir, "runner.json"), "utf8"));
+        if (meta.exitCode != null) {
+            a.status = meta.exitCode === 0 ? "ok" : "failed";
+            if (meta.exitCode !== 0) {
+                for (const p of a.phases)
+                    if (p.status === "running")
+                        p.status = "failed";
+            }
+        }
+    }
+    catch {
+        /* no runner.json (local run) or unreadable — keep trace-based status */
+    }
+    return a;
+}
+function shortenPath(p) {
+    const parts = p.split("/");
+    return parts.length > 2 ? parts.slice(-2).join("/") : p;
+}
+export async function listRuns() {
+    let entries;
+    try {
+        entries = (await fs.readdir(getOutputDir())).filter((e) => e.startsWith("run-"));
+    }
+    catch {
+        return [];
+    }
+    const items = await Promise.all(entries.map(async (id) => {
+        const runDir = path.join(getOutputDir(), id);
+        const st = await fs.stat(runDir).catch(() => null);
+        if (!st?.isDirectory())
+            return null;
+        const events = await readTrace(runDir);
+        const { runStart, summary, phases, steps, status, lastTs } = await applyRunnerVerdict(runDir, analyse(events));
+        const done = phases.filter((p) => p.status === "ok").length;
+        const current = phases.find((p) => p.status === "running")?.phase;
+        return {
+            id,
+            workflow: runStart?.workflow,
+            request: runStart?.request,
+            status,
+            startedAt: events[0]?.ts,
+            updatedAt: lastTs ?? st.mtime.toISOString(),
+            phasesDone: done,
+            phasesTotal: steps?.length ?? (summary ? phases.length : undefined),
+            currentPhase: current,
+            durationMs: summary?.total?.durationMs,
+            costUsd: summary?.total?.costUsd,
+        };
+    }));
+    return items.filter(Boolean).sort((a, b) => b.id.localeCompare(a.id));
+}
+export function safeRunDir(id) {
+    if (!/^run-[0-9-]+$/.test(id))
+        throw new Error("invalid run id");
+    return path.join(getOutputDir(), id);
+}
+export async function getRun(id) {
+    const runDir = safeRunDir(id);
+    const st = await fs.stat(runDir).catch(() => null);
+    if (!st?.isDirectory())
+        return null;
+    const events = await readTrace(runDir);
+    const { runStart, summary, phases, steps, status, lastTs } = await applyRunnerVerdict(runDir, analyse(events));
+    const names = await fs.readdir(runDir);
+    const files = [];
+    for (const name of names) {
+        const fst = await fs.stat(path.join(runDir, name)).catch(() => null);
+        if (fst?.isFile())
+            files.push({ name, size: fst.size, mtime: fst.mtime.toISOString() });
+    }
+    files.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        id,
+        workflow: runStart?.workflow,
+        description: runStart?.description,
+        request: runStart?.request,
+        status,
+        startedAt: events[0]?.ts,
+        updatedAt: lastTs ?? st.mtime.toISOString(),
+        phasesDone: phases.filter((p) => p.status === "ok").length,
+        phasesTotal: steps?.length ?? (summary ? phases.length : undefined),
+        currentPhase: phases.find((p) => p.status === "running")?.phase,
+        durationMs: summary?.total?.durationMs,
+        costUsd: summary?.total?.costUsd,
+        steps,
+        phases,
+        files,
+    };
+}
+export async function readRunFile(id, name) {
+    const runDir = safeRunDir(id);
+    const absPath = path.resolve(runDir, name);
+    if (absPath !== path.join(runDir, path.basename(name)))
+        throw new Error("invalid file name");
+    const st = await fs.stat(absPath).catch(() => null);
+    if (!st?.isFile())
+        return null;
+    return { absPath, size: st.size };
+}

package/dist/inspector/server.d.ts

@@ -0,0 +1,8 @@
+import http from "node:http";
+export interface InspectorOptions {
+    outputDir: string;
+    staticDir: string;
+    port: number;
+}
+/** Start the server; resolves once it listens. Runs until the process ends. */
+export declare function startInspector(opts: InspectorOptions): Promise<http.Server>;