npm - raga-cli - Versions diffs - 0.0.0-stage → 0.9.0 - Mend

raga-cli 0.0.0-stage → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (487) hide show

package/bundled-skills/skills/raga-artifacts/SKILL.md ADDED Viewed

@@ -0,0 +1,117 @@
+---
+name: raga-artifacts
+description: Make shareable slides and documents for developers and clients, with Mermaid diagrams rendered by Pele, exported as a self-contained HTML file and a PDF. Use when the user asks for a deck, slides, a report, a proposal, a one-pager, or another polished document to share.
+---
+# Raga artifacts
+You make slides and documents the user can send to developers and clients. You write one static HTML source file. The builder renders its Mermaid diagrams to SVG with Pele, highlights code, inlines local images, and prints a PDF with headless Chrome. The results are `dist/<name>.html`, which works offline, and `dist/<name>.pdf`.
+## Load the helper
+Work in the Python tool:
+```python
+exec(await read("<directory of this SKILL.md>/artifact_tool.py"), globals())
+artifact_setup("<directory of this SKILL.md>")
+```
+## Steps
+1. **Ask what to make.** Ask the user, then wait for the answer:
+   - Slides or a document?
+   - Who reads it: developers, clients, or both?
+   - What should the reader know or decide at the end?
+   - Which material should it use: files, notes, or this conversation?
+   - Is there a theme or brand color?
+   If the user already answered these, do not ask again.
+2. **Outline.** Propose an outline: one line per slide, or one line per section. Wait for approval before you write the full artifact. Keep decks to 6 to 12 slides unless the user asks for more.
+3. **Start from a template.** Run `artifact_new("slides", "artifacts/<name>/<name>.html")` or `artifact_new("doc", ...)`. The default folder is `artifacts/` in the project. Use the template's markup and classes.
+4. **Write the content.** Edit the source file with the edit or write tools.
+5. **Build and look.** Run `result = await artifact_build(path, preview=True)`. If `result["ok"]` is false, fix every item in `problems` and build again. Fix every item in `layout`: each one is a slide or block that does not fit its page. Read every item in `warnings`. If your tools can show you images, open `result["preview"]` and fix crowded slides, unreadable diagrams, and awkward empty space. The Python REPL's `read` returns raw bytes for images, so in a REPL session rely on `layout` and ask the user to look at the PDF.
+6. **Hand it over.** Give the user the PDF path and the HTML path. Report the slide or page count and any warning you did not fix. Then offer the sharing options below.
+## Writing rules
+- Each slide makes one point, and its title states that point as a sentence. Use at most five bullets.
+- For clients, lead with the outcome and the decision you need. For developers, show the design, the trade-offs, and the code.
+- Prefer a diagram, a table, or one large number over a paragraph.
+- Do not invent numbers, quotes, logos, or customer names. Use only what the user or the project provides, and mark estimates as estimates.
+## Markup
+The templates define these pieces. Combine them instead of writing new CSS:
+| Markup | Use |
+|---|---|
+| `<section class="slide">` | One slide. Add `title`, `section`, or `statement` for those layouts. |
+| `<div class="kicker">` | Small label above a title |
+| `<div class="cols" style="--cols: 3">` | Columns. The default is 2. |
+| `<div class="card">` | A boxed group |
+| `<div class="stat"><div class="value">42%</div><div class="label">...</div></div>` | A large number |
+| `<div class="callout good">` | A highlighted note. Variants are `good`, `warn`, and `bad`. |
+| `<span class="tag">` | A small label |
+| `<pre class="mermaid">...</pre>` | A diagram in Mermaid syntax. Escape `<`, `>`, and `&` as `&lt;`, `&gt;`, and `&amp;`. |
+| `<pre><code class="language-ts">...</code></pre>` | Code, highlighted at build time |
+| `<img src="images/x.png">` | A local image, inlined at build time |
+| `<div class="footer">` | Slide footer |
+| `<div class="page-break">` | Start a new page in a document |
+Set the theme with `data-theme` on `<html>`. The values are `light`, `dark`, and `ink`. To use a brand color, change `--accent` and `--accent-soft` in the `:root` block. Diagrams take their colors from the same variables.
+## Diagrams
+Pele renders these 32 diagram types. Pick the type that fits the point, not always a flowchart. Before you write a type for the first time in a session, read its example in [diagrams.md](diagrams.md). Always do this for keywords that end in `-beta` and for `eventmodeling`, because their syntax is new.
+| Type | Keyword | Use for | Audience |
+|---|---|---|---|
+| Flowchart | `flowchart LR` | Processes, decisions, pipelines | both |
+| Sequence | `sequenceDiagram` | Requests between services or people over time | developers |
+| Class | `classDiagram` | Types, interfaces, and their relations | developers |
+| State | `stateDiagram-v2` | Lifecycles and state machines | developers |
+| Entity relationship | `erDiagram` | Database tables and relations | developers |
+| C4 | `C4Context` | System context, containers, components | both |
+| Architecture | `architecture-beta` | Cloud and service topology with groups and icons | both |
+| Block | `block` | Layered or grid layouts of components | developers |
+| Packet | `packet` | Bit and byte layouts of protocols or file formats | developers |
+| Git graph | `gitGraph` | Branching and release strategy | developers |
+| Agentflow | `agentflow-beta` | AI agent and tool-call workflows | developers |
+| Railroad | `railroad-ebnf-beta` | Grammar and syntax rules | developers |
+| Event modeling | `eventmodeling` | Commands, events, and views of an event-driven system | developers |
+| Requirement | `requirementDiagram` | Requirements and what satisfies or verifies them | both |
+| Gantt | `gantt` | Schedules with tasks and dependencies | clients |
+| Timeline | `timeline` | Milestones and history | clients |
+| Kanban | `kanban` | Work status by column | clients |
+| User journey | `journey` | Steps a user takes, with satisfaction scores | clients |
+| Mindmap | `mindmap` | Topics and ideas branching from one center | clients |
+| Use case | `usecase-beta` | Actors and what they can do | both |
+| Swimlane | `swimlane-beta` | A process split by team or role | clients |
+| Tree view | `treeView-beta` | File trees and hierarchies | developers |
+| Pie | `pie` | Parts of a whole, at most six slices | clients |
+| XY chart | `xychart` | Bar and line charts over a series | clients |
+| Quadrant chart | `quadrantChart` | Two-axis prioritization, such as effort against impact | clients |
+| Sankey | `sankey` | Flows of volume, money, or traffic between stages | clients |
+| Treemap | `treemap-beta` | Sizes of nested parts, such as cost or code by module | both |
+| Radar | `radar-beta` | Comparing options across several criteria | clients |
+| Venn | `venn-beta` | Overlap between groups | clients |
+| Ishikawa | `ishikawa-beta` | Root causes of a problem, fishbone style | both |
+| Cynefin | `cynefin-beta` | Sorting problems by how predictable they are | clients |
+| Wardley map | `wardley-beta` | Strategy: components by visibility and maturity | clients |
+Keep a slide diagram to about 15 nodes. If a diagram fails to build, the problem names the diagram number. Compare it with the example and fix the syntax.
+## Limits the builder enforces
+- No `<script>`, `<iframe>`, `<object>`, or `<embed>`. Artifacts are static so they print and share safely.
+- No remote images, stylesheets, or fonts. Download images next to the source. Fonts come from the reader's system: the theme lists Inter first and falls back to system fonts.
+- A slide whose content overflows its 1600 by 900 frame adds a PDF page. The builder warns when the page count differs from the slide count.
+## Sharing
+The PDF is the default deliverable. It opens everywhere and looks the same for every reader. The HTML file is a second copy for screens.
+Offer these only when the user asks for a link, and run any of them only after the user agrees, because each one publishes the file:
+- A secret GitHub gist: `gh gist create dist/<name>.html`. Anyone with the link can read it. GitHub shows HTML in a gist as source code, so readers must download the file to view it.
+- A static host the user already uses, such as GitHub Pages.

