@nodetool-ai/cli 0.7.0-rc.23 → 0.8.2

package/dist/commands/costs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `nodetool costs` — inspect provider spend tracked in the local DB.
+ *
+ * Reads the local SQLite `predictions` table directly (in-process), so it works
+ * without a running server. Every provider call NodeTool makes is recorded as a
+ * Prediction — LLM calls with token counts, image/video/audio generation with
+ * the billing unit, quantity and unit price behind the charge.
+ *
+ * A call whose model is in no price catalog is still recorded, with a null
+ * cost. It shows up in `list` and is counted as `unpriced` in the aggregates,
+ * so an unknown price reads as unknown rather than as free.
+ */
+import type { Command } from "commander";
+export declare function registerCostsCommands(program: Command): void;
+//# sourceMappingURL=costs.d.ts.map

package/dist/commands/costs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"costs.d.ts","sourceRoot":"","sources":["../../src/commands/costs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiCzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8L5D"}

package/dist/commands/costs.js

@@ -0,0 +1,201 @@
+/**
+ * `nodetool costs` — inspect provider spend tracked in the local DB.
+ *
+ * Reads the local SQLite `predictions` table directly (in-process), so it works
+ * without a running server. Every provider call NodeTool makes is recorded as a
+ * Prediction — LLM calls with token counts, image/video/audio generation with
+ * the billing unit, quantity and unit price behind the charge.
+ *
+ * A call whose model is in no price catalog is still recorded, with a null
+ * cost. It shows up in `list` and is counted as `unpriced` in the aggregates,
+ * so an unknown price reads as unknown rather than as free.
+ */
+import { Prediction } from "@nodetool-ai/models";
+import { asJson, printTable, printKv } from "./output.js";
+import { setupLocalDb, LOCAL_USER_ID } from "./local-db.js";
+function fail(e) {
+    console.error(String(e instanceof Error ? e.message : e));
+    process.exit(1);
+}
+function usd(n) {
+    return `$${(n ?? 0).toFixed(4)}`;
+}
+/** A cost cell that tells an unpriced call apart from a genuinely free one. */
+function costCell(cost) {
+    return cost == null ? "unpriced" : usd(cost);
+}
+/** The units behind a unit-billed charge, e.g. "5 × seconds @ $0.2050". */
+function unitsCell(call) {
+    if (call.billing_unit == null && call.unit_price == null)
+        return "";
+    const quantity = call.quantity ?? 1;
+    const unit = call.billing_unit ?? "run";
+    const price = call.unit_price == null ? "" : ` @ ${usd(call.unit_price)}`;
+    return `${quantity} × ${unit}${price}`;
+}
+export function registerCostsCommands(program) {
+    const costs = program
+        .command("costs")
+        .description("Inspect tracked LLM/provider spend");
+    costs
+        .command("summary")
+        .description("Overall spend plus per-provider and per-model breakdowns")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        try {
+            await setupLocalDb();
+            const [byProvider, byModel] = await Promise.all([
+                Prediction.aggregateByProvider(LOCAL_USER_ID),
+                Prediction.aggregateByModel(LOCAL_USER_ID)
+            ]);
+            // Derive the overall totals by summing the provider aggregates rather
+            // than issuing a third full-table scan (aggregateByUser).
+            const overall = byProvider.reduce((acc, p) => ({
+                total_cost: acc.total_cost + p.total_cost,
+                total_input_tokens: acc.total_input_tokens + p.total_input_tokens,
+                total_output_tokens: acc.total_output_tokens + p.total_output_tokens,
+                total_tokens: acc.total_tokens + p.total_tokens,
+                call_count: acc.call_count + p.call_count,
+                unpriced_count: acc.unpriced_count + p.unpriced_count
+            }), {
+                total_cost: 0,
+                total_input_tokens: 0,
+                total_output_tokens: 0,
+                total_tokens: 0,
+                call_count: 0,
+                unpriced_count: 0
+            });
+            if (opts.json) {
+                asJson({ overall, by_provider: byProvider, by_model: byModel });
+                return;
+            }
+            console.log("\nOverall");
+            printKv({
+                total_cost: usd(overall.total_cost),
+                total_tokens: overall.total_tokens,
+                calls: overall.call_count,
+                unpriced_calls: overall.unpriced_count
+            });
+            if (overall.unpriced_count > 0) {
+                console.log(`\n${overall.unpriced_count} call(s) ran on a model no price ` +
+                    `catalog covers, so the total above is a lower bound. ` +
+                    `Run \`nodetool costs list\` to see them.`);
+            }
+            console.log("\nBy provider");
+            printTable(byProvider.map((p) => ({
+                provider: p.provider,
+                cost: usd(p.total_cost),
+                tokens: p.total_tokens,
+                calls: p.call_count,
+                unpriced: p.unpriced_count
+            })));
+            console.log("\nBy model");
+            printTable(byModel.map((m) => ({
+                provider: m.provider,
+                model: m.model,
+                cost: usd(m.total_cost),
+                tokens: m.total_tokens,
+                calls: m.call_count,
+                unpriced: m.unpriced_count
+            })));
+            console.log();
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    costs
+        .command("list")
+        .description("List recent provider calls with cost, tokens and billed units")
+        .option("--provider <name>", "Filter by provider")
+        .option("--model <id>", "Filter by model")
+        .option("--limit <n>", "Max results", "50")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        const limit = Number.parseInt(opts.limit, 10);
+        if (!Number.isFinite(limit) || limit <= 0) {
+            console.error(`Invalid --limit value: ${opts.limit}`);
+            process.exit(1);
+        }
+        try {
+            await setupLocalDb();
+            const page = { limit };
+            if (opts.provider) {
+                page.provider = opts.provider;
+            }
+            if (opts.model) {
+                page.model = opts.model;
+            }
+            const [calls] = await Prediction.paginate(LOCAL_USER_ID, page);
+            if (opts.json) {
+                asJson(calls);
+                return;
+            }
+            printTable(calls.map((c) => ({
+                created_at: c.created_at ?? "",
+                provider: c.provider,
+                model: c.model,
+                cost: costCell(c.cost),
+                in: c.input_tokens ?? "",
+                out: c.output_tokens ?? "",
+                units: unitsCell(c)
+            })));
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    costs
+        .command("by-provider")
+        .description("Aggregate spend grouped by provider")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        try {
+            await setupLocalDb();
+            const data = await Prediction.aggregateByProvider(LOCAL_USER_ID);
+            if (opts.json) {
+                asJson(data);
+                return;
+            }
+            printTable(data.map((p) => ({
+                provider: p.provider,
+                cost: usd(p.total_cost),
+                input_tokens: p.total_input_tokens,
+                output_tokens: p.total_output_tokens,
+                calls: p.call_count,
+                unpriced: p.unpriced_count
+            })));
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    costs
+        .command("by-model")
+        .description("Aggregate spend grouped by model")
+        .option("--provider <name>", "Filter by provider")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        try {
+            await setupLocalDb();
+            const data = await Prediction.aggregateByModel(LOCAL_USER_ID, opts.provider ? { provider: opts.provider } : {});
+            if (opts.json) {
+                asJson(data);
+                return;
+            }
+            printTable(data.map((m) => ({
+                provider: m.provider,
+                model: m.model,
+                cost: usd(m.total_cost),
+                input_tokens: m.total_input_tokens,
+                output_tokens: m.total_output_tokens,
+                calls: m.call_count,
+                unpriced: m.unpriced_count
+            })));
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+}
+//# sourceMappingURL=costs.js.map

package/dist/commands/costs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"costs.js","sourceRoot":"","sources":["../../src/commands/costs.ts"],"names":[],"mappings":"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"}

package/dist/commands/db.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function registerDbCommands(program: Command): void;
+//# sourceMappingURL=db.d.ts.map

package/dist/commands/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/commands/db.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0IzC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkIzD"}

package/dist/commands/db.js

@@ -0,0 +1,176 @@
+import { MigrationRunner, PostgresJsMigrationAdapter } from "@nodetool-ai/models";
+function resolveDatabaseUrl(opts) {
+    const url = opts.directUrl ??
+        opts.databaseUrl ??
+        process.env["DIRECT_URL"] ??
+        process.env["DATABASE_URL"];
+    if (!url) {
+        throw new Error("No PostgreSQL connection URL provided. Pass --direct-url/--database-url, " +
+            "or set DIRECT_URL or DATABASE_URL to your Supabase direct connection URL.");
+    }
+    return url;
+}
+function maskDatabaseUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.password) {
+            parsed.password = "***";
+        }
+        return parsed.toString();
+    }
+    catch {
+        return "(provided)";
+    }
+}
+async function withPostgresMigrationRunner(databaseUrl, fn) {
+    const { default: postgres } = await import("postgres");
+    const sql = postgres(databaseUrl, {
+        max: 1,
+        idle_timeout: 5,
+        connect_timeout: 30
+    });
+    const adapter = new PostgresJsMigrationAdapter(sql);
+    try {
+        return await fn(new MigrationRunner(adapter));
+    }
+    finally {
+        try {
+            await adapter.release();
+        }
+        finally {
+            await sql.end();
+        }
+    }
+}
+function printStatus(status, databaseUrl) {
+    console.log(`Database: ${maskDatabaseUrl(databaseUrl)}`);
+    console.log(`State: ${status.state}`);
+    console.log(`Current version: ${status.currentVersion ?? "(none)"}`);
+    console.log(`Applied migrations: ${status.applied.length}`);
+    console.log(`Pending migrations: ${status.pending.length}`);
+    if (status.pending.length > 0) {
+        console.log("\nPending:");
+        for (const migration of status.pending) {
+            console.log(`  ${migration.version}  ${migration.name}`);
+        }
+    }
+}
+function printMigrationList(versions, dryRun) {
+    if (versions.length === 0) {
+        console.log("No pending migrations.");
+        return;
+    }
+    console.log(dryRun
+        ? `Would apply ${versions.length} migration(s):`
+        : `Applied ${versions.length} migration(s):`);
+    for (const version of versions) {
+        console.log(`  ${version}`);
+    }
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function runCliAction(action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        console.error(getErrorMessage(error));
+        process.exit(1);
+    }
+}
+function addDatabaseUrlOptions(command) {
+    return command
+        .option("--direct-url <url>", "Supabase/PostgreSQL direct connection URL for migrations (preferred)")
+        .option("--database-url <url>", "Supabase/PostgreSQL connection URL (defaults to DIRECT_URL or DATABASE_URL)");
+}
+export function registerDbCommands(program) {
+    const db = program
+        .command("db")
+        .description("Database migration commands for PostgreSQL/Supabase");
+    addDatabaseUrlOptions(db
+        .command("status")
+        .description("Show PostgreSQL/Supabase migration status")
+        .option("--json", "Output as JSON")).action(async (opts) => {
+        await runCliAction(async () => {
+            const databaseUrl = resolveDatabaseUrl(opts);
+            const status = await withPostgresMigrationRunner(databaseUrl, (runner) => runner.status());
+            if (opts.json) {
+                console.log(JSON.stringify(status, null, 2));
+                return;
+            }
+            printStatus(status, databaseUrl);
+        });
+    });
+    addDatabaseUrlOptions(db
+        .command("migrate")
+        .description("Apply pending PostgreSQL/Supabase migrations")
+        .option("--target <version>", "Stop after applying this migration version")
+        .option("--dry-run", "Print pending migrations without applying them")
+        .option("--skip-checksums", "Skip checksum validation")
+        .option("--json", "Output as JSON")).action(async (opts) => {
+        await runCliAction(async () => {
+            const databaseUrl = resolveDatabaseUrl(opts);
+            const versions = await withPostgresMigrationRunner(databaseUrl, (runner) => {
+                const migrateOptions = {
+                    dryRun: opts.dryRun ?? false,
+                    validateChecksums: !(opts.skipChecksums ?? false)
+                };
+                if (opts.target) {
+                    migrateOptions.target = opts.target;
+                }
+                return runner.migrate(migrateOptions);
+            });
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    dryRun: opts.dryRun ?? false,
+                    migrations: versions
+                }, null, 2));
+                return;
+            }
+            printMigrationList(versions, opts.dryRun ?? false);
+        });
+    });
+    addDatabaseUrlOptions(db
+        .command("baseline")
+        .description("Mark existing PostgreSQL/Supabase tables as migrated")
+        .option("--force", "Clear and recreate migration tracking records")
+        .option("--json", "Output as JSON")).action(async (opts) => {
+        await runCliAction(async () => {
+            const databaseUrl = resolveDatabaseUrl(opts);
+            const baselined = await withPostgresMigrationRunner(databaseUrl, (runner) => runner.baseline(opts.force ?? false));
+            if (opts.json) {
+                console.log(JSON.stringify({ baselined }, null, 2));
+                return;
+            }
+            console.log(`Baselined ${baselined} migration(s).`);
+        });
+    });
+    addDatabaseUrlOptions(db
+        .command("rollback")
+        .description("Roll back PostgreSQL/Supabase migrations")
+        .option("--steps <n>", "Number of migrations to roll back", "1")
+        .option("--json", "Output as JSON")).action(async (opts) => {
+        await runCliAction(async () => {
+            const steps = Number.parseInt(opts.steps ?? "1", 10);
+            if (!Number.isInteger(steps) || steps < 1) {
+                throw new Error("--steps must be a positive integer");
+            }
+            const databaseUrl = resolveDatabaseUrl(opts);
+            const rolledBack = await withPostgresMigrationRunner(databaseUrl, (runner) => runner.rollback(steps));
+            if (opts.json) {
+                console.log(JSON.stringify({ rolledBack }, null, 2));
+                return;
+            }
+            if (rolledBack.length === 0) {
+                console.log("No migrations to roll back.");
+                return;
+            }
+            console.log(`Rolled back ${rolledBack.length} migration(s):`);
+            for (const version of rolledBack) {
+                console.log(`  ${version}`);
+            }
+        });
+    });
+}
+//# sourceMappingURL=db.js.map

