@sweny-ai/core 0.1.66 → 0.1.68

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

@@ -0,0 +1,209 @@
+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 { shouldSkip, readCache, writeCache, isCacheFresh, formatNudge, defaultCachePath, maybeNudge, CACHE_TTL_MS, } from "../version-check.js";
+function captureStream() {
+    const chunks = [];
+    const stream = {
+        write: (chunk) => {
+            chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+            return true;
+        },
+    };
+    return {
+        stream,
+        get text() {
+            return chunks.join("");
+        },
+    };
+}
+describe("shouldSkip", () => {
+    it("skips in CI", () => {
+        expect(shouldSkip({ CI: "1" }, true, "run")).toBe(true);
+    });
+    it("skips when SWENY_NO_UPDATE_CHECK is set", () => {
+        expect(shouldSkip({ SWENY_NO_UPDATE_CHECK: "1" }, true, "run")).toBe(true);
+    });
+    it("skips when SWENY_OFFLINE is set", () => {
+        expect(shouldSkip({ SWENY_OFFLINE: "1" }, true, "run")).toBe(true);
+    });
+    it("skips non-TTY invocations (pipes, scripts)", () => {
+        expect(shouldSkip({}, false, "run")).toBe(true);
+    });
+    it("skips the upgrade command itself to avoid double-printing", () => {
+        expect(shouldSkip({}, true, "upgrade")).toBe(true);
+        expect(shouldSkip({}, true, "update")).toBe(true);
+    });
+    it("allows the nudge in an interactive TTY with no opt-out", () => {
+        expect(shouldSkip({}, true, "run")).toBe(false);
+    });
+});
+describe("cache I/O", () => {
+    let tmpdir;
+    let cachePath;
+    beforeEach(() => {
+        tmpdir = fs.mkdtempSync(path.join(os.tmpdir(), "sweny-version-check-"));
+        cachePath = path.join(tmpdir, "sub", "version-check.json");
+    });
+    afterEach(() => {
+        fs.rmSync(tmpdir, { recursive: true, force: true });
+    });
+    it("round-trips a valid cache entry", () => {
+        writeCache(cachePath, { latest: "0.1.66", checkedAt: 12345 });
+        expect(readCache(cachePath)).toEqual({ latest: "0.1.66", checkedAt: 12345 });
+    });
+    it("creates parent directories as needed", () => {
+        writeCache(cachePath, { latest: "0.1.66", checkedAt: 12345 });
+        expect(fs.existsSync(cachePath)).toBe(true);
+    });
+    it("returns null for a missing cache file", () => {
+        expect(readCache(cachePath)).toBeNull();
+    });
+    it("returns null when the cache is malformed JSON", () => {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, "{{{not json");
+        expect(readCache(cachePath)).toBeNull();
+    });
+    it("returns null when required fields are missing or wrong type", () => {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, JSON.stringify({ latest: "0.1.66" }));
+        expect(readCache(cachePath)).toBeNull();
+        fs.writeFileSync(cachePath, JSON.stringify({ checkedAt: 1 }));
+        expect(readCache(cachePath)).toBeNull();
+        fs.writeFileSync(cachePath, JSON.stringify({ latest: "", checkedAt: 1 }));
+        expect(readCache(cachePath)).toBeNull();
+    });
+    it("never throws on unwritable cache directories (degrades silently)", () => {
+        // Point at a path where the parent is a file — mkdirSync will throw,
+        // and writeCache must swallow it.
+        const blocker = path.join(tmpdir, "blocker");
+        fs.writeFileSync(blocker, "im-a-file");
+        expect(() => writeCache(path.join(blocker, "cache.json"), { latest: "0.1.66", checkedAt: 1 })).not.toThrow();
+    });
+});
+describe("isCacheFresh", () => {
+    it("returns true within TTL", () => {
+        expect(isCacheFresh({ latest: "x", checkedAt: 1000 }, 1000 + CACHE_TTL_MS - 1)).toBe(true);
+    });
+    it("returns false at or past TTL", () => {
+        expect(isCacheFresh({ latest: "x", checkedAt: 1000 }, 1000 + CACHE_TTL_MS)).toBe(false);
+        expect(isCacheFresh({ latest: "x", checkedAt: 1000 }, 1000 + CACHE_TTL_MS + 1)).toBe(false);
+    });
+});
+describe("formatNudge", () => {
+    it("includes both versions and the upgrade command", () => {
+        const out = formatNudge("0.1.65", "0.1.66");
+        expect(out).toContain("0.1.65");
+        expect(out).toContain("0.1.66");
+        expect(out).toContain("sweny upgrade");
+    });
+});
+describe("defaultCachePath", () => {
+    it("honors XDG_CACHE_HOME when set", () => {
+        const p = defaultCachePath({ XDG_CACHE_HOME: "/custom/cache" }, "/home/x");
+        expect(p).toBe(path.join("/custom/cache", "sweny", "version-check.json"));
+    });
+    it("falls back to ~/.cache when XDG_CACHE_HOME is unset", () => {
+        expect(defaultCachePath({}, "/home/x")).toBe(path.join("/home/x/.cache", "sweny", "version-check.json"));
+    });
+    it("treats empty XDG_CACHE_HOME as unset (defensive)", () => {
+        expect(defaultCachePath({ XDG_CACHE_HOME: "" }, "/home/x")).toBe(path.join("/home/x/.cache", "sweny", "version-check.json"));
+    });
+});
+describe("maybeNudge", () => {
+    let tmpdir;
+    let cachePath;
+    let stderr;
+    const fetchOk = vi.fn(async () => "9.9.9");
+    beforeEach(() => {
+        tmpdir = fs.mkdtempSync(path.join(os.tmpdir(), "sweny-nudge-"));
+        cachePath = path.join(tmpdir, "version-check.json");
+        stderr = captureStream();
+        fetchOk.mockClear();
+    });
+    afterEach(() => {
+        fs.rmSync(tmpdir, { recursive: true, force: true });
+    });
+    function baseDeps(over = {}) {
+        return {
+            currentVersion: "0.1.65",
+            cachePath,
+            now: 1_000_000,
+            env: {},
+            isTty: true,
+            commandName: "run",
+            stderr: stderr.stream,
+            fetchLatestVersion: fetchOk,
+            ...over,
+        };
+    }
+    it("prints nudge when cache shows a newer release", async () => {
+        writeCache(cachePath, { latest: "0.1.66", checkedAt: 1_000_000 });
+        await maybeNudge(baseDeps());
+        expect(stderr.text).toMatch(/0\.1\.66 is available/);
+        expect(stderr.text).toMatch(/sweny upgrade/);
+    });
+    it("stays silent when cache is equal or lower than current", async () => {
+        writeCache(cachePath, { latest: "0.1.65", checkedAt: 1_000_000 });
+        await maybeNudge(baseDeps());
+        expect(stderr.text).toBe("");
+    });
+    it("refreshes the cache when stale and writes the fetched version", async () => {
+        writeCache(cachePath, { latest: "0.1.64", checkedAt: 0 });
+        await maybeNudge(baseDeps({ now: CACHE_TTL_MS + 10 }));
+        expect(fetchOk).toHaveBeenCalledWith("latest");
+        const after = readCache(cachePath);
+        expect(after?.latest).toBe("9.9.9");
+        expect(after?.checkedAt).toBe(CACHE_TTL_MS + 10);
+    });
+    it("refreshes when cache is missing and does not crash when fetch fails", async () => {
+        const fetchFail = vi.fn(async () => {
+            throw new Error("ENETDOWN");
+        });
+        await maybeNudge(baseDeps({ fetchLatestVersion: fetchFail }));
+        expect(fetchFail).toHaveBeenCalled();
+        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 }));
+        expect(fetchOk).not.toHaveBeenCalled();
+    });
+    it("skips entirely in CI — no nudge, no fetch", async () => {
+        writeCache(cachePath, { latest: "0.1.66", checkedAt: 1_000_000 });
+        await maybeNudge(baseDeps({ env: { CI: "1" } }));
+        expect(stderr.text).toBe("");
+        expect(fetchOk).not.toHaveBeenCalled();
+    });
+    it("skips entirely on non-TTY stderr", async () => {
+        writeCache(cachePath, { latest: "0.1.66", checkedAt: 1_000_000 });
+        await maybeNudge(baseDeps({ isTty: false }));
+        expect(stderr.text).toBe("");
+        expect(fetchOk).not.toHaveBeenCalled();
+    });
+    it("suppresses the nudge from within `sweny upgrade` itself", async () => {
+        writeCache(cachePath, { latest: "0.1.66", checkedAt: 1_000_000 });
+        await maybeNudge(baseDeps({ commandName: "upgrade" }));
+        expect(stderr.text).toBe("");
+        expect(fetchOk).not.toHaveBeenCalled();
+    });
+});

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