package/bundled-skills/skills/raga-artifacts/artifact.mjs ADDED Viewed

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * Build a self-contained artifact from an HTML source: render Mermaid blocks to SVG with Pele,
+ * highlight code, inline local images, check the layout, then print to PDF with headless Chrome.
+ *
+ *   node artifact.mjs build <source.html> [--out <dir>] [--no-pdf] [--preview]
+ *
+ * Prints one JSON object. Exit 1 lists every problem instead of producing a partial artifact.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { basename, delimiter, dirname, extname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+/**
+ * Pele and highlight.js are pinned dependencies of raga. Resolve them from this file first, which works
+ * for the bundled copy inside the raga package, then from the installed raga executable, which works
+ * for a copy in an instance revision.
+ */
+function packageRequires() {
+	const roots = [import.meta.url];
+	if (process.env.RAGA_PACKAGE_DIR) roots.push(pathToFileURL(join(process.env.RAGA_PACKAGE_DIR, "package.json")).href);
+	for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+		const raga = join(directory, "raga");
+		if (!existsSync(raga)) continue;
+		roots.push(pathToFileURL(realpathSync(raga)).href);
+	}
+	return roots.map((root) => createRequire(root));
+}
+function resolveDependency(name) {
+	for (const require of packageRequires()) {
+		try {
+			return require.resolve(name);
+		} catch {}
+	}
+	throw new Error(`Cannot find ${name}. Run the skill from a raga installation, or set RAGA_PACKAGE_DIR to the raga package directory.`);
+}
+const MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".svg": "image/svg+xml", ".webp": "image/webp" };
+const ENTITIES = { "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'", "&apos;": "'", "&nbsp;": " ", "&amp;": "&" };
+const decode = (text) => text.replace(/&(?:lt|gt|quot|#39|apos|nbsp|amp);/g, (entity) => ENTITIES[entity]);
+function chromePath() {
+	const candidates = [
+		process.env.CHROME_PATH,
+		"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+		"/Applications/Chromium.app/Contents/MacOS/Chromium",
+		"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+		"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+	];
+	for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+		for (const name of ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge"]) {
+			candidates.push(join(directory, name));
+		}
+	}
+	return candidates.find((path) => path && existsSync(path));
+}
+/** Run headless Chrome on a local file with a throwaway profile, so it never touches the user's browser. */
+function runChrome(chrome, htmlPath, outputPath, extraArgs) {
+	return chromeProcess(chrome, htmlPath, extraArgs).then(() => {
+		if (!existsSync(outputPath)) throw new Error(`Chrome did not write ${outputPath}`);
+	});
+}
+/** Run headless Chrome and return its standard output. */
+function runChromeOutput(chrome, htmlPath, extraArgs) {
+	return chromeProcess(chrome, htmlPath, extraArgs);
+}
+function chromeProcess(chrome, htmlPath, extraArgs) {
+	const profile = mkdtempSync(join(tmpdir(), "raga-artifact-chrome-"));
+	const args = [
+		"--headless=new",
+		"--disable-gpu",
+		"--no-first-run",
+		"--no-default-browser-check",
+		"--disable-extensions",
+		`--user-data-dir=${profile}`,
+		"--virtual-time-budget=5000",
+		...extraArgs,
+		pathToFileURL(htmlPath).href,
+	];
+	const { promise, resolve: done, reject } = Promise.withResolvers();
+	const child = spawn(chrome, args, { stdio: ["ignore", "pipe", "pipe"] });
+	let stdout = "";
+	let stderr = "";
+	child.stdout.on("data", (chunk) => {
+		if (stdout.length < 20_000_000) stdout += chunk;
+	});
+	child.stderr.on("data", (chunk) => {
+		if (stderr.length < 20000) stderr += chunk;
+	});
+	const timer = setTimeout(() => child.kill("SIGKILL"), 120000);
+	child.once("error", reject);
+	child.once("close", (code) => {
+		clearTimeout(timer);
+		rmSync(profile, { recursive: true, force: true });
+		if (code === 0) done(stdout);
+		else reject(new Error(`Chrome failed (exit ${code}). ${stderr.trim().slice(-2000)}`));
+	});
+	return promise;
+}
+/** Measure layout in Chrome: a slide whose content leaves its frame, or a wide block in a document. */
+async function checkLayout(chrome, htmlPath) {
+	const probe = `<script>addEventListener("load", () => {
+		const issues = [];
+		document.querySelectorAll("section.slide").forEach((slide, index) => {
+			const frame = slide.getBoundingClientRect();
+			let bottom = 0, right = 0;
+			for (const el of slide.querySelectorAll("*")) {
+				if (el.closest(".footer")) continue;
+				const rect = el.getBoundingClientRect();
+				if (!rect.width || !rect.height) continue;
+				bottom = Math.max(bottom, rect.bottom - frame.top);
+				right = Math.max(right, rect.right - frame.left);
+			}
+			const over = Math.round(Math.max(bottom - frame.height, right - frame.width, slide.scrollHeight - slide.clientHeight));
+			if (over > 1) issues.push("Slide " + (index + 1) + " overflows its frame by " + over + "px. Cut content or split the slide.");
+		});
+		document.querySelectorAll("main pre, main table, main figure, main img").forEach((el) => {
+			const over = el.scrollWidth - el.clientWidth;
+			if (over > 1) issues.push("A " + el.tagName.toLowerCase() + " is " + over + "px wider than the page. Shorten lines or narrow it.");
+		});
+		const out = document.createElement("pre");
+		out.id = "raga-layout";
+		out.textContent = JSON.stringify(issues);
+		document.body.append(out);
+	});</script>`;
+	const directory = mkdtempSync(join(tmpdir(), "raga-artifact-layout-"));
+	try {
+		const probePath = join(directory, "probe.html");
+		writeFileSync(probePath, readFileSync(htmlPath, "utf8").replace(/<\/body>/i, `${probe}</body>`));
+		const dom = await runChromeOutput(chrome, probePath, ["--window-size=1680,1000", "--dump-dom"]);
+		const match = /<pre id="raga-layout">([\s\S]*?)<\/pre>/.exec(dom);
+		return match ? JSON.parse(decode(match[1])) : ["The layout check did not finish."];
+	} finally {
+		rmSync(directory, { recursive: true, force: true });
+	}
+}
+/** Page count from the PDF's page tree. Chrome writes it uncompressed. */
+function pdfPages(pdfPath) {
+	const text = readFileSync(pdfPath).toString("latin1");
+	const counts = [...text.matchAll(/\/Type\s*\/Pages\b[^>]*?\/Count\s+(\d+)/g)].map((match) => Number(match[1]));
+	return counts.length ? Math.max(...counts) : undefined;
+}
+async function build(sourcePath, options) {
+	const source = readFileSync(sourcePath, "utf8");
+	const directory = dirname(sourcePath);
+	const problems = [];
+	const warnings = [];
+	if (/<script\b/i.test(source)) problems.push("Remove <script> elements. Artifacts are static so they print and share safely.");
+	if (/<(?:iframe|object|embed)\b/i.test(source)) problems.push("Remove <iframe>, <object>, and <embed> elements.");
+	if (/<link\b[^>]*href\s*=\s*["']https?:/i.test(source) || /url\(\s*["']?https?:/i.test(source))
+		problems.push("Remove remote stylesheets, fonts, and background images. The artifact must work offline.");
+	const { render, PeleError } = await import(pathToFileURL(resolveDependency("pele")).href);
+	const hljs = createRequire(import.meta.url)(resolveDependency("highlight.js"));
+	const font = /--font-sans\s*:\s*([^;]+);/.exec(source)?.[1]?.trim() ?? "sans-serif";
+	let diagrams = 0;
+	let html = source.replace(/<pre\b([^>]*\bclass\s*=\s*["'][^"']*\bmermaid\b[^"']*["'][^>]*)>([\s\S]*?)<\/pre>/gi, (_whole, _attrs, body) => {
+		diagrams++;
+		try {
+			return `<figure class="diagram">${render(decode(body).trim(), { fontFamily: font }).svg}</figure>`;
+		} catch (error) {
+			if (!(error instanceof PeleError)) throw error;
+			problems.push(`Diagram ${diagrams}: ${error.message}`);
+			return "";
+		}
+	});
+	let codeBlocks = 0;
+	html = html.replace(/<pre>\s*<code\b[^>]*\bclass\s*=\s*["'][^"']*\blanguage-([\w+-]+)[^"']*["'][^>]*>([\s\S]*?)<\/code>\s*<\/pre>/gi, (whole, language, body) => {
+		if (!hljs.getLanguage(language)) {
+			warnings.push(`Code block language "${language}" is unknown; left unhighlighted.`);
+			return whole;
+		}
+		codeBlocks++;
+		return `<pre class="code"><code class="hljs language-${language}">${hljs.highlight(decode(body), { language, ignoreIllegals: true }).value}</code></pre>`;
+	});
+	let images = 0;
+	html = html.replace(/(<img\b[^>]*\bsrc\s*=\s*)(["'])([^"']+)\2/gi, (whole, prefix, quote, src) => {
+		if (src.startsWith("data:")) return whole;
+		if (/^[a-z][a-z0-9+.-]*:/i.test(src)) {
+			problems.push(`Image ${src} is remote. Download it next to the source and use a relative path.`);
+			return whole;
+		}
+		const file = resolve(directory, decode(src));
+		const mime = MIME[extname(file).toLowerCase()];
+		if (!mime || !existsSync(file) || !statSync(file).isFile()) {
+			problems.push(`Image ${src} is missing or not a PNG, JPEG, GIF, SVG, or WebP file.`);
+			return whole;
+		}
+		images++;
+		return `${prefix}${quote}data:${mime};base64,${readFileSync(file).toString("base64")}${quote}`;
+	});
+	const slides = (html.match(/<section\b[^>]*\bclass\s*=\s*["'][^"']*\bslide\b/gi) ?? []).length;
+	if (problems.length) return { ok: false, problems, warnings };
+	const outDir = resolve(options.out ?? join(directory, "dist"));
+	mkdirSync(outDir, { recursive: true });
+	const name = basename(sourcePath).replace(/\.html?$/i, "");
+	const htmlPath = join(outDir, `${name}.html`);
+	writeFileSync(htmlPath, html);
+	const result = { ok: true, html: htmlPath, diagrams, codeBlocks, images, slides, warnings };
+	if (!options.pdf && !options.preview) return result;
+	const chrome = chromePath();
+	if (!chrome) return { ...result, ok: false, problems: ["No Chrome, Chromium, Edge, or Brave found. Install one or set CHROME_PATH."] };
+	result.layout = await checkLayout(chrome, htmlPath);
+	if (options.preview) {
+		// Screen layout: slides stack 900px frames with 40px gaps inside 40px padding; a document gets its first pages.
+		const size = slides ? `1680,${slides * 940 + 80}` : "900,3600";
+		const previewPath = join(outDir, `${name}.png`);
+		rmSync(previewPath, { force: true });
+		await runChrome(chrome, htmlPath, previewPath, ["--hide-scrollbars", `--window-size=${size}`, `--screenshot=${previewPath}`]);
+		result.preview = previewPath;
+	}
+	if (!options.pdf) return result;
+	const pdfPath = join(outDir, `${name}.pdf`);
+	rmSync(pdfPath, { force: true });
+	await runChrome(chrome, htmlPath, pdfPath, ["--no-pdf-header-footer", "--print-to-pdf-no-header", `--print-to-pdf=${pdfPath}`]);
+	const pages = pdfPages(pdfPath);
+	if (slides && pages !== undefined && pages !== slides)
+		warnings.push(`The PDF has ${pages} pages for ${slides} slides. A slide overflows its page; shorten it or split it.`);
+	return { ...result, pdf: pdfPath, pages };
+}
+const [command, sourceArg, ...rest] = process.argv.slice(2);
+if (command !== "build" || !sourceArg) {
+	console.error("Usage: node artifact.mjs build <source.html> [--out <dir>] [--no-pdf] [--preview]");
+	process.exit(2);
+}
+const outIndex = rest.indexOf("--out");
+try {
+	const result = await build(resolve(sourceArg), {
+		out: outIndex >= 0 ? rest[outIndex + 1] : undefined,
+		pdf: !rest.includes("--no-pdf"),
+		preview: rest.includes("--preview"),
+	});
+	console.log(JSON.stringify(result, null, 2));
+	process.exit(result.ok ? 0 : 1);
+} catch (error) {
+	console.log(JSON.stringify({ ok: false, problems: [error instanceof Error ? error.message : String(error)], warnings: [] }, null, 2));
+	process.exit(1);
+}

package/bundled-skills/skills/raga-artifacts/artifact_tool.py ADDED Viewed

@@ -0,0 +1,55 @@
+"""Artifact helpers for the raga Python REPL. Load with exec(await read(path), globals()), then call artifact_setup."""
+import json
+import os
+import shlex
+import shutil
+ARTIFACT_SKILL_DIR = None
+def artifact_setup(skill_dir):
+    """Remember where this skill lives so the other helpers find the builder and templates."""
+    global ARTIFACT_SKILL_DIR
+    ARTIFACT_SKILL_DIR = os.path.abspath(skill_dir)
+def _skill(path):
+    if ARTIFACT_SKILL_DIR is None:
+        raise RuntimeError("Call artifact_setup(<directory of the raga-artifacts SKILL.md>) first")
+    return os.path.join(ARTIFACT_SKILL_DIR, path)
+def artifact_new(kind, path):
+    """Copy the slides or doc template to path. Refuses to overwrite an existing file."""
+    if kind not in ("slides", "doc"):
+        raise ValueError('kind must be "slides" or "doc"')
+    path = os.path.abspath(path)
+    if os.path.exists(path):
+        raise FileExistsError(path + " exists. Edit it, or choose another path")
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    shutil.copyfile(_skill(os.path.join("templates", kind + ".html")), path)
+    return path
+async def artifact_build(source, pdf=True, preview=False, out=None):
+    """Build source into dist/<name>.html and, by default, dist/<name>.pdf. Returns the builder's JSON.
+    ok is False with a problems list when a diagram fails, the source has scripts or remote assets,
+    or no browser is found. preview=True also writes dist/<name>.png for a visual check.
+    """
+    command = "node " + shlex.quote(_skill("artifact.mjs")) + " build " + shlex.quote(os.path.abspath(source))
+    if out:
+        command += " --out " + shlex.quote(os.path.abspath(out))
+    if not pdf:
+        command += " --no-pdf"
+    if preview:
+        command += " --preview"
+    runner = globals().get("bash")
+    if runner is None:
+        raise RuntimeError("artifact_build runs in the raga Python REPL, where bash is available")
+    output = await runner(command + " 2>&1; true", timeout=300)
+    start = output.find("{")
+    if start < 0:
+        return {"ok": False, "problems": [output.strip()], "warnings": []}
+    return json.loads(output[start:])