package/dist/commands/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/commands/db.ts"],"names":[],"mappings":"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"}

package/dist/commands/debug-summary-output.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The console summary printed after a timeline, sketch or JS-script debug run.
+ * Only the document-specific line and the bundle's document file differ.
+ */
+interface DebugSummaryReport {
+    verdict: {
+        ok: boolean;
+        headline: string;
+        issues: string[];
+        warnings?: string[];
+    };
+    interactions: {
+        ok: boolean;
+    }[];
+}
+export declare function printDebugSummary(report: DebugSummaryReport, bundleDir: string, doc: {
+    label: string;
+    meta: string;
+    file: string;
+}): void;
+export {};
+//# sourceMappingURL=debug-summary-output.d.ts.map

package/dist/commands/debug-summary-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-summary-output.d.ts","sourceRoot":"","sources":["../../src/commands/debug-summary-output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,UAAU,kBAAkB;IAC1B,OAAO,EAAE;QACP,EAAE,EAAE,OAAO,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF,YAAY,EAAE;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CACjC;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD,IAAI,CAwBN"}

package/dist/commands/debug-summary-output.js

@@ -0,0 +1,28 @@
+/**
+ * The console summary printed after a timeline, sketch or JS-script debug run.
+ * Only the document-specific line and the bundle's document file differ.
+ */
+export function printDebugSummary(report, bundleDir, doc) {
+    const column = Math.max(doc.label.length, "session".length) + 1;
+    const row = (label, text) => `  ${`${label}:`.padEnd(column)} ${text}`;
+    const mark = report.verdict.ok ? "✅" : "❌";
+    console.log(`\n${mark} ${report.verdict.headline}`);
+    console.log(row(doc.label, doc.meta));
+    const failed = report.interactions.filter((i) => !i.ok).length;
+    if (report.interactions.length > 0) {
+        console.log(row("session", `${report.interactions.length} step(s), ${failed} failed`));
+    }
+    if (report.verdict.issues.length > 0) {
+        console.log("\nIssues:");
+        for (const issue of report.verdict.issues)
+            console.log(`  - ${issue}`);
+    }
+    if (report.verdict.warnings && report.verdict.warnings.length > 0) {
+        console.log("\nWarnings:");
+        for (const warning of report.verdict.warnings)
+            console.log(`  - ${warning}`);
+    }
+    console.log(`\nDebug bundle: ${bundleDir}`);
+    console.log(`  report.md / report.json · ${doc.file}`);
+}
+//# sourceMappingURL=debug-summary-output.js.map

