@netnodeag/kraftwerk 0.2.0

package/dist/cli/init.js

@@ -0,0 +1,81 @@
+import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+import { SCHEMA_URL } from "../config.js";
+/**
+ * `kraftwerk init` — make any repository a kraftwerk consumer in one
+ * command: kraftwerk.yml (root marker + config), workflows/ with a runnable
+ * example, and an output/ ignore entry. Everything is idempotent: existing
+ * files are left untouched and reported.
+ */
+const CONFIG_TEMPLATE = `# kraftwerk project config — also marks the project root for the CLI.
+# All fields optional. Docs: https://github.com/NETNODEAG/kraftwerk
+workflows: workflows   # where workflows live
+output: output         # where run artifacts land (git-ignored)
+`;
+const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
+name: hello
+description: "Example workflow: one agent answers the request in a file"
+workspace: |
+  Files: answer.md (the result).
+agents:
+  assistant:
+    model: haiku
+    tools: [Read, Write, Edit]
+    persona: prompts/assistant.md
+steps:
+  - name: answer
+    agent: assistant
+    prompt: prompts/answer.md
+    gates:
+      - file_non_empty: answer.md
+`;
+const PERSONA_TEMPLATE = `You are a precise assistant. You answer requests concisely and
+concretely, and store the result as a file.
+`;
+const PROMPT_TEMPLATE = `Request: \${{ request }}
+
+Answer the request and write the answer to answer.md
+(Markdown, with a short heading).
+`;
+export async function runInit(cwd) {
+    const exists = async (p) => !!(await stat(p).catch(() => null));
+    const created = [];
+    const skipped = [];
+    const put = async (rel, content) => {
+        const abs = path.join(cwd, rel);
+        if (await exists(abs)) {
+            skipped.push(rel);
+            return;
+        }
+        await mkdir(path.dirname(abs), { recursive: true });
+        await writeFile(abs, content);
+        created.push(rel);
+    };
+    await put("kraftwerk.yml", CONFIG_TEMPLATE);
+    await put("workflows/hello/workflow.yml", WORKFLOW_TEMPLATE);
+    await put("workflows/hello/prompts/assistant.md", PERSONA_TEMPLATE);
+    await put("workflows/hello/prompts/answer.md", PROMPT_TEMPLATE);
+    // .gitignore: append output/ if it's not covered yet.
+    const gitignorePath = path.join(cwd, ".gitignore");
+    const gitignore = (await readFile(gitignorePath, "utf8").catch(() => null)) ?? null;
+    if (gitignore === null) {
+        await writeFile(gitignorePath, "output/\n");
+        created.push(".gitignore");
+    }
+    else if (!gitignore.split("\n").some((l) => l.trim().replace(/\/$/, "") === "output")) {
+        await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}output/\n`);
+        created.push(".gitignore (output/ added)");
+    }
+    else {
+        skipped.push(".gitignore");
+    }
+    for (const f of created)
+        console.log(`${chalk.green("✔")} ${f}`);
+    for (const f of skipped)
+        console.log(`${chalk.dim("• skipped (exists):")} ${chalk.dim(f)}`);
+    console.log(`\nNext steps:\n` +
+        `  kraftwerk list\n` +
+        `  kraftwerk run hello "What is kraftwerk?"\n` +
+        chalk.dim(`  (editor validation comes from the $schema line in workflow.yml)`));
+}

package/dist/cli/kraftwerk.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/kraftwerk.js

