patchwork-os 0.2.0-alpha.0 → 0.2.0-alpha.11

package/dist/drivers/index.d.ts

@@ -0,0 +1,18 @@
+import type { ProviderDriver } from "./types.js";
+export type DriverMode = "subprocess" | "api" | "openai" | "grok" | "gemini" | "none";
+export interface DriverFactoryOpts {
+    binary: string;
+    antBinary: string;
+}
+/**
+ * Create the appropriate driver from a mode string.
+ * Returns null for "none" (orchestration disabled).
+ */
+export declare function createDriver(mode: DriverMode, opts: DriverFactoryOpts, log: (msg: string) => void): ProviderDriver | null;
+export { ApiDriver } from "./claude/api.js";
+export { SubprocessDriver } from "./claude/subprocess.js";
+export { GeminiSubprocessDriver } from "./gemini/index.js";
+export { GrokApiDriver } from "./grok/index.js";
+export { OpenAIApiDriver } from "./openai/index.js";
+export type { ProviderDriver, ProviderTaskInput, ProviderTaskOutcome, ProviderTaskResult, } from "./types.js";
+export { toProviderTaskOutcome } from "./types.js";

package/dist/drivers/index.js

@@ -0,0 +1,31 @@
+import { ApiDriver } from "./claude/api.js";
+import { SubprocessDriver } from "./claude/subprocess.js";
+import { GeminiSubprocessDriver } from "./gemini/index.js";
+import { GrokApiDriver } from "./grok/index.js";
+import { OpenAIApiDriver } from "./openai/index.js";
+/**
+ * Create the appropriate driver from a mode string.
+ * Returns null for "none" (orchestration disabled).
+ */
+export function createDriver(mode, opts, log) {
+    if (mode === "none")
+        return null;
+    if (mode === "subprocess")
+        return new SubprocessDriver(opts.binary, opts.antBinary, log);
+    if (mode === "api")
+        return new ApiDriver(log);
+    if (mode === "openai")
+        return new OpenAIApiDriver(log);
+    if (mode === "grok")
+        return new GrokApiDriver(log);
+    if (mode === "gemini")
+        return new GeminiSubprocessDriver(opts.binary === "claude" ? "gemini" : opts.binary, log);
+    throw new Error(`Unknown driver mode: ${mode}`);
+}
+export { ApiDriver } from "./claude/api.js";
+export { SubprocessDriver } from "./claude/subprocess.js";
+export { GeminiSubprocessDriver } from "./gemini/index.js";
+export { GrokApiDriver } from "./grok/index.js";
+export { OpenAIApiDriver } from "./openai/index.js";
+export { toProviderTaskOutcome } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/drivers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/drivers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAgBpD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAgB,EAChB,IAAuB,EACvB,GAA0B;IAE1B,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,IAAI,KAAK,YAAY;QACvB,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAChE,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;IACvD,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IACnD,IAAI,IAAI,KAAK,QAAQ;QACnB,OAAO,IAAI,sBAAsB,CAC/B,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EACjD,GAAG,CACJ,CAAC;IACJ,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAOpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/drivers/openai/index.d.ts

@@ -0,0 +1,24 @@
+import type { ProviderDriver, ProviderTaskInput, ProviderTaskResult } from "../types.js";
+export interface OpenAIDriverOpts {
+    /** Override API base URL — used by Grok and other OpenAI-compatible endpoints. */
+    baseURL?: string;
+    /** Default model when input.model is not set. */
+    defaultModel?: string;
+}
+/**
+ * OpenAI API driver — streams via chat.completions.create.
+ * Dynamic import: openai package is an optional peer dep (not in package.json).
+ * Install: npm install openai
+ *
+ * Limitation: single-turn only — no agentic tool-use loop.
+ * providerOptions: { maxTokens?: number, temperature?: number }
+ */
+export declare class OpenAIApiDriver implements ProviderDriver {
+    private readonly log;
+    private readonly opts;
+    readonly name: string;
+    constructor(log: (msg: string) => void, opts?: OpenAIDriverOpts);
+    run(input: ProviderTaskInput): Promise<ProviderTaskResult>;
+    /** Override in subclasses to use a different env var. */
+    protected apiKey(): string | undefined;
+}

package/dist/drivers/openai/index.js

