@sweny-ai/core 0.1.123 → 0.1.124

package/dist/cli/new.js

@@ -355,11 +355,12 @@ export function buildEnvTemplate(credentials) {
         if (cred.hint) {
             lines.push(`# ${cred.hint}`);
         }
+        const prefix = cred.optional ? "# " : "";
         if (cred.default !== undefined) {
-            lines.push(`${cred.key}=${cred.default}`);
+            lines.push(`${prefix}${cred.key}=${cred.default}`);
         }
         else {
-            lines.push(`${cred.key}=`);
+            lines.push(`${prefix}${cred.key}=`);
         }
         lines.push("");
     }
@@ -441,6 +442,47 @@ export function writeWorkflowFile(cwd, id, yaml, options) {
     fs.writeFileSync(target, yaml, "utf-8");
     return { written: true, path: target };
 }
+/**
+ * Make sure `.env` is gitignored: create `.gitignore` if missing, append
+ * `.env` if absent. Returns what happened.
+ */
+export function ensureGitignoreEnv(cwd) {
+    const gitignorePath = path.join(cwd, ".gitignore");
+    if (!fs.existsSync(gitignorePath)) {
+        fs.writeFileSync(gitignorePath, ".env\n", "utf-8");
+        return "created";
+    }
+    const content = fs.readFileSync(gitignorePath, "utf-8");
+    if (content.split(/\r?\n/).some((line) => line.trim() === ".env"))
+        return "present";
+    const sep = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+    fs.appendFileSync(gitignorePath, `${sep}.env\n`, "utf-8");
+    return "appended";
+}
+/** The command to show in next steps: `npx` users have no `sweny` on PATH. */
+function cliCommand() {
+    return process.env.npm_command === "exec" ? "npx @sweny-ai/core" : "sweny";
+}
+/** Usage printed (exit 2) when `sweny new` has no terminal and no --yes. */
+export function nonInteractiveUsage() {
+    return [
+        "sweny new needs a terminal to ask questions. Non-interactive form:",
+        "",
+        "  sweny new --template <id> --yes",
+        "",
+        `Templates: ${WORKFLOW_TEMPLATES.map((t) => t.id).join(", ")}`,
+        `Zero-credential starter: sweny new --template ${WORKFLOW_TEMPLATES[0].id} --yes`,
+    ].join("\n");
+}
+/** Credentials to list for a workflow: a no-skill starter only needs Claude auth, which a Claude Code login covers. */
+function credentialsForWorkflow(skillIds, allSkills) {
+    const creds = collectCredentialsForSkills(skillIds, allSkills);
+    if (skillIds.length > 0)
+        return creds;
+    return creds.map((c) => c.key === "ANTHROPIC_API_KEY"
+        ? { ...c, optional: true, hint: "Not needed if you are logged in to Claude Code (run `claude` once)" }
+        : c);
+}
 // ── Interactive wizard ────────────────────────────────────────────────
 function cancel() {
     p.cancel("Setup cancelled.");
@@ -468,6 +510,17 @@ function cancel() {
  */
 export async function runNew(options) {
     const cwd = process.cwd();
+    // `sweny new <id>`: a built-in template id wins over a marketplace lookup,
+    // so it works with no network. Only other ids go to the marketplace.
+    if (options?.marketplaceId && options.marketplaceId !== "e2e" && !options.forceMarketplace) {
+        if (WORKFLOW_TEMPLATES.some((t) => t.id === options.marketplaceId)) {
+            return runNew({ template: options.marketplaceId, skipIntro: options.skipIntro, yes: options.yes });
+        }
+    }
+    if (options?.template && !WORKFLOW_TEMPLATES.some((t) => t.id === options.template)) {
+        p.log.error(`Unknown template "${options.template}". Available: ${WORKFLOW_TEMPLATES.map((t) => t.id).join(", ")}`);
+        process.exit(1);
+    }
     // ── E2E shortcut: `sweny new e2e` jumps straight into the e2e wizard ──
     // `new` is the single entry for all workflow creation; this is a named
     // shortcut into the same flow the interactive picker reaches via "__e2e".
@@ -491,6 +544,10 @@ export async function runNew(options) {
         // Check for existing workflow file and prompt before fetching.
         const existingWorkflowPath = path.join(cwd, ".sweny", "workflows", `${options.marketplaceId}.yml`);
         let overwrite = false;
+        if (fs.existsSync(existingWorkflowPath) && options.yes) {
+            p.log.info(`Workflow already exists at ${path.relative(cwd, existingWorkflowPath)}. Not overwritten.`);
+            return;
+        }
         if (fs.existsSync(existingWorkflowPath)) {
             const confirmed = await p.confirm({
                 message: `.sweny/workflows/${options.marketplaceId}.yml already exists. Overwrite?`,
@@ -515,7 +572,8 @@ export async function runNew(options) {
             });
         }
         catch (err) {
-            p.log.error(err instanceof Error ? err.message : String(err));
+            const reason = err instanceof Error ? err.message : String(err);
+            p.log.error(`${reason}\nNot a built-in template either. Built-in templates (work offline): ${WORKFLOW_TEMPLATES.map((t) => t.id).join(", ")}`);
             process.exit(1);
         }
         if (!result.installed) {
@@ -546,44 +604,57 @@ export async function runNew(options) {
         p.log.info(`Found ${customSkills.length} custom skill(s): ${chalk.cyan(customSkills.map((s) => s.id).join(", "))}`);
     }
     // ── Step 1: Pick a workflow ─────────────────────────────────────────
-    const templateChoice = await p.select({
-        message: "What do you want to do?",
-        options: [
-            {
-                value: "__marketplace",
-                label: "Browse marketplace",
-                hint: "install a published workflow from swenyai/workflows",
-            },
-            ...WORKFLOW_TEMPLATES.map((t) => ({
-                value: t.id,
-                label: t.name,
-                hint: t.description,
-            })),
-            { value: "__e2e", label: "End-to-end browser testing", hint: "Automated browser tests for your app" },
-            { value: "__custom", label: "Describe your own", hint: "AI-generated from your description" },
-            { value: "__blank", label: "Start blank", hint: "just set up config, I'll create workflows later" },
-        ],
-    });
-    if (p.isCancel(templateChoice))
-        cancel();
-    // ── Marketplace short-circuit: fetch index, pick, delegate ──────────
-    if (templateChoice === "__marketplace") {
-        const { fetchMarketplaceIndex } = await import("./marketplace.js");
-        const spinner = p.spinner();
-        spinner.start("Fetching marketplace index…");
-        let entries;
+    // Marketplace is offered only when its index is reachable. Offline or a
+    // missing index must never leave the default option broken.
+    let marketplaceEntries = null;
+    let templateChoice;
+    if (options?.template) {
+        templateChoice = options.template;
+    }
+    else {
         try {
-            entries = await fetchMarketplaceIndex();
-            spinner.stop(`Found ${entries.length} workflow(s)`);
+            const { fetchMarketplaceIndex } = await import("./marketplace.js");
+            const entries = await fetchMarketplaceIndex({ timeoutMs: 3000 });
+            if (Array.isArray(entries) && entries.length > 0)
+                marketplaceEntries = entries;
+            else
+                p.log.info("Marketplace has no workflows yet. Showing built-in templates.");
         }
         catch (err) {
-            spinner.stop("Failed");
-            p.log.error(err instanceof Error ? err.message : String(err));
-            process.exit(1);
+            const reason = err instanceof Error ? err.message : String(err);
+            p.log.info(`Marketplace unavailable (${reason}). Showing built-in templates.`);
         }
+        templateChoice = await p.select({
+            message: "What do you want to do?",
+            initialValue: WORKFLOW_TEMPLATES[0].id,
+            options: [
+                ...WORKFLOW_TEMPLATES.map((t) => ({
+                    value: t.id,
+                    label: t.name,
+                    hint: t.description,
+                })),
+                ...(marketplaceEntries
+                    ? [
+                        {
+                            value: "__marketplace",
+                            label: "Browse marketplace",
+                            hint: "install a published workflow from swenyai/workflows",
+                        },
+                    ]
+                    : []),
+                { value: "__e2e", label: "End-to-end browser testing", hint: "Automated browser tests for your app" },
+                { value: "__custom", label: "Describe your own", hint: "AI-generated from your description" },
+                { value: "__blank", label: "Start blank", hint: "just set up config, I'll create workflows later" },
+            ],
+        });
+    }
+    if (p.isCancel(templateChoice))
+        cancel();
+    // ── Marketplace short-circuit: pick from the fetched index, delegate ──
+    if (templateChoice === "__marketplace" && marketplaceEntries) {
         const pick = await p.select({
             message: "Which workflow?",
-            options: entries.map((e) => ({
+            options: marketplaceEntries.map((e) => ({
                 value: e.id,
                 label: e.name,
                 hint: e.description,
@@ -593,7 +664,7 @@ export async function runNew(options) {
             cancel();
         // Delegate to the marketplace install path
         // Wizard already showed its intro — skip the fast-path intro to avoid doubling.
-        return runNew({ marketplaceId: pick, skipIntro: true });
+        return runNew({ marketplaceId: pick, skipIntro: true, forceMarketplace: true });
     }
     // ── E2E short-circuit: delegate to the e2e wizard ────────────────────
     if (templateChoice === "__e2e") {
@@ -617,7 +688,7 @@ export async function runNew(options) {
     const issueTracker = inferIssueTracker(workflowSkills, sourceControl);
     const observability = inferObservability(workflowSkills);
     // Collect credentials for the workflow's skills (+ always ANTHROPIC_API_KEY)
-    const credentials = collectCredentialsForSkills(workflowSkills, allSkills);
+    const credentials = credentialsForWorkflow(workflowSkills, allSkills);
     // ── Step 3: Summary + confirm ───────────────────────────────────────
     const files = [];
     if (!hasExistingConfig)
@@ -647,18 +718,20 @@ export async function runNew(options) {
     summaryLines.push(chalk.bold(hasExistingConfig ? "Workflow uses:" : "Inferred from workflow:"));
     summaryLines.push(...inferred);
     summaryLines.push("");
-    summaryLines.push(chalk.bold(`Credentials needed: ${credentials.length}`));
-    summaryLines.push(...credentials.map((c) => `  ${chalk.dim(c.key)}`));
+    summaryLines.push(chalk.bold(`Credentials: ${credentials.filter((c) => !c.optional).length} required`));
+    summaryLines.push(...credentials.map((c) => `  ${chalk.dim(c.key)}${c.optional ? chalk.dim(" (optional with a Claude Code login)") : ""}`));
     p.log.message(summaryLines.join("\n"));
-    const confirmed = await p.confirm({
-        message: hasExistingConfig ? "Add this workflow?" : "Create these files?",
-        initialValue: true,
-    });
-    if (p.isCancel(confirmed))
-        cancel();
-    if (!confirmed) {
-        p.cancel("Setup cancelled.");
-        process.exit(0);
+    if (!options?.yes) {
+        const confirmed = await p.confirm({
+            message: hasExistingConfig ? "Add this workflow?" : "Create these files?",
+            initialValue: true,
+        });
+        if (p.isCancel(confirmed))
+            cancel();
+        if (!confirmed) {
+            p.cancel("Setup cancelled.");
+            process.exit(0);
+        }
     }
     // ── Step 4: Write files ─────────────────────────────────────────────
     // 1. Write .sweny.yml (only if fresh)
@@ -684,6 +757,11 @@ export async function runNew(options) {
     // 3. Workflow template
     if (template) {
         const firstAttempt = writeWorkflowFile(cwd, template.id, template.yaml, { overwrite: false });
+        if (firstAttempt.exists && options?.yes) {
+            p.log.info(`.sweny/workflows/${template.id}.yml already exists, not overwritten`);
+            p.outro("Done.");
+            return;
+        }
         if (firstAttempt.exists) {
             const overwrite = await p.confirm({
                 message: `.sweny/workflows/${template.id}.yml already exists. Overwrite?`,
@@ -700,30 +778,26 @@ export async function runNew(options) {
         }
         p.log.success(`Created .sweny/workflows/${template.id}.yml`);
     }
-    // 4. .gitignore check
-    const gitignorePath = path.join(cwd, ".gitignore");
-    if (fs.existsSync(gitignorePath)) {
-        const gitignore = fs.readFileSync(gitignorePath, "utf-8");
-        const envIgnored = gitignore.split("\n").some((line) => line.trim() === ".env");
-        if (!envIgnored) {
-            p.log.warn(chalk.yellow(".env is not in .gitignore — add it to avoid committing secrets"));
-        }
-    }
-    else {
-        p.log.warn(chalk.yellow("No .gitignore found — make sure .env is not committed"));
-    }
+    // 4. Keep .env out of version control
+    const ignoreResult = ensureGitignoreEnv(cwd);
+    if (ignoreResult === "created")
+        p.log.success("Created .gitignore with .env");
+    else if (ignoreResult === "appended")
+        p.log.success("Added .env to .gitignore");
     // 5. Next steps
-    const credUrls = credentials.filter((c) => c.url).map((c) => `  ${c.key}: ${c.url}`);
+    const requiredCreds = credentials.filter((c) => !c.optional);
+    const credUrls = requiredCreds.filter((c) => c.url).map((c) => `  ${c.key}: ${c.url}`);
     const steps = [];
     let stepNum = 1;
-    if (addedNewKeys) {
-        steps.push(`${stepNum++}. Fill in your API keys in .env:`, ...credUrls, "", `${stepNum++}. Verify connectivity:`, "   sweny check", "");
+    const cli = cliCommand();
+    if (addedNewKeys && requiredCreds.length > 0) {
+        steps.push(`${stepNum++}. Fill in your API keys in .env:`, ...credUrls, "", `${stepNum++}. Verify connectivity:`, `   ${cli} check`, "");
     }
     if (template) {
-        steps.push(`${stepNum++}. Run your workflow:`, `   sweny workflow run .sweny/workflows/${template.id}.yml`);
+        steps.push(`${stepNum++}. Run your workflow:`, `   ${cli} workflow run .sweny/workflows/${template.id}.yml`);
     }
     else {
-        steps.push(`${stepNum++}. Create your first workflow:`, "   sweny new");
+        steps.push(`${stepNum++}. Create your first workflow:`, `   ${cli} new`);
     }
     p.note(steps.join("\n"), "Next steps");
     p.outro(hasExistingConfig ? "Workflow added!" : "You're all set!");

package/dist/cli/publish.js

@@ -58,6 +58,15 @@ export function validateWorkflowFile(filePath) {
                 warnings,
             };
         }
+        // Marketplace templates are required to declare workflow_type (spec:
+        // https://spec.sweny.ai/nodes/#workflow_type). Absence defaults to
+        // "generic" at runtime, but a marketplace submission that never chose a
+        // type is a template that never got the cross-type renderer it should
+        // have. Warn, don't block: this stays a warning so existing community
+        // submissions aren't hard-rejected by `sweny publish`.
+        if (!workflow.workflow_type) {
+            warnings.push('Workflow does not declare "workflow_type" (pr_review, e2e_test, content_generation, monitor, data_sync, generic); defaults to "generic". Marketplace templates should declare one explicitly.');
+        }
         // Config completeness warnings
         const allSkills = [...builtinSkills, ...customSkills];
         const skillMap = new Map(allSkills.map((s) => [s.id, s]));

package/dist/cli/run-output.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Run-end output for `sweny workflow run`: the receipt line, the
+ * GITHUB_STEP_SUMMARY writer, the quiet-by-default logger, and the help text.
+ *
+ * METADATA ONLY. Nothing here reads prompts, node outputs, tool inputs, or
+ * model prose: only counts, durations, token totals, and cost.
+ */
+import { type ExecutionTrace, type Logger, type NodeResult, type Workflow } from "../types.js";
+export interface RunSummary {
+    ok: boolean;
+    nodesOk: number;
+    nodesTotal: number;
+    nodesSkipped: number;
+    toolCalls: number;
+    durationMs: number;
+    /** input + output tokens. Undefined when no node reported usage. */
+    tokens?: number;
+    /** Sum of SDK-reported cost. Undefined when the SDK reported none (never estimated). */
+    costUsd?: number;
+}
+/** Sum the per-node results into one run summary. */
+export declare function summarizeRun(results: Map<string, NodeResult>, durationMs: number, crashed?: boolean): RunSummary;
+export declare function formatReceiptDuration(ms: number): string;
+export declare function formatTokenCount(n: number): string;
+export declare function formatCost(usd: number): string;
+/**
+ * One plain line: `✓ 3/3 nodes · 41 tool calls · 2m10s · 12k tokens · $0.18`.
+ * Token and cost segments are omitted when the SDK reported none. No ANSI;
+ * callers colorize only when writing to a TTY.
+ */
+export declare function formatReceipt(s: RunSummary): string;
+/** Receipt for a terminal: colored only when `color` is true. */
+export declare function renderReceiptLine(s: RunSummary, color: boolean): string;
+/** Markdown for `$GITHUB_STEP_SUMMARY`: receipt + status-colored Mermaid DAG. */
+export declare function formatStepSummary(workflow: Workflow, results: Map<string, NodeResult>, summary: RunSummary, trace?: ExecutionTrace): string;
+/**
+ * Append the step summary to the file named by GITHUB_STEP_SUMMARY.
+ * Runner-agnostic: does nothing when the variable is unset or empty.
+ * Never throws; returns true only when something was written.
+ */
+export declare function writeStepSummary(workflow: Workflow, results: Map<string, NodeResult>, summary: RunSummary, trace?: ExecutionTrace, env?: NodeJS.ProcessEnv): boolean;
+export interface RunLogger extends Logger {
+    /** Write any warnings held back while a node line was live. */
+    flush(): void;
+}
+/**
+ * Logger for `workflow run`. With `verbose`, the raw `[info]`/`[debug]` lines
+ * pass through unchanged. Otherwise info/debug are dropped and warnings and
+ * errors are rendered as `  ⚠ msg` / `  ✗ msg` on stderr. On a TTY they are held
+ * while a node line is live (the progress line is redrawn in place) and written
+ * by `flush()` after the node exits.
+ */
+export declare function createRunLogger(opts: {
+    verbose: boolean;
+    tty: boolean;
+    write?: (s: string) => void;
+}): RunLogger;
+export declare const WORKFLOW_RUN_DESCRIPTION = "Run a workflow from a YAML or JSON file. With no file, batch-runs every workflow in .sweny/e2e/ (lists and confirms first; use --yes to skip the prompt).";
+export declare const WORKFLOW_RUN_OPTIONS: ReadonlyArray<readonly [flags: string, description: string]>;

package/dist/cli/run-output.js

@@ -0,0 +1,189 @@
+/**
+ * Run-end output for `sweny workflow run`: the receipt line, the
+ * GITHUB_STEP_SUMMARY writer, the quiet-by-default logger, and the help text.
+ *
+ * METADATA ONLY. Nothing here reads prompts, node outputs, tool inputs, or
+ * model prose: only counts, durations, token totals, and cost.
+ */
+import fs from "node:fs";
+import chalk from "chalk";
+import { consoleLogger } from "../types.js";
+import { toMermaidBlock } from "../mermaid.js";
+/** Sum the per-node results into one run summary. */
+export function summarizeRun(results, durationMs, crashed = false) {
+    let nodesOk = 0;
+    let nodesSkipped = 0;
+    let failed = crashed;
+    let toolCalls = 0;
+    let tokens;
+    let costUsd;
+    const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+    for (const r of results.values()) {
+        if (r.status === "success")
+            nodesOk++;
+        else if (r.status === "skipped")
+            nodesSkipped++;
+        else
+            failed = true;
+        toolCalls += r.toolCalls?.length ?? 0;
+        const u = r.usage;
+        if (u) {
+            if (isNum(u.inputTokens) || isNum(u.outputTokens)) {
+                tokens =
+                    (tokens ?? 0) + (isNum(u.inputTokens) ? u.inputTokens : 0) + (isNum(u.outputTokens) ? u.outputTokens : 0);
+            }
+            if (isNum(u.costUsd))
+                costUsd = (costUsd ?? 0) + u.costUsd;
+        }
+    }
+    return {
+        ok: !failed,
+        nodesOk,
+        nodesTotal: results.size,
+        nodesSkipped,
+        toolCalls,
+        durationMs,
+        ...(tokens !== undefined ? { tokens } : {}),
+        ...(costUsd !== undefined ? { costUsd } : {}),
+    };
+}
+export function formatReceiptDuration(ms) {
+    if (ms < 1000)
+        return `${Math.max(0, Math.round(ms))}ms`;
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    return `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
+}
+export function formatTokenCount(n) {
+    if (n < 1000)
+        return String(Math.round(n));
+    if (n < 10_000)
+        return `${Math.round(n / 100) / 10}k`;
+    if (n < 1_000_000)
+        return `${Math.round(n / 1000)}k`;
+    return `${Math.round(n / 100_000) / 10}M`;
+}
+export function formatCost(usd) {
+    if (usd > 0 && usd < 0.01)
+        return "<$0.01";
+    return `$${usd.toFixed(2)}`;
+}
+/**
+ * One plain line: `✓ 3/3 nodes · 41 tool calls · 2m10s · 12k tokens · $0.18`.
+ * Token and cost segments are omitted when the SDK reported none. No ANSI;
+ * callers colorize only when writing to a TTY.
+ */
+export function formatReceipt(s) {
+    const parts = [
+        `${s.ok ? "✓" : "✗"} ${s.nodesOk}/${s.nodesTotal} nodes`,
+        ...(s.nodesSkipped > 0 ? [`${s.nodesSkipped} skipped`] : []),
+        `${s.toolCalls} tool ${s.toolCalls === 1 ? "call" : "calls"}`,
+        formatReceiptDuration(s.durationMs),
+        ...(s.tokens !== undefined ? [`${formatTokenCount(s.tokens)} tokens`] : []),
+        ...(s.costUsd !== undefined ? [formatCost(s.costUsd)] : []),
+    ];
+    return parts.join(" · ");
+}
+/** Receipt for a terminal: colored only when `color` is true. */
+export function renderReceiptLine(s, color) {
+    const line = formatReceipt(s);
+    if (!color)
+        return line;
+    return s.ok ? chalk.green(line) : chalk.red(line);
+}
+// ── Step summary ────────────────────────────────────────────────
+/** Brand blue (blue-600 / blue-700), not indigo. Applied to successful nodes. */
+const STEP_SUMMARY_CLASS_DEFS = {
+    success: "fill:#2563eb,stroke:#1d4ed8,color:#fff,stroke-width:2px",
+};
+/** Markdown for `$GITHUB_STEP_SUMMARY`: receipt + status-colored Mermaid DAG. */
+export function formatStepSummary(workflow, results, summary, trace) {
+    const state = {};
+    for (const [id, r] of results) {
+        state[id] = r.status === "success" ? "success" : r.status === "failed" ? "failed" : "skipped";
+    }
+    return [
+        `## ${summary.ok ? "✅" : "❌"} ${workflow.name}`,
+        "",
+        `\`${formatReceipt(summary)}\``,
+        "",
+        toMermaidBlock(workflow, { state, trace, classDefs: STEP_SUMMARY_CLASS_DEFS }),
+        "",
+        "",
+    ].join("\n");
+}
+/**
+ * Append the step summary to the file named by GITHUB_STEP_SUMMARY.
+ * Runner-agnostic: does nothing when the variable is unset or empty.
+ * Never throws; returns true only when something was written.
+ */
+export function writeStepSummary(workflow, results, summary, trace, env = process.env) {
+    const file = env.GITHUB_STEP_SUMMARY;
+    if (!file)
+        return false;
+    try {
+        fs.appendFileSync(file, formatStepSummary(workflow, results, summary, trace));
+        return true;
+    }
+    catch (err) {
+        process.stderr.write(`  ⚠ could not write GITHUB_STEP_SUMMARY: ${err instanceof Error ? err.message : err}\n`);
+        return false;
+    }
+}
+/**
+ * Logger for `workflow run`. With `verbose`, the raw `[info]`/`[debug]` lines
+ * pass through unchanged. Otherwise info/debug are dropped and warnings and
+ * errors are rendered as `  ⚠ msg` / `  ✗ msg` on stderr. On a TTY they are held
+ * while a node line is live (the progress line is redrawn in place) and written
+ * by `flush()` after the node exits.
+ */
+export function createRunLogger(opts) {
+    const write = opts.write ?? ((s) => void process.stderr.write(s));
+    if (opts.verbose)
+        return { ...consoleLogger, flush() { } };
+    const held = [];
+    const emit = (line) => {
+        if (opts.tty)
+            held.push(line);
+        else
+            write(line);
+    };
+    const noop = () => { };
+    return {
+        info: noop,
+        debug: noop,
+        warn: (msg) => emit(`  ${chalk.yellow("⚠")} ${msg.trim()}\n`),
+        error: (msg) => emit(`  ${chalk.red("✗")} ${msg.trim()}\n`),
+        flush() {
+            while (held.length)
+                write(held.shift());
+        },
+    };
+}
+// ── Help text ───────────────────────────────────────────────────
+export const WORKFLOW_RUN_DESCRIPTION = "Run a workflow from a YAML or JSON file. With no file, batch-runs every workflow in .sweny/e2e/ (lists and confirms first; use --yes to skip the prompt).";
+export const WORKFLOW_RUN_OPTIONS = [
+    [
+        "--timeout <ms>",
+        "Whole-run wall-clock timeout in ms. Applies to batch runs (.sweny/e2e/) and to a single workflow file (default: 3600000 = 60 min; 0 = no wall-clock budget)",
+    ],
+    [
+        "--max-steps <n>",
+        "Hard cap on total node executions for a single workflow file, including eval-failure retries (default: 200)",
+    ],
+    ["-y, --yes", "Skip the batch confirmation prompt (for CI)"],
+    [
+        "--dry-run",
+        "Run with read-only tools only: write tools, external MCP servers, and shell/file-edit tools are withheld, so nothing is created, posted, or sent. Stops at the first conditional edge. To inspect nodes without running, use --list-nodes.",
+    ],
+    ["--list-nodes", "Validate, print nodes and skills, and exit without running"],
+    ["--json", "Output result as JSON on stdout; suppress progress output"],
+    ["--stream", "Stream NDJSON events to stdout (for Studio / automation)"],
+    [
+        "--verbose",
+        "Show raw log lines and each tool call's input and output inline (human-readable, truncated). Use --stream for full untruncated NDJSON.",
+    ],
+    ["--mermaid", "Output a Mermaid diagram with execution state after run"],
+    ["--input <json>", "JSON string of input data to pass to the workflow"],
+];

package/dist/cli/skill-env.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Missing-credential reporting for skills.
+ *
+ * A built-in skill whose required env var is unset is NOT an unknown skill.
+ * These helpers turn that state into one actionable line per skill
+ * (`skill "github" needs GITHUB_TOKEN (set it in .env)`), shared by
+ * `workflow run` (hard fail) and `workflow validate` (warning).
+ */
+import type { SkillValidationResult } from "../skills/index.js";
+import type { Skill } from "../types.js";
+export interface SkillEnvGap {
+    id: string;
+    missingEnv: string[];
+}
+/**
+ * Built-in skills referenced by a workflow that are not usable because a
+ * required env var is unset. `availableIds` is the configured skill set;
+ * inline and unknown ids never produce a gap.
+ */
+export declare function findSkillEnvGaps(skillIds: Iterable<string>, availableIds: ReadonlySet<string>, inlineIds?: ReadonlySet<string>): SkillEnvGap[];
+export declare function formatSkillEnvGap(gap: SkillEnvGap): string;
+/**
+ * Lines to print for a failed `validateWorkflowSkills`: one env line per
+ * built-in skill with missing env, plus node-level errors that carry extra
+ * information (alternatives among several skills, or unknown ids).
+ */
+export declare function formatMissingSkillLines(validation: SkillValidationResult): string[];
+/** Warnings for `workflow validate`: referenced skills whose env is missing. */
+export declare function skillEnvWarnings(workflow: {
+    nodes: Record<string, {
+        skills: string[];
+    }>;
+    skills?: Record<string, unknown>;
+}, env: Record<string, string | undefined>, available: Skill[]): string[];

package/dist/cli/skill-env.js

@@ -0,0 +1,64 @@
+/**
+ * Missing-credential reporting for skills.
+ *
+ * A built-in skill whose required env var is unset is NOT an unknown skill.
+ * These helpers turn that state into one actionable line per skill
+ * (`skill "github" needs GITHUB_TOKEN (set it in .env)`), shared by
+ * `workflow run` (hard fail) and `workflow validate` (warning).
+ */
+import { builtinSkills, isSkillConfigured } from "../skills/index.js";
+/**
+ * Built-in skills referenced by a workflow that are not usable because a
+ * required env var is unset. `availableIds` is the configured skill set;
+ * inline and unknown ids never produce a gap.
+ */
+export function findSkillEnvGaps(skillIds, availableIds, inlineIds = new Set()) {
+    const gaps = [];
+    const seen = new Set();
+    for (const id of skillIds) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        if (availableIds.has(id) || inlineIds.has(id))
+            continue;
+        const builtin = builtinSkills.find((s) => s.id === id);
+        if (!builtin)
+            continue;
+        const fields = Object.values(builtin.config).filter((f) => f.env);
+        const required = fields.filter((f) => f.required).map((f) => f.env);
+        const missingEnv = required.length > 0 ? required : fields.map((f) => f.env);
+        if (missingEnv.length === 0)
+            continue;
+        gaps.push({ id, missingEnv });
+    }
+    return gaps;
+}
+export function formatSkillEnvGap(gap) {
+    return `skill "${gap.id}" needs ${gap.missingEnv.join(", ")} (set it in .env)`;
+}
+/**
+ * Lines to print for a failed `validateWorkflowSkills`: one env line per
+ * built-in skill with missing env, plus node-level errors that carry extra
+ * information (alternatives among several skills, or unknown ids).
+ */
+export function formatMissingSkillLines(validation) {
+    const lines = [];
+    const envGaps = validation.missing.filter((m) => m.category !== "unknown" && m.missingEnv.length > 0);
+    const unknownIds = validation.missing.filter((m) => m.category === "unknown").map((m) => m.id);
+    for (const m of envGaps)
+        lines.push(formatSkillEnvGap({ id: m.id, missingEnv: m.missingEnv }));
+    for (const err of validation.errors) {
+        const listed = /needs one of: (.+)\)$/.exec(err)?.[1]?.split(", ") ?? [];
+        const involvesUnknown = listed.some((id) => unknownIds.includes(id));
+        if (involvesUnknown || listed.length > 1)
+            lines.push(err);
+    }
+    return lines;
+}
+/** Warnings for `workflow validate`: referenced skills whose env is missing. */
+export function skillEnvWarnings(workflow, env, available) {
+    const availableIds = new Set(available.filter((s) => isSkillConfigured(s, env)).map((s) => s.id));
+    const ids = Object.values(workflow.nodes).flatMap((n) => n.skills);
+    const inline = new Set(Object.keys(workflow.skills ?? {}));
+    return findSkillEnvGaps(ids, availableIds, inline).map(formatSkillEnvGap);
+}