@@ -0,0 +1,342 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { input, select } from "@inquirer/prompts";
+import chalk from "chalk";
+import Table from "cli-table3";
+import { Command } from "commander";
+import ora from "ora";
+import { discoverWorkflows, findWorkflowsRoot } from "../discover.js";
+import { isRemoteSpec, resolveRemote } from "../remote.js";
+import { loadWorkflow, missingEnv } from "../yaml.js";
+import { renderCreateBrief } from "./create-brief.js";
+import { runDoctor } from "./doctor.js";
+import { runInit } from "./init.js";
+import { listRuns, showRun } from "./runs.js";
+/**
+ * kraftwerk — the kraftwerk CLI.
+ *
+ *   kraftwerk init                    scaffold kraftwerk.yml + workflows/ + example
+ *   kraftwerk list                    discover + list workflows (--json, --from)
+ *   kraftwerk run [workflow] [text]   run one (prompts interactively if omitted)
+ *   kraftwerk runs [show <id>]        inspect past runs from their traces
+ *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
+ *   kraftwerk validate [paths...]     validate without executing
+ *
+ * Workflows are auto-discovered under src/workflows/ (or workflows/), from
+ * any subdirectory (walk-up to kraftwerk.yml / workflows root / .git). No
+ * entry file, no registration, no local install needed — a repo with
+ * workflow folders plus `npx kraftwerk` is a complete consumer.
+ *
+ * Machine use (CI, cron, webhooks): `run --json` prints one JSON result on
+ * stdout and moves all narration to stderr; KRAFTWERK_YES=1 = --yes.
+ * Exit codes: 0 ok, 2 usage/config error, 3 run failed, 1 unexpected.
+ *
+ * `--from github:org/repo[@ref]` on list/run executes workflows straight
+ * from a git remote (shallow clone cache in ~/.cache/kraftwerk).
+ */
+/** Working directory for list/run: local cwd or the --from remote clone. */
+async function resolveBaseDir(from) {
+    if (!from)
+        return process.cwd();
+    if (!isRemoteSpec(from)) {
+        console.error(chalk.red(`--from "${from}" not recognized — expected github:org/repo[@ref] or a git URL.`));
+        process.exit(2);
+    }
+    return (await resolveRemote(from)).dir;
+}
+const pkg = JSON.parse(await readFile(new URL("../../package.json", import.meta.url), "utf8"));
+const program = new Command()
+    .name("kraftwerk")
+    .description("kraftwerk CLI: discover, validate, and run YAML workflows")
+    .version(pkg.version);
+const agentLabel = (workflow) => workflow.meta.agents
+    .map((a) => {
+    const harness = a.harness && a.harness !== "claude" ? `${a.harness}:` : "";
+    const effort = a.effort ? `, ${a.effort}` : "";
+    return `${a.id} ${chalk.dim(`(${harness}${a.model}${effort})`)}`;
+})
+    .join("\n");
+program
+    .command("list")
+    .description("Discover and list the workflows in the current project")
+    .option("--json", "Machine-readable output (JSON on stdout)")
+    .option("--from <source>", "Workflows from a git remote: github:org/repo[@ref] or git URL")
+    .action(async (opts) => {
+    const baseDir = await resolveBaseDir(opts.from);
+    const spinner = opts.json ? undefined : ora("Discovering workflows ...").start();
+    const found = await discoverWorkflows(baseDir);
+    spinner?.stop();
+    if (opts.json) {
+        console.log(JSON.stringify(found.map((e) => ({
+            path: e.path,
+            name: e.workflow?.name,
+            description: e.workflow?.description,
+            steps: e.workflow?.meta.steps,
+            requires: e.workflow?.meta.requires,
+            agents: e.workflow?.meta.agents.map((a) => ({
+                id: a.id,
+                model: a.model,
+                harness: a.harness ?? "claude",
+            })),
+            error: e.error,
+        })), null, 2));
+        return;
+    }
+    if (found.length === 0) {
+        console.log(chalk.yellow("No workflows found (expected: src/workflows/ or workflows/ — `kraftwerk init` scaffolds a project)."));
+        return;
+    }
+    const table = new Table({
+        head: ["workflow", "description", "steps", "agents"].map((h) => chalk.bold(h)),
+        wordWrap: true,
+        colWidths: [16, 40, 7, 36],
+    });
+    for (const entry of found) {
+        if (entry.workflow) {
+            const requires = entry.workflow.meta.requires;
+            table.push([
+                chalk.cyan(entry.workflow.name),
+                entry.workflow.description +
+                    (requires.length ? chalk.dim(`\nrequires: ${requires.join(", ")}`) : ""),
+                String(entry.workflow.meta.steps.length),
+                agentLabel(entry.workflow),
+            ]);
+        }
+        else {
+            table.push([
+                chalk.red(path.basename(entry.path)),
+                chalk.red(entry.error ?? "unknown error"),
+                "—",
+                "—",
+            ]);
+        }
+    }
+    console.log(table.toString());
+});
+program
+    .command("run")
+    .description("Run a workflow (prompts interactively for anything missing)")
+    .argument("[workflow]", "Workflow name from `kraftwerk list`")
+    .argument("[request...]", "The request: topic, URL, project idea, ...")
+    .option("--yes", "Auto-confirm approval gates (also: KRAFTWERK_YES=1)")
+    .option("--verbose", "Stream the agent narration")
+    .option("--json", "Non-interactive: JSON result on stdout, narration on stderr")
+    .option("--quiet", "Suppress narration (result/errors only)")
+    .option("--from <source>", "Workflows from a git remote: github:org/repo[@ref] or git URL")
+    .option("--sandbox", "Run inside the Docker sandbox container (image: kraftwerk-runner)")
+    .option("--ssh", "Forward the SSH agent + known_hosts into the sandbox (only with --sandbox)")
+    .option("--run-id <id>", "Pin the run folder name (output/<id>), e.g. for external triggers")
+    .action(async (name, requestParts, opts) => {
+    const machine = !!opts.json;
+    const fail = (code, message) => {
+        if (machine)
+            console.log(JSON.stringify({ ok: false, error: message }));
+        console.error(chalk.red(message));
+        process.exit(code);
+    };
+    const baseDir = await resolveBaseDir(opts.from);
+    const spinner = machine ? undefined : ora("Loading workflows ...").start();
+    const found = await discoverWorkflows(baseDir);
+    spinner?.stop();
+    const valid = found.filter((e) => e.workflow);
+    if (valid.length === 0)
+        fail(2, "No valid workflows found.");
+    let entry = name ? valid.find((e) => e.workflow.name === name) : undefined;
+    if (name && !entry) {
+        fail(2, `Workflow "${name}" not found. Available: ${valid.map((e) => e.workflow.name).join(", ")}`);
+    }
+    if (!entry && machine)
+        fail(2, "No workflow given (--json is non-interactive).");
+    entry ??= await select({
+        message: "Which workflow?",
+        choices: valid.map((e) => ({
+            name: `${e.workflow.name} — ${e.workflow.description}`,
+            value: e,
+        })),
+    });
+    const workflow = entry.workflow;
+    let request = (requestParts ?? []).join(" ").trim();
+    if (!request && machine)
+        fail(2, "No request given (--json is non-interactive).");
+    if (!request)
+        request = (await input({ message: "Request (topic, URL, ...):" })).trim();
+    if (!request)
+        fail(2, "No request given.");
+    const missing = missingEnv(workflow.meta.requires);
+    if (missing.length > 0) {
+        fail(2, `Workflow "${workflow.name}" needs environment variables that are missing: ${missing.join(", ")}`);
+    }
+    if (opts.sandbox) {
+        const { runSandboxed } = await import("../runner/docker.js");
+        const handle = await runSandboxed({
+            projectRoot: baseDir,
+            workflowPath: entry.path,
+            workflowName: workflow.name,
+            request,
+            runId: opts.runId,
+            ssh: !!opts.ssh,
+            mode: "attach",
+        });
+        console.log(chalk.dim(`sandbox ${handle.containerName} → ${handle.runDir}`));
+        process.exit(await handle.finished);
+    }
+    if (opts.runId) {
+        process.env.KRAFTWERK_RUN_DIR = path.resolve("output", opts.runId);
+    }
+    else if (!process.env.KRAFTWERK_RUN_DIR) {
+        // Root the run dir explicitly: at the project's output dir (honors
+        // kraftwerk.yml `output:` and works from subdirs); for remote runs at
+        // the caller's cwd — never inside the clone cache.
+        const { runStamp } = await import("../workflow.js");
+        const { resolveProject } = await import("../config.js");
+        const outBase = opts.from ? path.resolve("output") : (await resolveProject(baseDir)).outputDir;
+        process.env.KRAFTWERK_RUN_DIR = path.join(outBase, `run-${runStamp()}`);
+    }
+    // Machine/quiet mode: workflow narration must not pollute stdout — the
+    // engine logs via console.log, so reroute it for the duration of the run.
+    const realLog = console.log;
+    if (machine)
+        console.log = (...args) => console.error(...args);
+    else if (opts.quiet)
+        console.log = () => { };
+    const autoApprove = !!opts.yes || process.env.KRAFTWERK_YES === "1";
+    try {
+        const result = await workflow.run({ request, autoApprove, verbose: !!opts.verbose });
+        console.log = realLog;
+        if (machine) {
+            console.log(JSON.stringify({ ok: true, workflow: workflow.name, request, ...result }, null, 2));
+        }
+        else if (opts.quiet && result) {
+            console.log(`ok ${workflow.name} → ${result.runDir}`);
+        }
+    }
+    catch (err) {
+        console.log = realLog;
+        const message = err.message;
+        if (machine)
+            console.log(JSON.stringify({ ok: false, workflow: workflow.name, request, error: message }));
+        console.error(chalk.red(message));
+        process.exit(3);
+    }
+});
+program
+    .command("init")
+    .description("Scaffold the project: kraftwerk.yml, workflows/ with an example, .gitignore")
+    .action(async () => {
+    await runInit(process.cwd());
+});
+program
+    .command("doctor")
+    .description("Preflight: harness CLIs, docker, workflows, declared environment variables")
+    .action(async () => {
+    await runDoctor(process.cwd());
+});
+const runs = program
+    .command("runs")
+    .description("Inspect past runs (from output/*/trace.jsonl)");
+runs
+    .command("list", { isDefault: true })
+    .description("List runs (newest first)")
+    .option("--json", "Machine-readable output")
+    .action(async (opts) => {
+    await listRuns(process.cwd(), opts);
+});
+runs
+    .command("show")
+    .description("Show one run in detail: phases, gates, cost")
+    .argument("<runId>", "Folder name under output/, see `kraftwerk runs`")
+    .option("--json", "Machine-readable output (all trace events)")
+    .action(async (runId, opts) => {
+    await showRun(process.cwd(), runId, opts);
+});
+const runner = program
+    .command("runner")
+    .description("Manage the Docker sandbox runner (build the image, see/stop running runs)");
+runner
+    .command("build")
+    .description("Build/update the kraftwerk-runner image")
+    .action(async () => {
+    const { buildImage, dockerAvailable } = await import("../runner/docker.js");
+    if (!dockerAvailable()) {
+        console.error(chalk.red("Docker daemon not reachable — is Docker running?"));
+        process.exit(1);
+    }
+    await buildImage();
+    console.log(chalk.green("✔ Image kraftwerk-runner built"));
+});
+runner
+    .command("ps")
+    .description("List running sandbox runs")
+    .action(async () => {
+    const { listSandboxes } = await import("../runner/docker.js");
+    const rows = listSandboxes();
+    if (rows.length === 0) {
+        console.log(chalk.dim("No running sandbox runs."));
+        return;
+    }
+    for (const r of rows) {
+        console.log(`${chalk.cyan(r.runId)}  ${r.workflow}  ${chalk.dim(r.status)}`);
+    }
+});
+runner
+    .command("stop")
+    .description("Stop a running sandbox run")
+    .argument("<runId>", "Run-Id (run-...)")
+    .action(async (runId) => {
+    const { stopSandbox } = await import("../runner/docker.js");
+    if (stopSandbox(runId.replace(/^kw-/, ""))) {
+        console.log(chalk.green(`✔ ${runId} stopped`));
+    }
+    else {
+        console.error(chalk.red(`No running container for ${runId}.`));
+        process.exit(1);
+    }
+});
+// LLM-facing, veloop-style: prints a self-contained brief for the agent
+// that then authors the workflow folder with this CLI.
+program
+    .command("create")
+    .description("Print a brief for an LLM agent that builds a workflow from the description")
+    .argument("<spec...>", "What the workflow should do (free text)")
+    .action(async (specParts) => {
+    const spec = specParts.join(" ").trim();
+    if (!spec) {
+        console.error(chalk.red('Description missing. Example: kraftwerk create "A workflow that writes and reviews release notes"'));
+        process.exit(1);
+    }
+    const root = await findWorkflowsRoot(process.cwd());
+    console.log(renderCreateBrief({
+        spec,
+        workflowsRoot: root ? path.relative(process.cwd(), root) : undefined,
+    }));
+});
+program
+    .command("validate")
+    .description("Validate workflows without executing them (schema + semantics + files)")
+    .argument("[paths...]", "workflow.yml files or workflow folders; without paths: all discovered")
+    .action(async (paths) => {
+    let targets = paths;
+    if (targets.length === 0) {
+        const spinner = ora("Discovering workflows ...").start();
+        targets = (await discoverWorkflows(process.cwd())).map((e) => e.path);
+        spinner.stop();
+        if (targets.length === 0) {
+            console.log(chalk.yellow("No workflows found."));
+            return;
+        }
+    }
+    let failures = 0;
+    for (const target of targets) {
+        try {
+            const workflow = await loadWorkflow(target);
+            console.log(`${chalk.green("✔")} ${target} — ${chalk.cyan(workflow.name)} ` +
+                chalk.dim(`(${workflow.meta.steps.length} steps, ${workflow.meta.agents.length} agents)`));
+        }
+        catch (err) {
+            failures += 1;
+            console.error(`${chalk.red("✖")} ${target}\n${chalk.red(err.message)}`);
+        }
+    }
+    process.exit(failures > 0 ? 1 : 0);
+});
+await program.parseAsync(process.argv);