@@ -0,0 +1,110 @@
+const OUTPUT_CAP = 50 * 1024;
+/**
+ * OpenAI API driver — streams via chat.completions.create.
+ * Dynamic import: openai package is an optional peer dep (not in package.json).
+ * Install: npm install openai
+ *
+ * Limitation: single-turn only — no agentic tool-use loop.
+ * providerOptions: { maxTokens?: number, temperature?: number }
+ */
+export class OpenAIApiDriver {
+    log;
+    opts;
+    name = "openai";
+    constructor(log, opts = {}) {
+        this.log = log;
+        this.opts = opts;
+        if (!process.env.OPENAI_API_KEY && !opts.baseURL) {
+            throw new Error("OpenAIApiDriver requires OPENAI_API_KEY environment variable");
+        }
+    }
+    async run(input) {
+        // biome-ignore lint/suspicious/noExplicitAny: dynamic import of optional peer dep
+        let OpenAICtor;
+        try {
+            // biome-ignore lint/suspicious/noExplicitAny: dynamic import
+            const mod = await import("openai");
+            // biome-ignore lint/suspicious/noExplicitAny: dynamic import
+            OpenAICtor = mod.default ?? mod.OpenAI ?? mod;
+        }
+        catch {
+            throw new Error("OpenAIApiDriver requires openai — install it with: npm install openai");
+        }
+        const opts = input.providerOptions ?? {};
+        const maxTokens = typeof opts.maxTokens === "number" ? opts.maxTokens : 4096;
+        const temperature = typeof opts.temperature === "number" ? opts.temperature : undefined;
+        const contextNote = input.contextFiles && input.contextFiles.length > 0
+            ? `\n\n--- BEGIN CONTEXT FILE LIST ---\n${input.contextFiles
+                .map((f) => f.slice(0, 500).replace(/[\x00-\x1f\x7f]/g, ""))
+                .join("\n")}\n--- END CONTEXT FILE LIST ---`
+            : "";
+        const messages = [];
+        if (input.systemPrompt) {
+            messages.push({ role: "system", content: input.systemPrompt });
+        }
+        messages.push({ role: "user", content: input.prompt + contextNote });
+        const clientOpts = {};
+        if (this.opts.baseURL)
+            clientOpts.baseURL = this.opts.baseURL;
+        // Use provider-specific API key env var if set, fall back to OPENAI_API_KEY
+        const apiKey = this.apiKey();
+        if (apiKey)
+            clientOpts.apiKey = apiKey;
+        const client = new OpenAICtor(clientOpts);
+        const start = Date.now();
+        const model = input.model ?? this.opts.defaultModel ?? "gpt-4o";
+        this.log(`[${this.name}] streaming: model=${model} workspace=${input.workspace}`);
+        let text = "";
+        let firstChunkAt;
+        try {
+            // biome-ignore lint/suspicious/noExplicitAny: dynamic import shape
+            const stream = await client.chat.completions.create({
+                model,
+                max_tokens: maxTokens,
+                ...(temperature !== undefined ? { temperature } : {}),
+                messages,
+                stream: true,
+            }, { signal: input.signal });
+            // biome-ignore lint/suspicious/noExplicitAny: stream shape from dynamic import
+            for await (const chunk of stream) {
+                const delta = chunk.choices?.[0]?.delta?.content ?? "";
+                if (delta) {
+                    if (firstChunkAt === undefined)
+                        firstChunkAt = Date.now();
+                    text += delta;
+                    if (text.length <= OUTPUT_CAP) {
+                        input.onChunk?.(delta);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            const isAbort = (err instanceof Error && err.name === "AbortError") ||
+                input.signal.aborted;
+            if (isAbort) {
+                return {
+                    text: text.slice(0, OUTPUT_CAP),
+                    durationMs: Date.now() - start,
+                    wasAborted: true,
+                    startupMs: firstChunkAt !== undefined ? firstChunkAt - start : undefined,
+                };
+            }
+            return {
+                text: text.slice(0, OUTPUT_CAP),
+                durationMs: Date.now() - start,
+                errorMessage: err instanceof Error ? err.message : String(err),
+            };
+        }
+        return {
+            text: text.slice(0, OUTPUT_CAP),
+            durationMs: Date.now() - start,
+            startupMs: firstChunkAt !== undefined ? firstChunkAt - start : undefined,
+            providerMeta: { model },
+        };
+    }
+    /** Override in subclasses to use a different env var. */
+    apiKey() {
+        return process.env.OPENAI_API_KEY;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/drivers/openai/index.js.map

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

package/dist/drivers/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Provider-neutral driver types.
+ * All drivers implement ProviderDriver; Claude-specific fields go in providerOptions.
+ */
+export interface ProviderTaskInput {
+    prompt: string;
+    /** Working directory / context hint passed as cwd to the subprocess or API call. */
+    workspace: string;
+    timeoutMs: number;
+    signal: AbortSignal;
+    onChunk?: (chunk: string) => void;
+    /** Informational list of paths; driver decides how to surface them. */
+    contextFiles?: string[];
+    /** Provider-specific model ID (e.g. "claude-sonnet-4-6", "gemini-2.5-pro"). */
+    model?: string;
+    systemPrompt?: string;
+    /** Startup timeout: abort if no output arrives within this many ms of spawn. */
+    startupTimeoutMs?: number;
+    /**
+     * Provider-specific overrides — driver may ignore unknown keys.
+     * Claude subprocess: { effort, fallbackModel, maxBudgetUsd, useAnt }
+     * Gemini subprocess: { binary }
+     * OpenAI API: { maxTokens, temperature }
+     */
+    providerOptions?: Record<string, unknown>;
+}
+export interface ProviderTaskResult {
+    text: string;
+    durationMs: number;
+    startupMs?: number;
+    wasAborted?: boolean;
+    /** Set when the provider signals an error (replaces exitCode for API drivers). */
+    errorMessage?: string;
+    /** Tokens used, resolved model, etc. Driver-specific. */
+    providerMeta?: Record<string, unknown>;
+    exitCode?: number;
+    stderrTail?: string;
+    startupTimedOut?: boolean;
+}
+export type ProviderTaskOutcome = {
+    outcome: "done";
+    text: string;
+    durationMs: number;
+    startupMs?: number;
+    providerMeta?: Record<string, unknown>;
+} | {
+    outcome: "error";
+    errorMessage: string;
+    durationMs: number;
+} | {
+    outcome: "aborted";
+    cancelKind: "startup_timeout" | "timeout" | "user";
+    durationMs: number;
+};
+export interface ProviderDriver {
+    readonly name: string;
+    /** Primary entry point. Must resolve; never reject (swallow errors into result). */
+    run(input: ProviderTaskInput): Promise<ProviderTaskResult>;
+    /** Optional: discriminated-union variant. Default impl wraps run(). */
+    runOutcome?(input: ProviderTaskInput): Promise<ProviderTaskOutcome>;
+    /** Optional: long-lived session lifecycle (server-mode drivers). */
+    spawnForSession?(sessionId: string): Promise<void>;
+    killForSession?(sessionId: string): void;
+    /** Called once on bridge shutdown. Clean up connections, temp files. */
+    destroy?(): Promise<void>;
+}
+export declare function toProviderTaskOutcome(result: ProviderTaskResult, cancelReason?: "timeout" | "startup_timeout" | "user" | "shutdown"): ProviderTaskOutcome;
+/**
+ * @deprecated Use ProviderDriver. IClaudeDriver is a backward-compat alias.
+ * Will be removed in a future minor version.
+ */
+export type IClaudeDriver = ProviderDriver;

package/dist/drivers/types.js

@@ -0,0 +1,30 @@
+/**
+ * Provider-neutral driver types.
+ * All drivers implement ProviderDriver; Claude-specific fields go in providerOptions.
+ */
+export function toProviderTaskOutcome(result, cancelReason) {
+    if (result.wasAborted) {
+        const cancelKind = result.startupTimedOut || cancelReason === "startup_timeout"
+            ? "startup_timeout"
+            : cancelReason === "timeout"
+                ? "timeout"
+                : "user";
+        return { outcome: "aborted", cancelKind, durationMs: result.durationMs };
+    }
+    if (result.errorMessage ||
+        (result.exitCode !== undefined && result.exitCode !== 0)) {
+        return {
+            outcome: "error",
+            errorMessage: result.errorMessage ?? `exit code ${result.exitCode}`,
+            durationMs: result.durationMs,
+        };
+    }
+    return {
+        outcome: "done",
+        text: result.text,
+        durationMs: result.durationMs,
+        startupMs: result.startupMs,
+        providerMeta: result.providerMeta,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/drivers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/drivers/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoEH,MAAM,UAAU,qBAAqB,CACnC,MAA0B,EAC1B,YAAkE;IAElE,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,MAAM,UAAU,GACd,MAAM,CAAC,eAAe,IAAI,YAAY,KAAK,iBAAiB;YAC1D,CAAC,CAAC,iBAAiB;YACnB,CAAC,CAAC,YAAY,KAAK,SAAS;gBAC1B,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,MAAM,CAAC;QACf,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;IAC3E,CAAC;IACD,IACE,MAAM,CAAC,YAAY;QACnB,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC,EACxD,CAAC;QACD,OAAO;YACL,OAAO,EAAE,OAAO;YAChB,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,aAAa,MAAM,CAAC,QAAQ,EAAE;YACnE,UAAU,EAAE,MAAM,CAAC,UAAU;SAC9B,CAAC;IACJ,CAAC;IACD,OAAO;QACL,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,YAAY,EAAE,MAAM,CAAC,YAAY;KAClC,CAAC;AACJ,CAAC"}

package/dist/index.js

@@ -1,4 +1,24 @@
 #!/usr/bin/env node
+// Load .env from repo root if present (connector credentials, etc.).
+// Uses Node 20.6+ native dotenv loader; falls back to manual parse for older Node.
+{
+    const { fileURLToPath: _fileURLToPath } = await import("node:url");
+    const envPath = _fileURLToPath(new URL("../.env", import.meta.url));
+    try {
+        const { readFileSync, existsSync } = await import("node:fs");
+        if (existsSync(envPath)) {
+            for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+                const m = /^([A-Z_][A-Z0-9_]*)=(.*)$/.exec(line.trim());
+                if (m?.[1] && !process.env[m[1]]) {
+                    process.env[m[1]] = m[2]?.replace(/^["']|["']$/g, "");
+                }
+            }
+        }
+    }
+    catch {
+        /* non-fatal */
+    }
+}
 // Enable V8 compile cache for faster cold-start on repeated restarts (Node 22.8+).
 import nodeModule from "node:module";
 if (typeof nodeModule.enableCompileCache === "function") {
@@ -547,39 +567,99 @@ export function register(ctx) {
     process.stderr.write(`  3. Or add to your config: { "plugins": ["${outDir}"] }\n`);
     process.exit(0);
 }
-// Patchwork: `patchwork recipe run <name>` — POSTs to a running bridge's
-// /recipes/run endpoint to enqueue the recipe via the Claude orchestrator.
+// Patchwork: `patchwork recipe list` — enumerate installed recipes.
+if (process.argv[2] === "recipe" && process.argv[3] === "list") {
+    (async () => {
+        const { listYamlRecipes } = await import("./recipes/yamlRunner.js");
+        const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
+        const recipes = listYamlRecipes(recipesDir);
+        if (recipes.length === 0) {
+            process.stdout.write("No recipes installed. Run `patchwork-os patchwork-init` to install the starter set.\n");
+        }
+        else {
+            process.stdout.write(`Installed recipes (${recipes.length}):\n\n`);
+            for (const r of recipes) {
+                const desc = r.description ? `  ${r.description}` : "";
+                process.stdout.write(`  ${r.name.padEnd(28)} [${r.trigger}]${desc}\n`);
+            }
+            process.stdout.write(`\nRun a recipe: patchwork-os recipe run <name>\n`);
+        }
+        process.exit(0);
+    })();
+}
+// Patchwork: `patchwork recipe run <name>` — runs a recipe locally or via
+// a running bridge's /recipes/run endpoint if one is available.
 if (process.argv[2] === "recipe" && process.argv[3] === "run") {
-    const name = process.argv[4];
+    const args = process.argv.slice(4);
+    const localFlag = args.includes("--local");
+    const name = args.find((a) => !a.startsWith("--"));
     if (!name) {
-        process.stderr.write("Usage: patchwork recipe run <name>\n");
+        process.stderr.write("Usage: patchwork recipe run <name> [--local]\n");
         process.exit(1);
     }
     (async () => {
         try {
+            // Try bridge first (requires --claude-driver subprocess).
             const { findBridgeLock } = await import("./bridgeLockDiscovery.js");
-            const lock = findBridgeLock();
-            if (!lock) {
-                process.stderr.write("Error: no running bridge found under ~/.claude/ide/. Start the bridge with --claude-driver subprocess first.\n");
-                process.exit(1);
-                return;
+            const lock = localFlag ? null : findBridgeLock();
+            if (lock) {
+                const res = await fetch(`http://127.0.0.1:${lock.port}/recipes/run`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${lock.authToken}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({ name }),
+                });
+                const body = (await res.json());
+                if (!body.ok) {
+                    // Fall through to local YAML runner if bridge doesn't know the recipe.
+                    if (!(body.error ?? "").includes("not found")) {
+                        process.stderr.write(`Error: ${body.error ?? "unknown"}\n`);
+                        process.exit(1);
+                        return;
+                    }
+                    // else: fall through to local runner below
+                }
+                else {
+                    process.stdout.write(`  ✓ enqueued recipe "${name}" as task ${(body.taskId ?? "").slice(0, 8)}\n` +
+                        "    Watch progress on the dashboard Tasks page or via listClaudeTasks.\n");
+                    process.exit(0);
+                    return;
+                }
             }
-            const res = await fetch(`http://127.0.0.1:${lock.port}/recipes/run`, {
-                method: "POST",
-                headers: {
-                    Authorization: `Bearer ${lock.authToken}`,
-                    "Content-Type": "application/json",
-                },
-                body: JSON.stringify({ name }),
-            });
-            const body = (await res.json());
-            if (!body.ok) {
-                process.stderr.write(`Error: ${body.error ?? "unknown"}\n`);
+            // No bridge — run locally using the YAML runner.
+            const { loadYamlRecipe, runYamlRecipe } = await import("./recipes/yamlRunner.js");
+            const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
+            const bundledDir = fileURLToPath(new URL("../templates/recipes", import.meta.url));
+            const candidates = [
+                path.join(recipesDir, `${name}.yaml`),
+                path.join(recipesDir, `${name}.yml`),
+                path.join(recipesDir, `${name}.json`),
+                path.join(bundledDir, `${name}.yaml`),
+                path.join(bundledDir, `${name}.yml`),
+            ];
+            let recipePath;
+            for (const c of candidates) {
+                if (existsSync(c)) {
+                    recipePath = c;
+                    break;
+                }
+            }
+            if (!recipePath) {
+                process.stderr.write(`Error: recipe "${name}" not found in ${recipesDir}\n` +
+                    "  Run `patchwork-os recipe list` to see available recipes.\n");
                 process.exit(1);
                 return;
             }
-            process.stdout.write(`  ✓ enqueued recipe "${name}" as task ${(body.taskId ?? "").slice(0, 8)}\n` +
-                "    Watch progress on the dashboard Tasks page or via listClaudeTasks.\n");
+            process.stdout.write(`  Running recipe "${name}" locally…\n`);
+            const recipe = loadYamlRecipe(recipePath);
+            const workdir = lock?.workspace || process.cwd();
+            const result = await runYamlRecipe(recipe, { workdir });
+            process.stdout.write(`  ✓ ${result.stepsRun} step(s) completed\n`);
+            if (result.outputs.length > 0) {
+                process.stdout.write(`  Output written to:\n${result.outputs.map((o) => `    ${o}`).join("\n")}\n`);
+            }
             process.exit(0);
         }
         catch (err) {
@@ -1304,6 +1384,19 @@ Options:
     process.exit(0);
 }
 // F6: "Did you mean?" for unknown CLI subcommands
+// Patchwork: no-args → terminal dashboard (when invoked as patchwork-os or patchwork).
+{
+    const binName = path.basename(process.argv[1] ?? "");
+    const isPatchworkBin = binName === "patchwork-os" ||
+        binName === "patchwork" ||
+        binName === "patchwork.js";
+    if (isPatchworkBin && !process.argv[2]) {
+        (async () => {
+            const { runDashboard } = await import("./commands/dashboard.js");
+            await runDashboard();
+        })();
+    }
+}
 {
     const KNOWN_COMMANDS = [
         "init",
@@ -1319,6 +1412,7 @@ Options:
         "status",
         "shim",
         "recipe",
+        "dashboard",
     ];
     const unknownSub = process.argv[2];
     if (unknownSub &&