@sweny-ai/core 0.1.67 → 0.1.68

package/dist/cli/__tests__/diagram.test.js

@@ -2,8 +2,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { Command } from "commander";
-import { runWorkflowDiagram } from "../diagram.js";
+import { runWorkflowDiagram, resolveUseBlock } from "../diagram.js";
 const sampleWorkflow = {
     id: "sample",
     name: "Sample",
@@ -32,6 +31,42 @@ function captureStream() {
         },
     };
 }
+describe("resolveUseBlock", () => {
+    // Centralized behavior test — the renderer is a tiny switch around this
+    // so keeping the rules here as one table makes the policy easy to audit.
+    it("returns false by default (stdout, no -o, no flags)", () => {
+        expect(resolveUseBlock({})).toBe(false);
+    });
+    it("returns true when --block is explicit", () => {
+        expect(resolveUseBlock({ block: true })).toBe(true);
+    });
+    it("returns false when --no-block is explicit, even for .md", () => {
+        expect(resolveUseBlock({ block: false, output: "diagram.md" })).toBe(false);
+    });
+    it("infers true for .md output", () => {
+        expect(resolveUseBlock({ output: "diagram.md" })).toBe(true);
+    });
+    it("infers true for .markdown output", () => {
+        expect(resolveUseBlock({ output: "diagram.markdown" })).toBe(true);
+    });
+    it("infers false for .mmd output", () => {
+        expect(resolveUseBlock({ output: "diagram.mmd" })).toBe(false);
+    });
+    it("infers false for .mermaid output", () => {
+        expect(resolveUseBlock({ output: "diagram.mermaid" })).toBe(false);
+    });
+    it("infers false for any other extension (.txt, no ext, etc.)", () => {
+        expect(resolveUseBlock({ output: "diagram.txt" })).toBe(false);
+        expect(resolveUseBlock({ output: "diagram" })).toBe(false);
+    });
+    it("is case-insensitive on extension", () => {
+        expect(resolveUseBlock({ output: "Diagram.MD" })).toBe(true);
+        expect(resolveUseBlock({ output: "Diagram.MMD" })).toBe(false);
+    });
+    it("lets explicit --block override .mmd extension", () => {
+        expect(resolveUseBlock({ block: true, output: "diagram.mmd" })).toBe(true);
+    });
+});
 describe("runWorkflowDiagram", () => {
     let tmpdir;
     const loadWorkflowFile = vi.fn((_f) => sampleWorkflow);
@@ -44,55 +79,78 @@ describe("runWorkflowDiagram", () => {
     afterEach(() => {
         fs.rmSync(tmpdir, { recursive: true, force: true });
     });
-    describe("stdout", () => {
-        it("writes a fenced mermaid block to stdout by default", () => {
+    describe("stdout — default behavior", () => {
+        it("writes RAW mermaid (no fence, no title frontmatter) by default", () => {
+            // This is the Mermaid-CLI / Live-Editor-compatible output. No ```,
+            // no `---\ntitle: …\n---` — just `graph TB` and the nodes.
             const stdout = captureStream();
             const stderr = captureStream();
             runWorkflowDiagram("any.yml", {}, { loadWorkflowFile, stdout: stdout.stream, stderr: stderr.stream, exit });
-            expect(stdout.text).toMatch(/^```mermaid\n/);
-            expect(stdout.text).toMatch(/\n```\n$/);
+            expect(stdout.text).not.toMatch(/```mermaid/);
+            expect(stdout.text).not.toMatch(/^---\ntitle:/);
+            expect(stdout.text).toMatch(/^graph TB/);
             expect(exit).not.toHaveBeenCalled();
         });
-        it("writes raw mermaid when --no-block is explicit", () => {
+        it("wraps in a ```mermaid fence when --block is explicit", () => {
             const stdout = captureStream();
-            const stderr = captureStream();
-            runWorkflowDiagram("any.yml", { block: false }, { loadWorkflowFile, stdout: stdout.stream, stderr: stderr.stream, exit });
-            expect(stdout.text).not.toMatch(/```mermaid/);
-            expect(stdout.text).toMatch(/graph TB/);
+            runWorkflowDiagram("any.yml", { block: true }, { loadWorkflowFile, stdout: stdout.stream, stderr: captureStream().stream, exit });
+            expect(stdout.text).toMatch(/^```mermaid\n/);
+            expect(stdout.text).toMatch(/\n```\n$/);
         });
         it("honors --direction LR", () => {
             const stdout = captureStream();
             runWorkflowDiagram("any.yml", { direction: "LR" }, { loadWorkflowFile, stdout: stdout.stream, stderr: captureStream().stream, exit });
             expect(stdout.text).toMatch(/graph LR/);
         });
-        it("honors --title override", () => {
+        it("emits --title as frontmatter only when explicitly set", () => {
             const stdout = captureStream();
             runWorkflowDiagram("any.yml", { title: "Custom Title" }, { loadWorkflowFile, stdout: stdout.stream, stderr: captureStream().stream, exit });
-            expect(stdout.text).toContain("Custom Title");
+            expect(stdout.text).toMatch(/^---\ntitle: Custom Title\n---\n/);
+            expect(stdout.text).toContain("graph TB");
+        });
+        it("does NOT default title to the workflow name", () => {
+            // Regression guard: previously we auto-filled `title` from workflow.name,
+            // which broke mmdc / mermaid-live because they don't accept title frontmatter.
+            const stdout = captureStream();
+            runWorkflowDiagram("any.yml", {}, { loadWorkflowFile, stdout: stdout.stream, stderr: captureStream().stream, exit });
+            expect(stdout.text).not.toMatch(/title:/);
+            expect(stdout.text).not.toContain("Sample"); // workflow.name
         });
     });
     describe("-o / --output file", () => {
-        it("writes raw mermaid to .mmd by default (no fence)", () => {
+        it("writes raw mermaid to .mmd (default)", () => {
             const out = path.join(tmpdir, "diagram.mmd");
             const stderr = captureStream();
             runWorkflowDiagram("any.yml", { output: out }, { loadWorkflowFile, stdout: captureStream().stream, stderr: stderr.stream, exit });
             const contents = fs.readFileSync(out, "utf8");
             expect(contents).not.toMatch(/```mermaid/);
-            expect(contents).toMatch(/graph TB/);
+            expect(contents).not.toMatch(/title:/);
+            expect(contents).toMatch(/^graph TB/);
             expect(stderr.text).toMatch(/✓ Wrote diagram to/);
         });
-        it("writes fenced markdown to .md by default", () => {
+        it("writes raw mermaid to .mermaid (Mermaid CLI's canonical extension)", () => {
+            const out = path.join(tmpdir, "diagram.mermaid");
+            runWorkflowDiagram("any.yml", { output: out }, { loadWorkflowFile, stdout: captureStream().stream, stderr: captureStream().stream, exit });
+            const contents = fs.readFileSync(out, "utf8");
+            expect(contents).not.toMatch(/```mermaid/);
+            expect(contents).toMatch(/^graph TB/);
+        });
+        it("writes fenced markdown to .md", () => {
             const out = path.join(tmpdir, "diagram.md");
             runWorkflowDiagram("any.yml", { output: out }, { loadWorkflowFile, stdout: captureStream().stream, stderr: captureStream().stream, exit });
             const contents = fs.readFileSync(out, "utf8");
             expect(contents).toMatch(/^```mermaid\n/);
             expect(contents).toMatch(/\n```\n$/);
         });
-        it("falls back to fenced default for unknown extensions", () => {
+        it("writes raw mermaid for unknown extensions (no longer falls back to fenced)", () => {
+            // Behavior change: previously .txt and friends got fenced as the
+            // "safe default". Now raw mermaid is the safe default because that's
+            // what every renderer actually accepts.
             const out = path.join(tmpdir, "diagram.txt");
             runWorkflowDiagram("any.yml", { output: out }, { loadWorkflowFile, stdout: captureStream().stream, stderr: captureStream().stream, exit });
             const contents = fs.readFileSync(out, "utf8");
-            expect(contents).toMatch(/```mermaid/);
+            expect(contents).not.toMatch(/```mermaid/);
+            expect(contents).toMatch(/graph TB/);
         });
         it("creates parent directories as needed (-o nested/subdir/file.mmd)", () => {
             const out = path.join(tmpdir, "a", "b", "c", "diagram.mmd");
@@ -107,51 +165,15 @@ describe("runWorkflowDiagram", () => {
             expect(stdout.text).toBe("");
         });
     });
-    describe("explicit --block / --no-block precedence over extension inference", () => {
-        function cmdWithBlock(block, explicit) {
-            const cmd = new Command();
-            cmd.option("--block", "fenced", true);
-            cmd.option("--no-block", "raw");
-            if (explicit) {
-                // Simulate user typing `--block` or `--no-block` on the CLI — commander
-                // marks the source as "cli" when the flag is seen in argv.
-                cmd.setOptionValueWithSource("block", block, "cli");
-            }
-            return cmd;
-        }
-        it("explicit --block wins over .mmd extension (writes fenced to .mmd)", () => {
+    describe("explicit --block / --no-block override extension inference", () => {
+        it("explicit --block wins over .mmd (writes fenced to .mmd)", () => {
             const out = path.join(tmpdir, "diagram.mmd");
-            runWorkflowDiagram("any.yml", { output: out, block: true }, {
-                loadWorkflowFile,
-                command: cmdWithBlock(true, true),
-                stdout: captureStream().stream,
-                stderr: captureStream().stream,
-                exit,
-            });
+            runWorkflowDiagram("any.yml", { output: out, block: true }, { loadWorkflowFile, stdout: captureStream().stream, stderr: captureStream().stream, exit });
             expect(fs.readFileSync(out, "utf8")).toMatch(/```mermaid/);
         });
-        it("explicit --no-block wins over .md extension (writes raw to .md)", () => {
+        it("explicit --no-block wins over .md (writes raw to .md)", () => {
             const out = path.join(tmpdir, "diagram.md");
-            runWorkflowDiagram("any.yml", { output: out, block: false }, {
-                loadWorkflowFile,
-                command: cmdWithBlock(false, true),
-                stdout: captureStream().stream,
-                stderr: captureStream().stream,
-                exit,
-            });
-            expect(fs.readFileSync(out, "utf8")).not.toMatch(/```mermaid/);
-        });
-        it("default --block source does not suppress .mmd extension inference", () => {
-            // Commander always sets `block: true` via the declared default, but its
-            // source is "default" — our inference should still kick in for .mmd.
-            const out = path.join(tmpdir, "diagram.mmd");
-            runWorkflowDiagram("any.yml", { output: out, block: true }, {
-                loadWorkflowFile,
-                command: cmdWithBlock(true, false), // not explicit
-                stdout: captureStream().stream,
-                stderr: captureStream().stream,
-                exit,
-            });
+            runWorkflowDiagram("any.yml", { output: out, block: false }, { loadWorkflowFile, stdout: captureStream().stream, stderr: captureStream().stream, exit });
             expect(fs.readFileSync(out, "utf8")).not.toMatch(/```mermaid/);
         });
     });
@@ -160,7 +182,9 @@ describe("runWorkflowDiagram", () => {
             const stdout = captureStream();
             runWorkflowDiagram("triage", {}, { loadWorkflowFile, stdout: stdout.stream, stderr: captureStream().stream, exit });
             expect(loadWorkflowFile).not.toHaveBeenCalled();
-            expect(stdout.text).toMatch(/```mermaid/);
+            expect(stdout.text).toMatch(/graph TB/);
+            // Confirm built-in renders raw by default too.
+            expect(stdout.text).not.toMatch(/```mermaid/);
         });
         it("resolves 'implement' without calling loadWorkflowFile", () => {
             const stdout = captureStream();

package/dist/cli/__tests__/upgrade.test.js

@@ -158,6 +158,17 @@ describe("runUpgrade — no-op paths", () => {
         expect(runInstall).toHaveBeenCalledWith("npm", ["install", "-g", "@sweny-ai/core@latest"]);
         expect(exit).toHaveBeenCalledWith(0);
     });
+    it("downgrades when --force is set against a local-dev build ahead of the registry", async () => {
+        const { deps, runInstall, exit } = makeDeps({
+            currentVersion: "0.2.0",
+            fetchLatestVersion: vi.fn(async () => "0.1.66"),
+        });
+        await runUpgrade({ force: true }, deps);
+        // --force explicitly overrides the "ahead" short-circuit — this is how
+        // someone pins back to the published train from a stale local build.
+        expect(runInstall).toHaveBeenCalledWith("npm", ["install", "-g", "@sweny-ai/core@latest"]);
+        expect(exit).toHaveBeenCalledWith(0);
+    });
 });
 describe("runUpgrade — install dispatch", () => {
     it("invokes the detected package manager and exits 0 on success", async () => {

package/dist/cli/__tests__/version-check.test.js

@@ -166,6 +166,23 @@ describe("maybeNudge", () => {
         expect(readCache(cachePath)).toBeNull(); // fetch failed, nothing written
         expect(stderr.text).toBe(""); // silent on error
     });
+    it("gives up silently when the registry is slower than the budget", async () => {
+        // The race between fetch and the internal timer means a slow fetch should
+        // resolve to null → no cache write → no nudge. We pin down the behavior
+        // here so a future regression (forgetting the race or the timeout) gets
+        // caught even though the budget is configured in the module itself.
+        const slowFetch = vi.fn(() => new Promise((resolve) => {
+            // Never resolves within the test — the internal timer is what wins.
+            const t = setTimeout(() => resolve("9.9.9"), 10_000);
+            if (typeof t.unref === "function") {
+                t.unref();
+            }
+        }));
+        await maybeNudge(baseDeps({ fetchLatestVersion: slowFetch }));
+        expect(slowFetch).toHaveBeenCalled();
+        expect(readCache(cachePath)).toBeNull();
+        expect(stderr.text).toBe("");
+    });
     it("does not refresh when cache is fresh (saves bandwidth)", async () => {
         writeCache(cachePath, { latest: "0.1.65", checkedAt: 1_000_000 });
         await maybeNudge(baseDeps({ now: 1_000_000 + 1 }));

package/dist/cli/diagram.d.ts

@@ -1,16 +1,24 @@
-import type { Command } from "commander";
 import type { Workflow } from "../types.js";
 export interface DiagramOptions {
     direction?: string;
+    /**
+     * Optional diagram title. When omitted we render pure Mermaid with no
+     * `---\ntitle: …\n---` frontmatter — the format that `mmdc`, Mermaid Live
+     * Editor, and `@mermaid-js/mermaid-cli` all accept as-is.
+     */
     title?: string;
+    /**
+     * Wrap output in a ```mermaid fenced code block. Tri-state:
+     *   - `true`  → fenced (forced by explicit `--block`)
+     *   - `false` → raw (forced by explicit `--no-block`)
+     *   - `undefined` → inferred from `--output` extension; default is raw
+     */
     block?: boolean;
     output?: string;
 }
 export interface DiagramDeps {
     /** Load a workflow file (YAML or JSON). Injected so tests can stub. */
     loadWorkflowFile: (file: string) => Workflow;
-    /** Commander instance used to detect whether --block was set explicitly. */
-    command?: Command;
     /** Stream for success/error messages. Defaults to process.stderr. */
     stderr?: NodeJS.WritableStream;
     /** Stream for diagram output when no --output is set. Defaults to process.stdout. */
@@ -18,13 +26,24 @@ export interface DiagramDeps {
     /** Exit handler. Defaults to process.exit. Tests can throw instead. */
     exit?: (code: number) => void;
 }
+/**
+ * Resolve whether output should be wrapped in a ```mermaid fenced block.
+ *
+ * Precedence:
+ *   1. Explicit `--block` / `--no-block` always wins.
+ *   2. When `-o` points at `.md`/`.markdown` we fence (markdown context).
+ *   3. Everything else — stdout, `.mmd`, `.mermaid`, unknown extensions —
+ *      emits raw Mermaid syntax that Mermaid CLI / Live Editor / mmdc can
+ *      consume directly with no preprocessing.
+ */
+export declare function resolveUseBlock(options: DiagramOptions): boolean;
 /**
  * Render a workflow as a Mermaid diagram and write to stdout or a file.
  *
- * Block-default rules (in order of precedence):
- *   1. Explicit `--block` / `--no-block` — always wins (detected via the
- *      Command's option-value source when provided)
- *   2. When `-o` is set, infer from extension: `.mmd` → raw, `.md` → fenced
- *   3. Otherwise default to fenced (matches prior stdout behavior)
+ * By default the output is pure Mermaid — no ```mermaid fence, no
+ * `---\ntitle: …\n---` frontmatter — so the result is directly consumable
+ * by Mermaid CLI (`mmdc`) and the Live Editor. Pass `--block` to wrap in a
+ * fenced code block for README embedding, or `--title` to inject a title
+ * header for Mermaid renderers that support it.
  */
 export declare function runWorkflowDiagram(file: string, options: DiagramOptions, deps: DiagramDeps): void;

package/dist/cli/diagram.js

@@ -3,14 +3,37 @@ import * as path from "node:path";
 import chalk from "chalk";
 import { toMermaid, toMermaidBlock } from "../mermaid.js";
 import { triageWorkflow, implementWorkflow, seedContentWorkflow } from "../workflows/index.js";
+const MARKDOWN_EXTS = new Set([".md", ".markdown"]);
+/**
+ * Resolve whether output should be wrapped in a ```mermaid fenced block.
+ *
+ * Precedence:
+ *   1. Explicit `--block` / `--no-block` always wins.
+ *   2. When `-o` points at `.md`/`.markdown` we fence (markdown context).
+ *   3. Everything else — stdout, `.mmd`, `.mermaid`, unknown extensions —
+ *      emits raw Mermaid syntax that Mermaid CLI / Live Editor / mmdc can
+ *      consume directly with no preprocessing.
+ */
+export function resolveUseBlock(options) {
+    if (options.block === true)
+        return true;
+    if (options.block === false)
+        return false;
+    if (options.output) {
+        const ext = path.extname(options.output).toLowerCase();
+        if (MARKDOWN_EXTS.has(ext))
+            return true;
+    }
+    return false;
+}
 /**
  * Render a workflow as a Mermaid diagram and write to stdout or a file.
  *
- * Block-default rules (in order of precedence):
- *   1. Explicit `--block` / `--no-block` — always wins (detected via the
- *      Command's option-value source when provided)
- *   2. When `-o` is set, infer from extension: `.mmd` → raw, `.md` → fenced
- *   3. Otherwise default to fenced (matches prior stdout behavior)
+ * By default the output is pure Mermaid — no ```mermaid fence, no
+ * `---\ntitle: …\n---` frontmatter — so the result is directly consumable
+ * by Mermaid CLI (`mmdc`) and the Live Editor. Pass `--block` to wrap in a
+ * fenced code block for README embedding, or `--title` to inject a title
+ * header for Mermaid renderers that support it.
  */
 export function runWorkflowDiagram(file, options, deps) {
     const stderr = deps.stderr ?? process.stderr;
@@ -38,21 +61,14 @@ export function runWorkflowDiagram(file, options, deps) {
         }
     }
     const direction = (options.direction === "LR" ? "LR" : "TB");
-    const title = options.title ?? workflow.name;
-    // Explicit --block / --no-block always wins. When commander's source is
-    // "cli" or "env" the user (or env var) set it; otherwise we may infer.
-    const blockSource = deps.command?.getOptionValueSource("block");
-    const blockExplicit = blockSource === "cli" || blockSource === "env";
-    let useBlock = options.block !== false;
-    if (!blockExplicit && options.output) {
-        const ext = path.extname(options.output).toLowerCase();
-        if (ext === ".mmd")
-            useBlock = false;
-        else if (ext === ".md")
-            useBlock = true;
-    }
+    const useBlock = resolveUseBlock(options);
     const render = useBlock ? toMermaidBlock : toMermaid;
-    const output = render(workflow, { direction, title }) + "\n";
+    // Title is opt-in only — an unset `--title` produces no frontmatter. Users
+    // who want the workflow.name as title can pass `--title "$(name)"`.
+    const renderOpts = { direction };
+    if (options.title)
+        renderOpts.title = options.title;
+    const output = render(workflow, renderOpts) + "\n";
     if (options.output) {
         try {
             // Create parent dirs so `-o some/nested/diagram.mmd` works without a

package/dist/cli/main.js

@@ -799,14 +799,14 @@ workflowCmd
     .action(workflowRunAction);
 workflowCmd
     .command("diagram <file>")
-    .description("Render a workflow as a Mermaid diagram")
+    .description("Render a workflow as a Mermaid diagram (raw .mmd by default; .md output auto-fences)")
     .option("--direction <dir>", "Graph direction: TB (top-bottom) or LR (left-right)", "TB")
-    .option("--title <title>", "Diagram title (defaults to workflow name)")
-    .option("--block", "Wrap in ```mermaid fenced code block (default)", true)
-    .option("--no-block", "Output raw Mermaid without code fence")
-    .option("-o, --output <path>", "Write the diagram to a file instead of stdout")
-    .action(function diagramAction(file, options) {
-    runWorkflowDiagram(file, options, { loadWorkflowFile, command: this });
+    .option("--title <title>", "Inject a title header (off by default — raw Mermaid has no title)")
+    .option("--block", "Wrap in ```mermaid fenced code block (forces fencing in any output)")
+    .option("--no-block", "Force raw Mermaid even when writing to a .md file")
+    .option("-o, --output <path>", "Write to a file instead of stdout (.mmd/.mermaid raw; .md fenced)")
+    .action((file, options) => {
+    runWorkflowDiagram(file, options, { loadWorkflowFile });
 });
 workflowCmd
     .command("export <name>")
@@ -967,7 +967,7 @@ workflowCmd
 // ── sweny upgrade / update ────────────────────────────────────────────
 // Self-update the globally-installed @sweny-ai/core. Mirrors the UX of
 // `bun upgrade`, `deno upgrade`, `rustup update`, etc.
-const upgradeCmd = program
+program
     .command("upgrade")
     .alias("update")
     .description("Upgrade sweny to the latest published version")
@@ -991,7 +991,13 @@ const upgradeCmd = program
         installPath,
         fetchLatestVersion: fetchLatestFromNpm,
         runInstall: (cmd, args) => {
-            const res = spawnSync(cmd, args, { stdio: "inherit" });
+            // Windows: `npm`/`pnpm`/`yarn` are `.cmd` shims and Node's spawn can't
+            // resolve them without a shell. Everywhere else we skip the shell to
+            // keep argv unambiguous and avoid injection surface.
+            const res = spawnSync(cmd, args, {
+                stdio: "inherit",
+                shell: process.platform === "win32",
+            });
             if (res.error) {
                 process.stderr.write(chalk.red(`  Error: couldn't run ${cmd} — ${res.error.message}`) + "\n");
                 return 127;
@@ -1009,8 +1015,6 @@ const upgradeCmd = program
         },
     });
 });
-// Touch upgradeCmd so TS/ESLint don't flag it unused if someone tightens rules.
-void upgradeCmd;
 // ── Passive "new version available" nudge ─────────────────────────────
 // Runs after every command. Non-blocking, bounded to 1.5s, silent on any
 // failure, skipped in CI / non-TTY / opt-out environments.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.67",
+  "version": "0.1.68",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"