package/dist/commands/debug-summary-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-summary-output.js","sourceRoot":"","sources":["../../src/commands/debug-summary-output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,MAAM,UAAU,iBAAiB,CAC/B,MAA0B,EAC1B,SAAiB,EACjB,GAAkD;IAElD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChE,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,IAAY,EAAU,EAAE,CAClD,KAAK,GAAG,KAAK,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACpD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC;IAC/D,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,OAAO,CAAC,GAAG,CACT,GAAG,CAAC,SAAS,EAAE,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,aAAa,MAAM,SAAS,CAAC,CAC1E,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACzB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM;YAAE,OAAO,CAAC,GAAG,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAC3B,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ;YAC3C,OAAO,CAAC,GAAG,CAAC,OAAO,OAAO,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,mBAAmB,SAAS,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,CAAC,+BAA+B,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;AACzD,CAAC"}

package/dist/commands/debug.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `nodetool debug` — the workflow debug harness command.
+ *
+ * Runs a workflow end-to-end on the headless server and (optionally) in a real
+ * browser, then writes a debug bundle (workflow JSON, every message/log/output/
+ * error, an OpenTelemetry trace summary, plus browser console errors and a
+ * screenshot) and prints an agent-friendly summary. Heavy dependencies are
+ * imported lazily inside the action so command registration stays light and
+ * unit-testable.
+ */
+import type { Command } from "commander";
+export declare function registerDebugCommands(program: Command): void;
+//# sourceMappingURL=debug.d.ts.map

