@smithers-orchestrator/cli 0.20.0 → 0.20.3

package/src/index.js

@@ -259,6 +259,36 @@ function parseJsonInput(raw, label, fail) {
         });
     }
 }
+/**
+ * @param {string | undefined} raw
+ * @param {FailFn} fail
+ * @returns {Record<string, string | number | boolean> | undefined}
+ */
+function parseAnnotations(raw, fail) {
+    const parsed = parseJsonInput(raw, "annotations", fail);
+    if (parsed === undefined)
+        return undefined;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return fail({
+            code: "INVALID_ANNOTATIONS",
+            message: "Run annotations must be a flat JSON object of string/number/boolean values",
+            exitCode: 4,
+        });
+    }
+    /** @type {Record<string, string | number | boolean>} */
+    const annotations = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (!["string", "number", "boolean"].includes(typeof value)) {
+            return fail({
+                code: "INVALID_ANNOTATIONS",
+                message: `Run annotation ${key} must be a string, number, or boolean`,
+                exitCode: 4,
+            });
+        }
+        annotations[key] = /** @type {string | number | boolean} */ (value);
+    }
+    return annotations;
+}
 /**
  * @param {string | undefined} status
  */
@@ -454,6 +484,41 @@ function isRunStatusTerminal(status) {
         status !== "waiting-timer" &&
         status !== "waiting-event");
 }
