@diagent/cli 0.1.0

package/README.md

@@ -0,0 +1,210 @@
+## @diagent/cli
+
+Command-line tool to encode and decode Diagent shareable flowchart URLs.
+Designed for agents (Claude Code, Cursor) and humans alike.
+
+By default, `diagent encode` produces a **short URL** like
+`https://diagent.dev/d/abcdefghij` (~31 chars, constant size regardless
+of diagram complexity). This works by calling the Diagent backend's
+`POST /api/s` endpoint, which stores the Mermaid in Cloudflare KV and
+returns a content-addressed short ID.
+
+If the backend is unreachable (dev, offline, rate-limit, Cloudflare
+outage), `diagent encode` **automatically falls back** to an inline URL
+of the form `https://diagent.dev/?code=<lz-compressed>`, which carries
+the full Mermaid source in the `code` query parameter. The feature
+never fully breaks — worst case, you get a longer URL and a stderr
+notice. Pass `--inline` to skip the backend entirely and always produce
+the inline format.
+
+### Install
+
+**From npm:**
+
+```bash
+npx -y @diagent/cli --help
+# or install globally
+npm install -g @diagent/cli
+```
+
+**From source (contributors):**
+
+```bash
+cd cli
+npm install
+npm run build
+npm link     # puts `diagent` on your global PATH
+```
+
+### Usage
+
+```
+diagent encode [FILE] [--base-url URL] [--inline]
+                                          Encode Mermaid from FILE or stdin -> URL on stdout
+                                          (tries backend short URL, falls back to inline)
+diagent decode <URL>                      Decode inline ?code= URL -> Mermaid source on stdout
+diagent decode -                          Decode URL read from stdin
+diagent --help                            Show help
+diagent --version                         Show version
+```
+
+**Encode from stdin (produces a short URL):**
+
+```bash
+cat flow.mmd | diagent encode
+# https://diagent.dev/d/kwtsgx5o24
+```
+
+**Encode from a file:**
+
+```bash
+diagent encode flow.mmd
+```
+
+**Force inline format (skip backend):**
+
+```bash
+diagent encode flow.mmd --inline
+# https://diagent.dev/?code=GYGw9g7gxg...
+```
+
+**Encode against a local dev server:**
+
+```bash
+diagent encode flow.mmd --base-url http://localhost:5173/
+```
+
+**Decode a short URL or inline URL (both work):**
+
+```bash
+# Short URL — diagent follows the 302 internally
+diagent decode "https://diagent.dev/d/kwtsgx5o24"
+# flowchart TD
+#     A["Hello"]
+#     B["World"]
+#     A --> B
+
+# Inline URL
+diagent decode "https://diagent.dev/?code=GYGw9g7gxgFghgJwC4AIAqARAUC3KCCA..."
+
+# From stdin — avoids shell-quoting pain for long URLs
+echo "$URL" | diagent decode -
+```
+
+`diagent decode` transparently handles both URL formats. For `/d/:id`
+short URLs it sends a HEAD request (3s timeout), reads the `Location`
+header, and extracts `?code=` from the redirect target. The CLI user
+never has to know which format they have.
+
+### Agent workflow
+
+Once `diagent` is on your agent's `$PATH`, no per-agent configuration is
+required. The agent invokes it via its shell/Bash tool:
+
+```bash
+# Agent shares a diagram it authored — short URL by default
+echo 'flowchart TD
+    A[Start] --> B[End]' | diagent encode
+# -> https://diagent.dev/d/abcdefghij
+
+# Agent reads a URL the user pasted — works for both short and inline
+diagent decode "https://diagent.dev/d/abcdefghij"
+diagent decode "https://diagent.dev/?code=..."
+```
+
+Short URLs are legible in chat, dramatically shorter than the inline
+format, and unbounded in diagram complexity. The agent never sees or
+handles the `lz-string` format — the backend takes care of it.
+
+No MCP server, no SDK, no per-user `.mcp.json` — just a CLI on PATH.
+For stateless operations like these, a CLI is strictly simpler than an
+MCP server and works in any environment with shell access.
+
+### Claude Code Skill (auto-discovery)
+
+Without priming, Claude Code doesn't know about `diagent` — it's a new
+tool that isn't in training data. To teach every Claude Code session
+across every project about this CLI, install the bundled Skill:
+
+```bash
+mkdir -p ~/.claude/skills/diagent
+curl -o ~/.claude/skills/diagent/SKILL.md \
+  https://raw.githubusercontent.com/daniellee-ux/Diagent/main/.claude/skills/diagent/SKILL.md
+```
+
+The skill uses `npx -y @diagent/cli` internally, so the CLI auto-downloads
+on first use — no `npm link` or build step required.
+
+Or, if you have the repo cloned and want auto-updating via symlink:
+
+```bash
+mkdir -p ~/.claude/skills
+ln -sfn /path/to/Diagent/.claude/skills/diagent ~/.claude/skills/diagent
+```
+
+Once installed, a fresh Claude Code session in any project will
+recognize phrases like "draw me a flowchart" or "diagram the login
+flow" and invoke the CLI without needing to be told it exists. Test it:
+
+```text
+You: Can you draw me a flowchart of how this login handler works?
+
+Claude: [reads the handler, runs `npx -y @diagent/cli encode` on a generated Mermaid]
+        Here's the diagram: https://diagent.dev/d/...
+```
+
+If Claude still says "I don't have a diagent CLI available," verify
+the skill file: `ls -la ~/.claude/skills/diagent/SKILL.md`. A full Claude
+Code restart may be needed to pick up newly-installed skills.
+
+### Environment
+
+| Variable | Default | Description |
+|---|---|---|
+| `DIAGENT_BASE_URL` | `https://diagent.dev/` | Base URL for both `POST /api/s` and inline URL construction. Override with `--base-url` flag for per-invocation. |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success (includes fallback-to-inline path) |
+| 1 | Runtime error (empty input, invalid URL, corrupt code param, too large, file not found) |
+| 2 | Usage error (unknown subcommand, missing required argument) |
+
+When encode falls back from short URL to inline URL due to backend
+unavailability, it still returns exit 0 — the operation succeeded,
+just in a degraded form. The stderr notice `backend unreachable,
+using inline URL` is the signal.
+
+### Format parity with the web app
+
+The CLI and the browser's **Copy Link** button produce byte-identical
+output for the same Mermaid source and base URL — both short URLs
+(from the Worker) and inline fallback URLs (from `lz-string`). The CLI
+uses the same compression, the same `?code=` query-param convention,
+and the same `/d/:id` shape as the browser.
+
+This means you can:
+- Generate a short URL via CLI, open it in the browser — the diagram loads.
+- Click **Copy Link** in the browser, `diagent decode` the inline form
+  (after following the redirect) — the source comes back exactly as the
+  browser serialized it.
+
+### Local dev workflow
+
+To test the CLI against a local Worker instead of production, run one
+dev server that hosts both the SPA and the Worker:
+
+```bash
+# Terminal 1 — Vite dev server runs the Worker via @cloudflare/vite-plugin
+npm run dev                              # http://localhost:5173
+
+# Terminal 2 (or wherever you invoke diagent)
+echo 'flowchart TD\n    A --> B' | diagent encode --base-url http://localhost:5173/
+# -> http://localhost:5173/d/abcdefghij
+```
+
+The `@cloudflare/vite-plugin` makes Vite's dev server execute the Worker
+script natively, so `/api/*` and `/d/*` requests are handled on port 5173
+without a separate `wrangler dev` process or proxy. Production
+`wrangler deploy` is unaffected.