package/dist/cli/runs.d.ts

@@ -0,0 +1,6 @@
+export declare function listRuns(cwd: string, opts?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function showRun(cwd: string, id: string, opts?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/cli/runs.js

@@ -0,0 +1,120 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+import Table from "cli-table3";
+import { resolveProject } from "../config.js";
+import { fmtDuration, fmtTokens } from "../stats.js";
+async function readRun(dir) {
+    const tracePath = path.join(dir, "trace.jsonl");
+    const raw = await readFile(tracePath, "utf8").catch(() => null);
+    if (raw === null)
+        return undefined;
+    const events = raw
+        .split("\n")
+        .filter((l) => l.trim())
+        .flatMap((l) => {
+        try {
+            return [JSON.parse(l)];
+        }
+        catch {
+            return [];
+        }
+    });
+    const start = events.find((e) => e.event === "run_start");
+    const summary = events.find((e) => e.event === "run_summary");
+    const failed = events.some((e) => e.event === "phase_end" && (e.status === "failed" || e.status === "blocked"));
+    return {
+        id: path.basename(dir),
+        dir,
+        workflow: start?.workflow,
+        request: start?.request,
+        startedAt: start?.ts,
+        status: summary ? "ok" : failed ? "failed" : "incomplete",
+        durationMs: summary?.total?.durationMs,
+        costUsd: summary?.total?.costUsd,
+        events,
+    };
+}
+async function collectRuns(cwd) {
+    const { outputDir } = await resolveProject(cwd);
+    const entries = await readdir(outputDir, { withFileTypes: true }).catch(() => []);
+    const runs = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const info = await readRun(path.join(outputDir, entry.name));
+        if (info)
+            runs.push(info);
+    }
+    runs.sort((a, b) => (b.startedAt ?? b.id).localeCompare(a.startedAt ?? a.id));
+    return { outputDir, runs };
+}
+const STATUS_LABEL = {
+    ok: chalk.green("ok"),
+    failed: chalk.red("failed"),
+    incomplete: chalk.yellow("incomplete"),
+};
+export async function listRuns(cwd, opts = {}) {
+    const { outputDir, runs } = await collectRuns(cwd);
+    if (opts.json) {
+        console.log(JSON.stringify(runs.map(({ events: _events, ...rest }) => rest), null, 2));
+        return;
+    }
+    if (runs.length === 0) {
+        console.log(chalk.dim(`No runs under ${outputDir}.`));
+        return;
+    }
+    const table = new Table({
+        head: ["run", "workflow", "status", "duration", "cost", "request"].map((h) => chalk.bold(h)),
+        wordWrap: true,
+        colWidths: [26, 14, 12, 8, 9, 30],
+    });
+    for (const r of runs) {
+        table.push([
+            r.id,
+            r.workflow ?? "—",
+            STATUS_LABEL[r.status],
+            r.durationMs !== undefined ? fmtDuration(r.durationMs) : "—",
+            r.costUsd !== undefined ? `$${r.costUsd.toFixed(2)}` : "—",
+            r.request ?? "—",
+        ]);
+    }
+    console.log(table.toString());
+}
+export async function showRun(cwd, id, opts = {}) {
+    const { outputDir } = await resolveProject(cwd);
+    const dir = path.join(outputDir, id);
+    if (!(await stat(dir).catch(() => null))) {
+        console.error(chalk.red(`Run "${id}" not found under ${outputDir}.`));
+        process.exit(2);
+    }
+    const info = await readRun(dir);
+    if (!info) {
+        console.error(chalk.red(`${id}: no trace.jsonl — not a kraftwerk run?`));
+        process.exit(2);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(info, null, 2));
+        return;
+    }
+    console.log(`${chalk.cyan(info.workflow ?? "?")} ${STATUS_LABEL[info.status]}  ${chalk.dim(info.startedAt ?? "")}`);
+    if (info.request)
+        console.log(chalk.dim(`request: ${info.request}`));
+    console.log(chalk.dim(`dir: ${info.dir}\n`));
+    for (const e of info.events) {
+        if (e.event === "phase_end") {
+            const icon = e.status === "ok" ? chalk.green("✔") : chalk.red("✖");
+            const s = e.stats;
+            const detail = s
+                ? ` ${chalk.dim(`${fmtDuration(s.durationMs)} | ${fmtTokens(s.inputTokens + s.cacheReadTokens + s.cacheCreationTokens)} in / ${fmtTokens(s.outputTokens)} out | $${s.costUsd.toFixed(4)} | ${s.attempts} attempt(s)`)}`
+                : "";
+            console.log(`${icon} ${e.phase}${detail}`);
+        }
+        if (e.event === "gate_result" && e.passed === false) {
+            console.log(`  ${chalk.red("gate")} ${e.gate}: ${e.failure}`);
+        }
+    }
+    if (info.durationMs !== undefined) {
+        console.log(chalk.dim(`\ntotal: ${fmtDuration(info.durationMs)} | $${(info.costUsd ?? 0).toFixed(4)}`));
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+import type { WorkflowDefinition } from "./workflow.js";
+/**
+ * CLI registry dispatch: one entry point, one name per workflow. A consumer's
+ * whole entry file is one call:
+ *
+ *   runCli({ [contentWorkflow.name]: contentWorkflow });
+ *
+ *   npm start -- <workflow> "topic or source URL"
+ *   npm start -- <workflow> --yes "..."       # auto-approve
+ *   npm start -- <workflow> --verbose "..."   # + agent narration
+ *   npm start -- validate <path> ...          # validate YAML workflows
+ */
+export declare function runCli(workflows: Record<string, WorkflowDefinition>): void;

package/dist/cli.js

@@ -0,0 +1,47 @@
+import { validateWorkflows } from "./validate.js";
+/**
+ * CLI registry dispatch: one entry point, one name per workflow. A consumer's
+ * whole entry file is one call:
+ *
+ *   runCli({ [contentWorkflow.name]: contentWorkflow });
+ *
+ *   npm start -- <workflow> "topic or source URL"
+ *   npm start -- <workflow> --yes "..."       # auto-approve
+ *   npm start -- <workflow> --verbose "..."   # + agent narration
+ *   npm start -- validate <path> ...          # validate YAML workflows
+ */
+export function runCli(workflows) {
+    const usage = () => {
+        console.error('Usage: npm start -- <workflow> [--yes] [--verbose] "<topic or source URL>"');
+        console.error('       npm start -- validate <workflow.yml | workflow-folder> ...');
+        console.error("\nAvailable workflows:");
+        for (const wf of Object.values(workflows)) {
+            console.error(`  ${wf.name.padEnd(12)} ${wf.description}`);
+        }
+        process.exit(1);
+    };
+    const main = async () => {
+        const args = process.argv.slice(2);
+        const autoApprove = args.includes("--yes");
+        const verbose = args.includes("--verbose") || args.includes("-v");
+        const positional = args.filter((a) => !["--yes", "--verbose", "-v"].includes(a));
+        const [name, ...rest] = positional;
+        // Reserved subcommand: validate YAML workflows without executing them.
+        if (name === "validate") {
+            if (rest.length === 0)
+                usage();
+            process.exit((await validateWorkflows(rest)) > 0 ? 1 : 0);
+        }
+        const workflow = name ? workflows[name] : undefined;
+        if (!workflow)
+            usage();
+        const request = rest.join(" ").trim();
+        if (!request)
+            usage();
+        await workflow.run({ request, autoApprove, verbose });
+    };
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Project resolution + optional project config.
+ *
+ * `kraftwerk.yml` at the project root is both the config file and the
+ * root marker, so every CLI command works from any subdirectory. Without
+ * it, the walk-up falls back to the first ancestor containing a workflows
+ * root (src/workflows/ or workflows/), then to the first .git directory,
+ * then to the starting cwd.
+ *
+ * All fields are optional — a valid kraftwerk.yml may be empty:
+ *
+ *   workflows: src/workflows   # workflows root, relative to the file
+ *   output: output             # run-artifact directory, relative to the file
+ */
+/** Stable, versionless URL of the workflow JSON schema (editor validation). */
+export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
+export declare const CONFIG_FILENAMES: string[];
+export interface ProjectConfig {
+    /** Workflows root relative to the project root. */
+    workflows?: string;
+    /** Run-artifact directory relative to the project root. Default: output */
+    output?: string;
+}
+export interface Project {
+    /** Absolute project root the CLI operates on. */
+    root: string;
+    /** Parsed kraftwerk.yml, {} if none exists. */
+    config: ProjectConfig;
+    /** Absolute path of the config file, if one exists. */
+    configPath?: string;
+    /** Absolute workflows root, if one exists. */
+    workflowsRoot?: string;
+    /** Absolute run-artifact directory (may not exist yet). */
+    outputDir: string;
+}
+/**
+ * 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
+ * itself the last resort.
+ */
+export declare function resolveProject(cwd: string): Promise<Project>;