+/**
+ * Fetch a docs file from smithers.sh and write it to stdout.
+ * Honors --json (global) by emitting `{ url, content }`.
+ *
+ * @param {{ error: Function; ok: Function; format?: string; options?: { json?: boolean } }} c
+ * @param {string} url
+ * @param {string} errorCode
+ */
+async function printSmithersDocs(c, url, errorCode) {
+    let body;
+    try {
+        const res = await fetch(url);
+        if (!res.ok) {
+            return c.error({
+                code: errorCode,
+                message: `Failed to fetch ${url}: HTTP ${res.status}`,
+                exitCode: 1,
+            });
+        }
+        body = await res.text();
+    }
+    catch (err) {
+        return c.error({
+            code: errorCode,
+            message: `Failed to fetch ${url}: ${err?.message ?? String(err)}`,
+            exitCode: 1,
+        });
+    }
+    const wantsJson = Boolean(c.options?.json) || c.format === "json";
+    if (wantsJson) {
+        return c.ok({ url, content: body });
+    }
+    process.stdout.write(body.endsWith("\n") ? body : `${body}\n`);
+    return c.ok(undefined);
+}
 /**
  * @param {string | undefined} format
  * @param {unknown} payload
@@ -1225,6 +1290,7 @@ const upOptions = z.object({
     toolTimeoutMs: z.number().int().min(1).optional().describe("Max wall-clock time per tool call in ms"),
     hot: z.boolean().default(false).describe("Enable hot module replacement for .tsx workflows"),
     input: z.string().optional().describe("Input data as JSON string"),
+    annotations: z.string().optional().describe("Run annotations as a flat JSON object of string/number/boolean values"),
     resume: z.union([z.boolean(), z.string()]).default(false).describe("Resume a previous run. Pass true with --run-id, or pass the run ID directly (e.g. --resume <run-id>)"),
     force: z.boolean().default(false).describe("Resume even if still marked running"),
     resumeClaimOwner: z.string().optional().describe("Internal durable resume claim owner"),
@@ -1450,6 +1516,7 @@ async function executeUpCommand(c, workflowPath, options, fail) {
     try {
         const resolvedWorkflowPath = resolve(process.cwd(), workflowPath);
         const input = parseJsonInput(options.input, "input", fail) ?? {};
+        const annotations = parseAnnotations(options.annotations, fail);
         const { resume, resumeRunId } = normalizeResumeOption(options.resume);
         const runId = options.runId ?? resumeRunId;
         // Detached mode: spawn ourselves as a background process
@@ -1460,6 +1527,8 @@ async function executeUpCommand(c, workflowPath, options, fail) {
                 childArgs.push("--run-id", runId);
             if (options.input)
                 childArgs.push("--input", options.input);
+            if (options.annotations)
+                childArgs.push("--annotations", options.annotations);
             if (options.maxConcurrency)
                 childArgs.push("--max-concurrency", String(options.maxConcurrency));
             if (options.root)
@@ -1647,6 +1716,7 @@ async function executeUpCommand(c, workflowPath, options, fail) {
                 maxOutputBytes: options.maxOutputBytes,
                 toolTimeoutMs: options.toolTimeoutMs,
                 hot: options.hot,
+                annotations,
                 onProgress,
                 signal: abort.signal,
             }));
@@ -1699,6 +1769,7 @@ async function executeUpCommand(c, workflowPath, options, fail) {
             maxOutputBytes: options.maxOutputBytes,
             toolTimeoutMs: options.toolTimeoutMs,
             hot: options.hot,
+            annotations,
             onProgress,
             signal: abort.signal,
         }));
@@ -1819,7 +1890,7 @@ const workflowCli = Cli.create({
                 path: resolve(workflowRoot, "bunfig.toml"),
                 exists: existsSync(resolve(workflowRoot, "bunfig.toml")),
             },
-            agents: detectAvailableAgents(),
+            agents: detectAvailableAgents(process.env, { cwd: process.cwd() }),
         });
     },
 });
@@ -2515,8 +2586,8 @@ const cli = Cli.create({
                                 { command: "workflow run implement", description: "Run the implementation workflow" },
                             ]
                             : [
-                                { command: "tui", description: "Open the interactive dashboard" },
                                 { command: "workflow list", description: "View all available workflows" },
+                                { command: "workflow run implement", description: "Run the implementation workflow" },
                             ],
                     },
                 });
@@ -2605,49 +2676,6 @@ const cli = Cli.create({
             cleanup();
         }
     },
-})
-    // =========================================================================
-    // smithers tui
-    // =========================================================================
-    .command("tui", {
-    description: "Open the interactive Smithers observability dashboard",
-    async run(c) {
-        const fail = (opts) => {
-            commandExitOverride = opts.exitCode ?? 1;
-            return c.error(opts);
-        };
-        let cleanup;
-        let renderer;
-        try {
-            const db = await findAndOpenDb(undefined, {
-                timeoutMs: 5000,
-                intervalMs: 100,
-            });
-            const adapter = db.adapter;
-            cleanup = db.cleanup;
-            const { createCliRenderer } = await import("@opentui/core");
-            const { createRoot } = await import("@opentui/react");
-            const { TuiApp } = await import("./tui/app.jsx");
-            const React = await import("react");
-            renderer = await createCliRenderer({ exitOnCtrlC: false });
-            const root = createRoot(renderer);
-            await new Promise((resolve) => {
-                root.render(React.createElement(TuiApp, {
-                    adapter,
-                    onExit: () => resolve(true),
-                }));
-            });
-            return c.ok(undefined);
-        }
-        catch (err) {
-            return fail({ code: "TUI_FAILED", message: err?.message ?? String(err), exitCode: 1 });
-        }
-        finally {
-            if (renderer)
-                renderer.destroy();
-            cleanup?.();
-        }
-    }
 })
     // =========================================================================
     // smithers ps
@@ -4930,6 +4958,22 @@ const cli = Cli.create({
             return c.error({ code: "GUI_LAUNCH_FAILED", message: err?.message ?? String(err), exitCode: 1 });
         }
     },
+})
+    // =========================================================================
+    // smithers docs / smithers docs-full
+    // Print the published llms.txt / llms-full.txt from smithers.sh.
+    // =========================================================================
+    .command("docs", {
+    description: "Print llms.txt (concise docs index for LLMs) from smithers.sh.",
+    async run(c) {
+        return printSmithersDocs(c, "https://smithers.sh/llms.txt", "DOCS_FETCH_FAILED");
+    },
+})
+    .command("docs-full", {
+    description: "Print llms-full.txt (full docs bundle for LLMs) from smithers.sh.",
+    async run(c) {
+        return printSmithersDocs(c, "https://smithers.sh/llms-full.txt", "DOCS_FULL_FETCH_FAILED");
+    },
 })
     .command(workflowCli)
     .command(cronCli)

package/src/workflow-pack.js

@@ -133,7 +133,6 @@ function renderPackageJson(versions) {
         dependencies: {
             react: versions.reactVersion,
             "react-dom": versions.reactDomVersion,
-            skills: "github:mattpocock/skills",
             "smithers-orchestrator": smithersSpec,
             zod: versions.zodVersion,
         },
@@ -413,6 +412,17 @@ function renderPrompts() {
                 "",
             ].join("\n"),
         },
+        {
+            path: ".smithers/prompts/grill-me.mdx",
+            contents: [
+                "Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.",
+                "",
+                "Ask the questions one at a time.",
+                "",
+                "If a question can be answered by exploring the codebase, explore the codebase instead.",
+                "",
+            ].join("\n"),
+        },
         {
             path: ".smithers/prompts/write-a-prd.mdx",
             contents: [
@@ -1185,7 +1195,7 @@ function renderComponents() {
                 "/** @jsxImportSource smithers-orchestrator */",
                 'import { Loop, Sequence, Task, type AgentLike, type OutputTarget } from "smithers-orchestrator";',
                 'import { z } from "zod/v4";',