package/build/cli.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { exec } from 'node:child_process';
+import { resolveMermaidFromUrl, shortenOrInline, DEFAULT_BASE_URL, } from './core.js';
+const HELP = `diagent — encode and decode Diagent shareable flowchart URLs
+
+Usage:
+  diagent encode [FILE] [--base-url URL] [--inline] [--open]
+                                           Encode Mermaid from FILE or stdin → URL on stdout
+                                           (tries backend short URL, falls back to inline on failure)
+  diagent decode <URL>                      Decode short /d/:id OR inline ?code= URL → Mermaid on stdout
+  diagent decode -                          Decode URL read from stdin
+  diagent --help                            Show this help
+  diagent --version                         Show version
+
+Options:
+  --inline        Skip the backend and always produce an inline ?code= URL
+  --open          Open the generated URL in the default browser
+  --base-url URL  Diagent origin for both backend calls and URL construction
+                  (default: ${DEFAULT_BASE_URL})
+
+Examples:
+  cat flow.mmd | diagent encode
+  diagent encode flow.mmd
+  diagent encode flow.mmd --base-url http://localhost:5173/
+  diagent encode flow.mmd --inline
+  diagent decode "https://diagent.dev/d/abcdefghij"
+  diagent decode "https://diagent.dev/?code=GYGw9g7gxg..."
+
+Environment:
+  DIAGENT_BASE_URL   Default base URL for encode (default: ${DEFAULT_BASE_URL})
+`;
+async function readStdin() {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    for await (const chunk of process.stdin)
+        data += chunk;
+    return data;
+}
+async function runEncode(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: {
+            'base-url': { type: 'string' },
+            inline: { type: 'boolean' },
+            open: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    const file = positionals[0];
+    const mermaid = file ? await readFile(file, 'utf8') : await readStdin();
+    const baseUrl = values['base-url'] ?? DEFAULT_BASE_URL;
+    const preferInline = values.inline === true;
+    const { result, usedFallback } = await shortenOrInline(mermaid, baseUrl, preferInline);
+    if (!result.ok) {
+        process.stderr.write(`diagent: ${result.error}\n`);
+        return 1;
+    }
+    if (usedFallback && !preferInline) {
+        process.stderr.write('diagent: backend unreachable, using inline URL\n');
+    }
+    process.stdout.write(result.url + '\n');
+    if (values.open) {
+        const cmd = process.platform === 'darwin' ? 'open' :
+            process.platform === 'win32' ? 'start' : 'xdg-open';
+        exec(`${cmd} ${JSON.stringify(result.url)}`);
+    }
+    return 0;
+}
+async function runDecode(args) {
+    const { values, positionals } = parseArgs({
+        args,
+        options: { help: { type: 'boolean', short: 'h' } },
+        allowPositionals: true,
+    });
+    if (values.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    let url = positionals[0];
+    if (!url) {
+        process.stderr.write('diagent decode: missing URL argument (pass URL or "-" for stdin)\n');
+        return 2;
+    }
+    if (url === '-')
+        url = (await readStdin()).trim();
+    const result = await resolveMermaidFromUrl(url);
+    if (!result.ok) {
+        process.stderr.write(`diagent: could not decode URL — ${result.error}\n`);
+        return 1;
+    }
+    const mermaid = result.mermaid;
+    process.stdout.write(mermaid + (mermaid.endsWith('\n') ? '' : '\n'));
+    return 0;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (argv[0] === '--version' || argv[0] === '-v') {
+        const pkg = await readFile(new URL('../package.json', import.meta.url), 'utf8');
+        process.stdout.write(JSON.parse(pkg).version + '\n');
+        return 0;
+    }
+    const [sub, ...rest] = argv;
+    switch (sub) {
+        case 'encode':
+            return runEncode(rest);
+        case 'decode':
+            return runDecode(rest);
+        default:
+            process.stderr.write(`diagent: unknown subcommand "${sub}"\n${HELP}`);
+            return 2;
+    }
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    process.stderr.write(`diagent: ${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+});

package/build/core.js

@@ -0,0 +1,176 @@
+import LZString from 'lz-string';
+export const URL_CODE_PARAM = 'code';
+export const MAX_URL_LENGTH = 8000;
+export const DEFAULT_BASE_URL = process.env.DIAGENT_BASE_URL ?? 'https://diagent.dev/';
+/** Matches a `/d/<10 base32 chars>` short URL path. */
+const SHORT_URL_PATH_RE = /^\/d\/[a-z2-7]{10}$/;
+export function buildShareableUrl(mermaid, baseUrl = DEFAULT_BASE_URL) {
+    if (!mermaid || !mermaid.trim()) {
+        return { ok: false, error: 'Nothing to encode' };
+    }
+    const encoded = LZString.compressToEncodedURIComponent(mermaid);
+    const normalized = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+    const url = `${normalized}?${URL_CODE_PARAM}=${encoded}`;
+    if (url.length > MAX_URL_LENGTH) {
+        return {
+            ok: false,
+            error: `Diagram too large for URL (${url.length} > ${MAX_URL_LENGTH} chars)`,
+        };
+    }
+    return { ok: true, url };
+}
+export function extractMermaidFromUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const raw = parsed.searchParams.get(URL_CODE_PARAM);
+    if (!raw)
+        return null;
+    const decoded = LZString.decompressFromEncodedURIComponent(raw);
+    return decoded || null;
+}
+/**
+ * Try to shorten a Mermaid source via the backend (`POST {baseUrl}api/s`).
+ * Returns a short URL on success, or an error result on any failure
+ * (network, 3s timeout, non-2xx). Retries once after a 500ms delay to
+ * absorb cold-start hiccups and transient 5xxs from Cloudflare Workers.
+ * Callers should fall back to `buildShareableUrl` for the inline format.
+ */
+export async function shortenViaBackend(mermaid, baseUrl = DEFAULT_BASE_URL) {
+    if (!mermaid || !mermaid.trim()) {
+        return { ok: false, error: 'Nothing to encode' };
+    }
+    const normalized = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+    const apiUrl = `${normalized}api/s`;
+    const attempt = async () => {
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 3000);
+            const res = await fetch(apiUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'text/plain' },
+                body: mermaid,
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!res.ok)
+                return { ok: false, error: `backend ${res.status}` };
+            const data = (await res.json());
+            if (!data?.url)
+                return { ok: false, error: 'malformed backend response' };
+            return { ok: true, url: data.url };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: err instanceof Error ? err.message : 'network error',
+            };
+        }
+    };
+    const first = await attempt();
+    if (first.ok)
+        return first;
+    // Retry once after a short delay — first-call cold starts and
+    // transient 5xxs are common on Cloudflare Workers free tier.
+    await new Promise((r) => setTimeout(r, 500));
+    return attempt();
+}
+/**
+ * Resolve any Diagent URL (inline `?code=` OR short `/d/<id>`) to its
+ * underlying Mermaid source. For inline URLs this is a synchronous
+ * extraction. For short URLs this HEADs the URL to follow the 302 Location
+ * header, then extracts `?code=` from the redirect target. 3s timeout;
+ * fails fast with a typed error result.
+ */
+export async function resolveMermaidFromUrl(url) {
+    // Fast path: inline ?code= URLs don't need a network call.
+    const direct = extractMermaidFromUrl(url);
+    if (direct)
+        return { ok: true, mermaid: direct };
+    // Parse the URL to check for the /d/<id> short-URL shape.
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, error: 'not a valid URL' };
+    }
+    if (!SHORT_URL_PATH_RE.test(parsed.pathname)) {
+        return {
+            ok: false,
+            error: 'URL has no ?code= param and is not a /d/<id> short URL',
+        };
+    }
+    // Follow the 302 to pull the underlying inline URL, then recurse.
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3000);
+        const res = await fetch(url, {
+            method: 'HEAD',
+            redirect: 'manual',
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (res.status !== 302) {
+            return {
+                ok: false,
+                error: `backend returned ${res.status}, expected 302`,
+            };
+        }
+        const location = res.headers.get('location');
+        if (!location) {
+            return { ok: false, error: 'backend 302 missing Location header' };
+        }
+        // Worker redirects a missing /d/:id to /?notfound=:id so both
+        // browser and CLI get a structured signal. Surface a specific,
+        // user-friendly error that the agent can relay verbatim.
+        try {
+            const locUrl = new URL(location, parsed.origin);
+            const nfId = locUrl.searchParams.get('notfound');
+            if (nfId) {
+                return {
+                    ok: false,
+                    error: `short URL /d/${nfId} was not found (may have been deleted or never existed)`,
+                };
+            }
+        }
+        catch {
+            // Fall through to the existing decode path; if the Location is
+            // malformed, extractMermaidFromUrl will return its own error.
+        }
+        const decoded = extractMermaidFromUrl(location);
+        if (!decoded) {
+            return {
+                ok: false,
+                error: 'redirect target has no valid ?code= param',
+            };
+        }
+        return { ok: true, mermaid: decoded };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : 'network error',
+        };
+    }
+}
+/**
+ * Primary encode entry point: tries the backend first (unless preferInline
+ * is set), falls back to inline URL on failure. The caller gets both the
+ * result and a flag indicating which path produced it.
+ */
+export async function shortenOrInline(mermaid, baseUrl = DEFAULT_BASE_URL, preferInline = false) {
+    if (!preferInline) {
+        const short = await shortenViaBackend(mermaid, baseUrl);
+        if (short.ok)
+            return { result: short, usedFallback: false };
+    }
+    return {
+        result: buildShareableUrl(mermaid, baseUrl),
+        usedFallback: !preferInline,
+    };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@diagent/cli",
+  "version": "0.1.0",
+  "description": "Encode and decode Diagent shareable flowchart URLs from the command line. Designed for agents (Claude Code, Cursor) and humans.",
+  "type": "module",
+  "bin": {
+    "diagent": "./build/cli.js"
+  },
+  "files": [
+    "build/cli.js",
+    "build/core.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/daniellee-ux/Diagent.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/daniellee-ux/Diagent/tree/main/cli#readme",
+  "keywords": ["mermaid", "diagram", "flowchart", "cli", "agent", "claude-code"],
+  "scripts": {
+    "build": "tsc && chmod +x build/cli.js",
+    "start": "node build/cli.js",
+    "test": "node --test build/core.test.js"
+  },
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "dependencies": {
+    "lz-string": "^1.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "typescript": "~6.0.2"
+  }
+}