reffy-cli 0.4.0 → 0.6.0

package/README.md

@@ -1,17 +1,17 @@
 # reffy
 
+[![npm version](https://img.shields.io/npm/v/reffy-cli.svg)](https://www.npmjs.com/package/reffy-cli)
+[![MIT License](https://img.shields.io/github/license/RoskiDeluge/reffy-ts.svg)](LICENSE)
+[![CI](https://github.com/RoskiDeluge/reffy-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/RoskiDeluge/reffy-ts/actions/workflows/ci.yml)
+
 Reffy is intended as an ideation layer for spec-driven development (SDD) in straightforward, version controlled and agent-friendly markdown files.
 
 ## Install
 
-Recommended usage in any repo:
-
 ```bash
 npm install -g reffy-cli
 ```
 
-The install runs this package's `prepare` step, which builds `dist/` automatically.
-
 ## Quickstart (CLI-only)
 
 Inside your project:
@@ -19,10 +19,6 @@ Inside your project:
 ```bash
 reffy init
 reffy bootstrap
-reffy doctor
-reffy reindex
-reffy validate
-reffy summarize
 ```
 
 Command summary:
@@ -33,6 +29,7 @@ Command summary:
 - `reffy reindex`: reconciles `.references/manifest.json` with `.references/artifacts` by adding missing files and removing stale entries.
 - `reffy validate`: validates `.references/manifest.json` against manifest v1 contract.
 - `reffy summarize`: generates a read-only handoff summary from indexed artifacts.
+- `reffy diagram render`: renders Mermaid diagrams as SVG or ASCII, including spec-aware generation from OpenSpec `spec.md`.
 
 Output modes:
 
@@ -49,6 +46,9 @@ reffy doctor --output text
 reffy doctor --output json
 reffy summarize --output text
 reffy summarize --output json
+reffy diagram render --stdin --format svg < diagram.mmd
+reffy diagram render --input openspec/specs/auth/spec.md --format ascii
+reffy diagram render --input openspec/specs/auth/spec.md --format svg --output .references/artifacts/auth-spec.svg
 ```
 
 ## Using Reffy With SDD Frameworks (OpenSpec Example)
@@ -85,3 +85,5 @@ npm run build
 npm run check
 npm test
 ```
+
+`npm install` runs this package's `prepare` step, which builds `dist/` automatically.

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { renderDiagram } from "./diagram.js";
 import { runDoctor } from "./doctor.js";
 import { ReferencesStore } from "./storage.js";
 import { summarizeArtifacts } from "./summarize.js";
@@ -200,8 +201,128 @@ function usage() {
         "  reindex    Scan .references/artifacts and add missing files to manifest.",
         "  validate   Validate .references/manifest.json against manifest v1 contract.",
         "  summarize  Generate a read-only summary of indexed Reffy artifacts.",
+        "  diagram    Render Mermaid diagrams (supports SVG and ASCII).",
     ].join("\n");
 }
+function diagramUsage() {
+    return [
+        "Usage: reffy diagram render [--repo PATH] [--input PATH|--stdin] [--format svg|ascii] [--output PATH]",
+        "",
+        "Options:",
+        "  --input PATH      Read Mermaid (or OpenSpec spec.md) from file",
+        "  --stdin           Read Mermaid text from stdin",
+        "  --format VALUE    Output format: svg (default) or ascii",
+        "  --output PATH     Write rendered result to file instead of stdout",
+        "  --theme NAME      Apply built-in SVG theme (beautiful-mermaid)",
+        "  --bg HEX          SVG color override for background",
+        "  --fg HEX          SVG color override for foreground",
+        "  --line HEX        SVG color override for connector lines",
+        "  --accent HEX      SVG color override for accents/arrowheads",
+        "  --muted HEX       SVG color override for secondary text",
+        "  --surface HEX     SVG color override for node surfaces",
+        "  --border HEX      SVG color override for node borders",
+        "  --font NAME       SVG font family override",
+    ].join("\n");
+}
+function parseDiagramArgs(argv) {
+    const repoRoot = parseRepoArg(argv);
+    const args = {
+        repoRoot,
+        stdin: false,
+        format: "svg",
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--repo") {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--repo="))
+            continue;
+        if (arg === "--stdin") {
+            args.stdin = true;
+            continue;
+        }
+        if (arg === "--input") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--input requires a path");
+            args.inputPath = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--input=")) {
+            const value = arg.split("=", 2)[1];
+            if (!value)
+                throw new Error("--input requires a path");
+            args.inputPath = value;
+            continue;
+        }
+        if (arg === "--output") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--output requires a path");
+            args.outputPath = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--output=")) {
+            const value = arg.split("=", 2)[1];
+            if (!value)
+                throw new Error("--output requires a path");
+            args.outputPath = value;
+            continue;
+        }
+        if (arg === "--format") {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error("--format requires a value: svg|ascii");
+            if (value !== "svg" && value !== "ascii")
+                throw new Error(`Unsupported format: ${value}. Valid formats: svg, ascii`);
+            args.format = value;
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--format=")) {
+            const value = arg.split("=", 2)[1];
+            if (value !== "svg" && value !== "ascii")
+                throw new Error(`Unsupported format: ${value}. Valid formats: svg, ascii`);
+            args.format = value;
+            continue;
+        }
+        const keyMap = {
+            "--theme": "theme",
+            "--bg": "bg",
+            "--fg": "fg",
+            "--line": "line",
+            "--accent": "accent",
+            "--muted": "muted",
+            "--surface": "surface",
+            "--border": "border",
+            "--font": "font",
+        };
+        const directKey = keyMap[arg];
+        if (directKey) {
+            const value = argv[i + 1];
+            if (!value)
+                throw new Error(`${arg} requires a value`);
+            args[directKey] = value;
+            i += 1;
+            continue;
+        }
+        const inline = Object.entries(keyMap).find(([flag]) => arg.startsWith(`${flag}=`));
+        if (inline) {
+            const [flag, key] = inline;
+            const value = arg.slice(flag.length + 1);
+            if (!value)
+                throw new Error(`${flag} requires a value`);
+            args[key] = value;
+            continue;
+        }
+        throw new Error(`Unknown diagram option: ${arg}`);
+    }
+    return args;
+}
 function printSection(title, values) {
     console.log(`${title}:`);
     if (values.length === 0) {
@@ -214,12 +335,50 @@ function printSection(title, values) {
 }
 async function main() {
     const [, , command, ...rest] = process.argv;
-    const output = parseOutputMode(rest);
-    printBanner(output);
     if (!command) {
         console.error(usage());
         return 1;
     }
+    if (command === "diagram") {
+        const [subcommand, ...diagramArgs] = rest;
+        if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+            console.error(diagramUsage());
+            return 1;
+        }
+        if (subcommand !== "render") {
+            console.error(`Unknown diagram subcommand: ${subcommand}`);
+            console.error(diagramUsage());
+            return 1;
+        }
+        const parsed = parseDiagramArgs(diagramArgs);
+        const rendered = await renderDiagram({
+            repoRoot: parsed.repoRoot,
+            inputPath: parsed.inputPath,
+            stdin: parsed.stdin,
+            format: parsed.format,
+            outputPath: parsed.outputPath,
+            theme: parsed.theme,
+            bg: parsed.bg,
+            fg: parsed.fg,
+            line: parsed.line,
+            accent: parsed.accent,
+            muted: parsed.muted,
+            surface: parsed.surface,
+            border: parsed.border,
+            font: parsed.font,
+        });
+        if (parsed.outputPath) {
+            console.log(`Wrote ${parsed.format} diagram to ${path.isAbsolute(parsed.outputPath) ? parsed.outputPath : path.join(parsed.repoRoot, parsed.outputPath)}`);
+            return 0;
+        }
+        process.stdout.write(rendered.content);
+        if (!rendered.content.endsWith("\n")) {
+            process.stdout.write("\n");
+        }
+        return 0;
+    }
+    const output = parseOutputMode(rest);
+    printBanner(output);
     if (command === "init") {
         const repoRoot = parseRepoArg(rest);
         const agents = await initAgents(repoRoot);

package/dist/diagram.d.ts

@@ -0,0 +1,21 @@
+export type DiagramFormat = "svg" | "ascii";
+export interface DiagramRenderRequest {
+    repoRoot: string;
+    inputPath?: string;
+    stdin?: boolean;
+    format: DiagramFormat;
+    outputPath?: string;
+    theme?: string;
+    bg?: string;
+    fg?: string;
+    line?: string;
+    accent?: string;
+    muted?: string;
+    surface?: string;
+    border?: string;
+    font?: string;
+}
+export declare function renderDiagram(request: DiagramRenderRequest): Promise<{
+    content: string;
+    source_kind: "mermaid" | "spec";
+}>;

package/dist/diagram.js

@@ -0,0 +1,110 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { THEMES, renderMermaid, renderMermaidAscii } from "beautiful-mermaid";
+function isLikelyOpenSpecDocument(inputPath, content) {
+    if (inputPath && path.basename(inputPath).toLowerCase() === "spec.md")
+        return true;
+    return /^### Requirement:\s+/m.test(content) && /^#### Scenario:\s+/m.test(content);
+}
+function toNodeId(prefix, index) {
+    return `${prefix}${String(index + 1)}`;
+}
+function sanitizeLabel(value) {
+    return value.replace(/"/g, "'").replace(/\s+/g, " ").trim();
+}
+function convertSpecToMermaid(specText) {
+    const requirementRegex = /^### Requirement:\s*(.+)$/gm;
+    const scenarioRegex = /^#### Scenario:\s*(.+)$/gm;
+    const requirements = Array.from(specText.matchAll(requirementRegex)).map((match) => ({
+        title: sanitizeLabel(match[1] ?? ""),
+        index: match.index ?? 0,
+    }));
+    if (requirements.length === 0) {
+        throw new Error("Unable to derive diagram from spec.md: no requirements found.");
+    }
+    const scenarios = Array.from(specText.matchAll(scenarioRegex)).map((match) => ({
+        title: sanitizeLabel(match[1] ?? ""),
+        index: match.index ?? 0,
+    }));
+    const lines = ["graph TD"];
+    let scenarioCursor = 0;
+    for (let i = 0; i < requirements.length; i += 1) {
+        const requirement = requirements[i];
+        const nextRequirementIndex = i + 1 < requirements.length ? requirements[i + 1]?.index ?? specText.length : specText.length;
+        const requirementId = toNodeId("R", i);
+        lines.push(`  ${requirementId}["Requirement: ${requirement.title}"]`);
+        while (scenarioCursor < scenarios.length) {
+            const scenario = scenarios[scenarioCursor];
+            if (scenario.index < requirement.index || scenario.index >= nextRequirementIndex) {
+                break;
+            }
+            const scenarioId = toNodeId("S", scenarioCursor);
+            lines.push(`  ${scenarioId}["Scenario: ${scenario.title}"]`);
+            lines.push(`  ${requirementId} --> ${scenarioId}`);
+            scenarioCursor += 1;
+        }
+    }
+    return lines.join("\n");
+}
+async function readStdinFully() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function loadSource(request) {
+    if (request.stdin && request.inputPath) {
+        throw new Error("Provide either --stdin or --input, not both.");
+    }
+    if (!request.stdin && !request.inputPath) {
+        throw new Error("Diagram input required: pass --stdin or --input <path>.");
+    }
+    const raw = request.stdin
+        ? await readStdinFully()
+        : await fs.readFile(path.isAbsolute(request.inputPath ?? "") ? request.inputPath : path.join(request.repoRoot, request.inputPath), "utf8");
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        throw new Error("Diagram input is empty.");
+    }
+    if (isLikelyOpenSpecDocument(request.inputPath, raw)) {
+        return { sourceText: convertSpecToMermaid(raw), sourceKind: "spec" };
+    }
+    return { sourceText: raw, sourceKind: "mermaid" };
+}
+function resolveSvgTheme(request) {
+    const options = {};
+    if (request.theme) {
+        const theme = THEMES[request.theme];
+        if (!theme) {
+            const validThemes = Object.keys(THEMES).sort().join(", ");
+            throw new Error(`Unsupported theme: ${request.theme}. Valid themes: ${validThemes}`);
+        }
+        Object.assign(options, theme);
+    }
+    const overrides = ["bg", "fg", "line", "accent", "muted", "surface", "border", "font"];
+    for (const key of overrides) {
+        const value = request[key];
+        if (typeof value === "string" && value.length > 0) {
+            options[key] = value;
+        }
+    }
+    return options;
+}
+export async function renderDiagram(request) {
+    const { sourceText, sourceKind } = await loadSource(request);
+    let content = "";
+    if (request.format === "ascii") {
+        content = renderMermaidAscii(sourceText);
+    }
+    else {
+        const svgOptions = resolveSvgTheme(request);
+        content = await renderMermaid(sourceText, svgOptions);
+    }
+    if (request.outputPath) {
+        const outPath = path.isAbsolute(request.outputPath) ? request.outputPath : path.join(request.repoRoot, request.outputPath);
+        await fs.mkdir(path.dirname(outPath), { recursive: true });
+        await fs.writeFile(outPath, content, "utf8");
+    }
+    return { content, source_kind: sourceKind };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reffy-cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "CLI-first, framework-agnostic references workflow for any repo (TypeScript)",
   "license": "MIT",
   "type": "module",
@@ -25,6 +25,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "beautiful-mermaid": "^0.1.3",
     "mime-types": "^2.1.35",
     "uuid": "^11.1.0"
   },