package/dist/commands/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/commands/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2BzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4H5D"}

package/dist/commands/debug.js

@@ -0,0 +1,138 @@
+import { formatInterventionLine, formatSupervisedSummary, summarizeInterventions } from "@nodetool-ai/execution/debug";
+import { addSupervisorOptions, parseSupervisorFlags } from "../supervisor.js";
+import { numericOptionParser } from "../numeric-options.js";
+import { printCommandError } from "../command-errors.js";
+export function registerDebugCommands(program) {
+    addSupervisorOptions(program
+        .command("debug <workflow_id_or_file>")
+        .description("Run a workflow end-to-end (server and/or browser) and collect a full debug bundle")
+        .option("--no-server", "Skip the headless server surface")
+        .option("--browser", "Also run the workflow in a real browser (Playwright) — expensive")
+        .option("--trace", "Capture an OpenTelemetry trace of the server run (timing/tokens/cost) — expensive")
+        .option("--stages", "Capture a canvas screenshot at every browser run stage (implies --browser) — expensive")
+        .option("--params <json>", "JSON params string keyed by input-node name")
+        .option("--out <dir>", "Bundle output directory (default: nodetool-debug/<id>-<timestamp>)")
+        .option("--timeout <ms>", "Per-surface run timeout in milliseconds", numericOptionParser("--timeout", { integer: true, min: 0 }))
+        .option("--json", "Print the full DebugReport as JSON to stdout")
+        .option("--watch", "Re-run on file change and print a diff of the verdict (file targets only)")).action(async (ref, opts) => {
+        try {
+            const { initDb, Workflow } = await import("@nodetool-ai/models");
+            const { initMasterKey } = await import("@nodetool-ai/security");
+            const { getDefaultDbPath } = await import("@nodetool-ai/config");
+            const { runDebug, runWatchLoop, snapshotDebugReport } = await import("../debug/index.js");
+            initDb(getDefaultDbPath());
+            try {
+                await initMasterKey();
+            }
+            catch {
+                // Secret decryption is best-effort for debug runs; a missing master
+                // key only affects nodes that need secrets.
+            }
+            const params = opts.params
+                ? JSON.parse(opts.params)
+                : {};
+            const loadFromDb = (id) => Workflow.get(id);
+            // In watch mode keep a stable bundle dir so each re-run overwrites
+            // rather than littering timestamped directories.
+            const supervisor = parseSupervisorFlags(opts);
+            const runOptions = {
+                server: opts.server,
+                browser: opts.browser ?? false,
+                trace: opts.trace ?? false,
+                stages: opts.stages ?? false,
+                params
+            };
+            if (supervisor) {
+                runOptions.supervisor = supervisor;
+            }
+            if (opts.out) {
+                runOptions.outDir = opts.out;
+            }
+            else if (opts.watch) {
+                runOptions.outDir = `nodetool-debug/${watchSlug(ref)}-watch`;
+            }
+            if (opts.timeout) {
+                runOptions.timeoutMs = opts.timeout;
+            }
+            const runOnce = () => runDebug(ref, runOptions, {
+                loadFromDb,
+                onLog: (line) => console.error(line.trimEnd())
+            });
+            const report = await runOnce();
+            if (opts.json) {
+                console.log(JSON.stringify(report, null, 2));
+            }
+            else {
+                printSummary(report);
+            }
+            if (!opts.watch) {
+                process.exit(report.verdict.ok ? 0 : 1);
+            }
+            // ── Watch mode ────────────────────────────────────────────────────
+            const { existsSync } = await import("node:fs");
+            const { resolve } = await import("node:path");
+            const watchPath = resolve(ref);
+            if (!existsSync(watchPath)) {
+                console.error(`\n--watch needs a file target to watch; "${ref}" is not a file on disk.`);
+                process.exit(1);
+            }
+            await runWatchLoop({
+                file: watchPath,
+                first: report,
+                run: runOnce,
+                snapshot: snapshotDebugReport,
+                log: (line) => console.error(line)
+            });
+            process.exit(0);
+        }
+        catch (e) {
+            printCommandError(e, opts.json);
+            process.exit(1);
+        }
+    });
+}
+function watchSlug(ref) {
+    return (ref
+        .replace(/[^a-zA-Z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40) || "workflow");
+}
+function printSummary(report) {
+    const mark = report.verdict.ok ? "✅" : "❌";
+    console.log(`\n${mark} ${report.verdict.headline}`);
+    if (report.server) {
+        console.log(`  server:  ${report.server.status} (${report.server.summary.counts.errored} node error(s))`);
+        const interventions = report.server.summary.interventions;
+        if (report.server.supervised && interventions.length > 0) {
+            for (const intervention of interventions) {
+                console.log(`  ${formatInterventionLine(intervention)}`);
+            }
+            console.log(`  ${formatSupervisedSummary(summarizeInterventions(interventions))}`);
+        }
+    }
+    if (report.browser) {
+        console.log(report.browser.unavailableReason
+            ? `  browser: skipped — ${report.browser.unavailableReason}`
+            : `  browser: ${report.browser.status} (${report.browser.consoleErrors.length} console error(s))`);
+    }
+    if (report.verdict.issues.length > 0) {
+        console.log("\nIssues:");
+        for (const issue of report.verdict.issues)
+            console.log(`  - ${issue}`);
+    }
+    if (report.verdict.warnings && report.verdict.warnings.length > 0) {
+        console.log("\nWarnings:");
+        for (const warning of report.verdict.warnings)
+            console.log(`  - ${warning}`);
+    }
+    if (report.bundleDir) {
+        const parts = ["report.md / report.json", "workflow.json"];
+        if (report.server)
+            parts.push("server/");
+        if (report.browser && !report.browser.unavailableReason)
+            parts.push("browser/");
+        console.log(`\nDebug bundle: ${report.bundleDir}`);
+        console.log(`  ${parts.join(" · ")}`);
+    }
+}
+//# sourceMappingURL=debug.js.map