-                'import GrillMeSkill from "skills/grill-me/SKILL.md";',
+                'import GrillMeSkill from "../prompts/grill-me.mdx";',
                 'import AskUserInstructions from "../prompts/ask-user-instructions.mdx";',
                 "",
                 "export const grillOutputSchema = z.looseObject({",
@@ -3261,13 +3271,42 @@ function renderWorkflows() {
 /**
  * @param {DependencyVersions} versions
  * @param {NodeJS.ProcessEnv} env
+ * @param {string} projectRoot
  * @returns {TemplateFile[]}
  */
-function renderTemplateFiles(versions, env) {
+function renderTemplateFiles(versions, env, projectRoot) {
     return [
         {
             path: ".smithers/.gitignore",
-            contents: ["node_modules/", "executions/", "runs/", "sandboxes/", "state/", "tmp/", "*.db", "*.sqlite", "dist/", ".DS_Store", ""].join("\n"),
+            contents: [
+                "# Ephemeral data (never commit)",
+                "node_modules/",
+                "executions/",
+                "runs/",
+                "sandboxes/",
+                "state/",
+                "tmp/",
+                "*.db",
+                "*.sqlite",
+                "*.db-shm",
+                "*.db-wal",
+                "dist/",
+                ".DS_Store",
+                "",
+                "# Log files",
+                "*.log",
+                "logs/",
+                ""
+            ].join("\n"),
+        },
+        {
+            path: ".smithers/workflows/.gitignore",
+            contents: [
+                "# Ignore log files in workflows",
+                "*.log",
+                "run-*.log",
+                ""
+            ].join("\n"),
         },
         {
             path: ".smithers/package.json",
@@ -3304,7 +3343,7 @@ function renderTemplateFiles(versions, env) {
         ...renderAgentScaffoldFiles(),
         {
             path: ".smithers/agents.ts",
-            contents: generateAgentsTs(env),
+            contents: generateAgentsTs(env, { cwd: projectRoot }),
         },
         {
             path: ".smithers/smithers.config.ts",
@@ -3361,7 +3400,7 @@ export function initWorkflowPack(options = {}) {
         else {
             ensureDir(executionsDir);
         }
-        templateFiles = renderTemplateFiles(versions, env);
+        templateFiles = renderTemplateFiles(versions, env, projectRoot);
     }
     for (const file of templateFiles) {
         const absolutePath = resolve(projectRoot, file.path);
@@ -3388,10 +3427,9 @@ export function initWorkflowPack(options = {}) {
     };
 }
 /**
- * Install `.smithers/` workspace deps so git-specifier packages like
- * `github:mattpocock/skills` — which Bun's runtime auto-install doesn't fetch —
- * are available the first time a workflow runs. Failures here don't fail init:
- * the scaffold is on disk, the user can always re-run `bun install` by hand.
+ * Install `.smithers/` workspace deps so the first workflow run isn't blocked
+ * on a cold install. Failures here don't fail init: the scaffold is on disk,
+ * the user can always re-run `bun install` by hand.
  *
  * @param {string} rootDir
  * @param {boolean} skip

package/src/tui/app.jsx

@@ -1,139 +0,0 @@
-// @ts-nocheck
-import React, { useEffect, useState } from "react";
-import { useKeyboard } from "@opentui/react";
-import { RunsList } from "./components/RunsList.jsx";
-import { WorkflowLauncher } from "./components/WorkflowLauncher.jsx";
-import { RunDetailView } from "./components/RunDetailView.jsx";
-import { NodeDetailView } from "./components/NodeDetailView.jsx";
-import { AskModal } from "./components/AskModal.jsx";
-import { SqliteBrowser } from "./components/SqliteBrowser.jsx";
-import { CronList } from "./components/CronList.jsx";
-import { MetricsPane } from "./components/MetricsPane.jsx";
-/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} SmithersDb */
-
-const TABS = [
-    { id: "runs", label: "Runs", access: "r" },
-    { id: "ask", label: "Agent Console", access: "a" },
-    { id: "crons", label: "Triggers", access: "t" },
-    { id: "metrics", label: "Telemetry", access: "m" },
-    { id: "sqlite", label: "Data Grid", access: "s" },
-];
-/**
- * @param {{ adapter: SmithersDb; onExit: () => void; }} value
- */
-export function TuiApp({ adapter, onExit, }) {
-    const [view, setView] = useState("runs");
-    const [selectedRunId, setSelectedRunId] = useState(null);
-    const [selectedNodeId, setSelectedNodeId] = useState(null);
-    const activeTabId = (view === "detail" || view === "node" || view === "launcher") ? "runs" : view;
-    useKeyboard(async (key) => {
-        // Tab switching
-        if (key.name === "left" || key.name === "right") {
-            // only accept left/right at the root view so we don't clobber text inputs
-            if (view === "runs" || view === "crons" || view === "metrics") {
-                const currentIndex = TABS.findIndex((t) => t.id === activeTabId);
-                if (key.name === "right") {
-                    const next = TABS[(currentIndex + 1) % TABS.length];
-                    setView(next.id);
-                }
-                else {
-                    const prev = TABS[(currentIndex - 1 + TABS.length) % TABS.length];
-                    setView(prev.id);
-                }
-                return;
-            }
-        }
-        if (key.name === "s" && view !== "sqlite" && view !== "ask") {
-            setView("sqlite");
-            return;
-        }
-        if (key.name === "t" && view !== "crons" && view !== "ask") {
-            setView("crons");
-            return;
-        }
-        if (key.name === "m" && view !== "metrics" && view !== "ask") {
-            setView("metrics");
-            return;
-        }
-        if (view === "runs") {
-            if (key.name === "escape" || (key.name === "c" && key.ctrl)) {
-                onExit();
-            }
-            if (key.name === "n") {
-                setView("launcher");
-            }
-            if (key.name === "a") {
-                setView("ask");
-            }
-        }
-        else if (view === "detail") {
-            if (key.name === "escape") {
-                setView("runs");
-            }
-            else if (key.name === "c" && key.ctrl) {
-                onExit();
-            }
-        }
-        else if (view === "node") {
-            if (key.name === "escape") {
-                setView("detail");
-            }
-            else if (key.name === "c" && key.ctrl) {
-                onExit();
-            }
-        }
-        else if (view === "launcher") {
-            if (key.name === "escape") {
-                setView("runs");
-            }
-            else if (key.name === "c" && key.ctrl) {
-                onExit();
-            }
-        }
-        else if (view === "ask") {
-            if (key.name === "escape") {
-                setView("runs");
-            }
-            else if (key.name === "c" && key.ctrl) {
-                onExit();
-            }
-        }
-    });
-    return (<box style={{ flexGrow: 1, width: "100%", height: "100%", flexDirection: "column" }}>
-      {/* Global Tab Header */}
-      <box style={{ width: "100%", height: 3, borderBottom: true, borderColor: "gray", flexDirection: "row", paddingLeft: 1 }}>
-        {TABS.map((tab) => {
-            const isActive = activeTabId === tab.id;
-            return (<text key={tab.id} style={{ color: isActive ? "#a7f3d0" : "gray", marginRight: 3 }}>
-              {isActive ? "▶ " : "  "}[{tab.access.toUpperCase()}] {tab.label}
-            </text>);
-        })}
-      </box>
-
-      {view === "runs" && (<box style={{ flexGrow: 1, width: "100%", height: "100%", border: true, borderColor: "#34d399", flexDirection: "column" }} title="Smithers Runs - [Enter] View Details | [N] New Run | [Esc] Exit">
-          <RunsList adapter={adapter} focused={view === "runs"} onChange={setSelectedRunId} onSubmit={(runId) => {
-                setSelectedRunId(runId);
-                setView("detail");
-            }}/>
-        </box>)}
-
-      {view === "detail" && selectedRunId && (<RunDetailView adapter={adapter} runId={selectedRunId} onBack={() => setView("runs")} onSelectNode={(nodeId) => {
-                setSelectedNodeId(nodeId);
-                setView("node");
-            }}/>)}
-
-      {view === "node" && selectedRunId && (<NodeDetailView adapter={adapter} runId={selectedRunId} nodeId={selectedNodeId} onBack={() => setView("detail")}/>)}
-
-      {view === "launcher" && (<WorkflowLauncher onClose={() => setView("runs")}/>)}
-      {view === "ask" && (<AskModal onClose={() => setView("runs")}/>)}
-      {view === "sqlite" && (<box style={{ flexGrow: 1, width: "100%", height: "100%", border: true, borderColor: "#34d399", flexDirection: "column" }} title="Smithers DB - [Esc] Return to Runs | [Tab] Switch Panes | [Up/Down] Query Table">
-          <SqliteBrowser adapter={adapter} onBack={() => setView("runs")}/>
-        </box>)}
-      {view === "crons" && (<box style={{ flexGrow: 1, width: "100%", height: "100%", border: true, borderColor: "#34d399", flexDirection: "column" }} title="Smithers Schedule Triggers - [Esc] Return to Runs | [Up/Down] Select | [Del] Remove">
-          <CronList adapter={adapter} onBack={() => setView("runs")}/>
-        </box>)}
-      {view === "metrics" && (<box style={{ flexGrow: 1, width: "100%", height: "100%", border: true, borderColor: "#34d399", flexDirection: "column" }} title="Smithers Telemetry (Prometheus Rollup) - [Esc] Return to Runs">
-          <MetricsPane adapter={adapter} onBack={() => setView("runs")}/>
-        </box>)}
-    </box>);
-}

package/src/tui/app.tsx

@@ -1,5 +0,0 @@
-import type { SmithersDb } from "@smithers-orchestrator/db/adapter";
-export declare function TuiApp({ adapter, onExit, }: {
-    adapter: SmithersDb;
-    onExit: () => void;
-}): import("react/jsx-runtime").JSX.Element;

package/src/tui/components/AskModal.jsx

@@ -1,109 +0,0 @@
-// @ts-nocheck
-import React, { useState, useEffect } from "react";
-import { useKeyboard } from "@opentui/react";
-/**
- * @param {{ onClose: () => void }} value
- */
-export function AskModal({ onClose }) {
-    const [question, setQuestion] = useState("");
-    const [answer, setAnswer] = useState("");
-    const [status, setStatus] = useState("input");
-    useKeyboard((key) => {
-        if (key.name === "escape" || (key.name === "c" && key.ctrl)) {
-            if (status !== "streaming") { // Or allow cancel mid-stream if we kill the proc? Keep simple for now
-                onClose();
-                return;
-            }
-        }
-        if (status === "input") {
-            if (key.name === "backspace") {
-                setQuestion((q) => q.slice(0, -1));
-                return;
-            }
-            if (key.name === "enter" || key.name === "return") {
-                if (question.trim().length > 0) {
-                    startAsk();
-                }
-                return;
-            }
-            // Basic typing capture (sequence is the literal ansi char)
-            if (!key.ctrl && !key.meta && key.sequence && key.sequence.length === 1 && key.name !== "up" && key.name !== "down" && key.name !== "left" && key.name !== "right") {
-                setQuestion((q) => q + key.sequence);
-            }
-        }
-    });
-    async function startAsk() {
-        setStatus("streaming");
-        setAnswer("");
-        try {
-            const proc = Bun.spawn(["bun", "run", "src/index.js", "ask", question], {
-                stdout: "pipe",
-                stderr: "pipe",
-            });
-            // Stream stdout async
-            (async () => {
-                try {
-                    const stream = proc.stdout;
-                    const reader = stream.getReader();
-                    const decoder = new TextDecoder();
-                    while (true) {
-                        const { done, value } = await reader.read();
-                        if (done)
-                            break;
-                        const text = decoder.decode(value);
-                        setAnswer((a) => a + text);
-                    }
-                }
-                catch { }
-            })();
-            // Stream stderr async (in case the agent prints progress or errors there)
-            (async () => {
-                try {
-                    const stream = proc.stderr;
-                    const reader = stream.getReader();
-                    const decoder = new TextDecoder();
-                    while (true) {
-                        const { done, value } = await reader.read();
-                        if (done)
-                            break;
-                        const text = decoder.decode(value);
-                        setAnswer((a) => a + text);
-                    }
-                }
-                catch { }
-            })();
-            await proc.exited;
-            if (proc.exitCode !== 0 && answer.trim().length === 0) {
-                setAnswer("Failed to run ask command. Is your agent installed?");
-                setStatus("error");
-            }
-            else {
-                setStatus("done");
-            }
-        }
-        catch (err) {
-            setAnswer(`Spawn error: ${err.message}`);
-            setStatus("error");
-        }
-    }
-    // Auto scroll logic in OpenTUI: scrollboxes generally stay at the top unless navigated? 
-    // For streaming, we'll just append text.
-    return (<box style={{
-            flexGrow: 1,
-            width: "100%",
-            height: "100%",
-            border: true,
-            borderColor: "magenta",
-            flexDirection: "column",
-        }} title={`Ask Smithers ${status === "input" ? "[Type Question, Enter to Submit, Esc to Close]" : "[Streaming... Esc to Close]"}`}>
-      {status === "input" ? (<box style={{ flexDirection: "column", paddingLeft: 1, paddingTop: 1 }}>
-          <text style={{ color: "cyan" }}>What would you like to know about the Smithers orchestrator?</text>
-          <text style={{ color: "white", marginTop: 1 }}>{"> "}{question}█</text>
-        </box>) : (<scrollbox style={{ width: "100%", height: "100%", flexDirection: "column", paddingLeft: 1 }}>
-          <text style={{ color: "cyan", marginBottom: 1 }}>Q: {question}</text>
-          <text style={{ color: "white" }}>{answer}</text>
-          {status === "done" && <text style={{ color: "green", marginTop: 1 }}>[ Agent finished. Press Esc to close. ]</text>}
-          {status === "error" && <text style={{ color: "red", marginTop: 1 }}>[ Agent failed. Press Esc to close. ]</text>}
-        </scrollbox>)}
-    </box>);
-}

package/src/tui/components/AskModal.tsx

@@ -1,3 +0,0 @@
-export declare function AskModal({ onClose }: {
-    onClose: () => void;
-}): import("react/jsx-runtime").JSX.Element;