@@ -31,6 +31,9 @@ import { checkProviderConnectivity } from "./check.js";
 import { registerSetupCommand } from "./setup.js";
 import { registerPublishCommand } from "./publish.js";
 import { reportToCloud } from "./cloud-report.js";
+import { runUpgrade, fetchLatestFromNpm } from "./upgrade.js";
+import { maybeNudge, defaultCachePath } from "./version-check.js";
+import { spawnSync } from "node:child_process";
 // ── Stream observer (NDJSON) ────────────────────────────────────────
 /**
  * Create an observer that writes NDJSON ExecutionEvents to stdout.
@@ -796,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>")
@@ -961,4 +964,69 @@ workflowCmd
     }
     console.log();
 });
-program.parse();
+// ── sweny upgrade / update ────────────────────────────────────────────
+// Self-update the globally-installed @sweny-ai/core. Mirrors the UX of
+// `bun upgrade`, `deno upgrade`, `rustup update`, etc.
+program
+    .command("upgrade")
+    .alias("update")
+    .description("Upgrade sweny to the latest published version")
+    .option("--check", "Report what would be installed without running the installer")
+    .option("--force", "Reinstall even if the current version is already latest")
+    .option("--tag <tag>", "npm dist-tag to install (default: latest)", "latest")
+    .action(async (options) => {
+    // process.argv[1] is the CLI entrypoint — resolve through any symlinks
+    // (nvm, homebrew, etc. symlink the bin into a PATH dir) so PM detection
+    // looks at the real install location.
+    const argv1 = process.argv[1] ?? "";
+    let installPath = argv1;
+    try {
+        installPath = fs.realpathSync(argv1);
+    }
+    catch {
+        // Fall through with the unresolved path; detection degrades gracefully.
+    }
+    await runUpgrade(options, {
+        currentVersion: version,
+        installPath,
+        fetchLatestVersion: fetchLatestFromNpm,
+        runInstall: (cmd, args) => {
+            // 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;
+            }
+            return typeof res.status === "number" ? res.status : 1;
+        },
+        canWrite: (dir) => {
+            try {
+                fs.accessSync(dir, fs.constants.W_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    });
+});
+// ── 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.
+program.hook("postAction", async (_thisCommand, actionCommand) => {
+    const topLevel = actionCommand.parent?.name() === "sweny" ? actionCommand.name() : actionCommand.parent?.name();
+    await maybeNudge({
+        currentVersion: version,
+        cachePath: defaultCachePath(),
+        now: Date.now(),
+        env: process.env,
+        isTty: Boolean(process.stderr.isTTY),
+        commandName: topLevel,
+    });
+});
+await program.parseAsync();

package/dist/cli/upgrade.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `sweny upgrade` — self-update the globally-installed `@sweny-ai/core` CLI.
+ *
+ * The hard parts are detection (which package manager owns this install?) and
+ * permissions (global node_modules often require sudo). We keep the runtime
+ * surface tiny via dependency injection so the whole flow is testable.
+ */
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun" | "volta" | "brew" | "unknown";
+export interface UpgradeOptions {
+    /** Skip the "already latest" short-circuit. */
+    force?: boolean;
+    /** Don't install — just report what would happen. */
+    check?: boolean;
+    /** Override the tag pulled from the registry. Defaults to "latest". */
+    tag?: string;
+}
+export interface UpgradeDeps {
+    /** Version currently running (from `package.json`). */
+    currentVersion: string;
+    /** Absolute path to the current CLI entrypoint — used for PM detection. */
+    installPath: string;
+    /** Fetch latest version for `@sweny-ai/core@<tag>`. */
+    fetchLatestVersion: (tag: string) => Promise<string>;
+    /** Run the resolved install command. Returns the process exit code. */
+    runInstall: (cmd: string, args: string[]) => number;
+    /** Writable-dir probe for EACCES detection. */
+    canWrite: (dir: string) => boolean;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    exit?: (code: number) => void;
+}
+/**
+ * Detect the package manager that owns this install by walking the parent
+ * chain of the CLI entrypoint. The rules are ordered by specificity — more
+ * distinctive roots (bun, volta, pnpm, homebrew) beat the generic
+ * `lib/node_modules` npm layout.
+ */
+export declare function detectPackageManager(installPath: string): PackageManager;
+/**
+ * Resolve the install-root directory for writability checks. For npm-style
+ * layouts, walk up until we find `node_modules/@sweny-ai/core` and return
+ * the parent of `node_modules` (the writable prefix). Returns null if the
+ * install path doesn't look like a package-manager install.
+ */
+export declare function resolveInstallRoot(installPath: string): string | null;
+/** Build the (cmd, args) pair for a given package manager + tag. */
+export declare function installCommandFor(pm: PackageManager, tag: string): {
+    cmd: string;
+    args: string[];
+} | null;
+/**
+ * Compare two semver-ish version strings. Returns:
+ *  - `>0` when `a > b`
+ *  - `<0` when `a < b`
+ *  - `0` when equal
+ *
+ * Handles numeric core (`major.minor.patch`) and pre-release strings
+ * conservatively: any pre-release (`-alpha.1`) is treated as *lower* than
+ * the same core without one, matching npm's semver ordering at the level
+ * of precision we need for "is the registry newer than me."
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Fetch the latest published version of `@sweny-ai/core` from the npm
+ * registry. Uses the dist-tag endpoint which returns a small, cacheable JSON
+ * document — no tarball download.
+ */
+export declare function fetchLatestFromNpm(tag: string): Promise<string>;
+/**
+ * Main `sweny upgrade` entrypoint. Resolves the latest version, decides
+ * whether an install is needed, dispatches to the right package manager,
+ * and surfaces permission problems as actionable copy-paste commands.
+ */
+export declare function runUpgrade(options: UpgradeOptions, deps: UpgradeDeps): Promise<void>;