deepclause-pi 0.1.4 → 0.2.0

package/dist/diagram/grade.d.ts

@@ -0,0 +1,41 @@
+import type { CheckResult, MermaidView } from "./validate.js";
+export type DiagramGrade = "presentation" | "specification";
+export type RequestedGrade = DiagramGrade | "both";
+export declare const GRADE_SYSTEM_PROMPT = "You are a meticulous Mermaid v11 diagram editor. You output only valid Mermaid source, never wrapped in code fences, and you keep all facts accurate.";
+export declare const GRADE_PROMPTS: Record<DiagramGrade, string>;
+/**
+ * Map free-form user/tool wording onto a supported grade. Returns undefined when
+ * nothing matches so the caller can apply its default.
+ */
+export declare function resolveGrade(text: string): RequestedGrade | undefined;
+export declare function stripFences(raw: string): string;
+export interface CompleteOptions {
+    systemPrompt: string;
+    prompt: string;
+    maxTokens: number;
+    signal?: AbortSignal;
+}
+export interface PolishOptions {
+    grade: DiagramGrade;
+    view: MermaidView;
+    source: string;
+    seed: string;
+    maxTokens: number;
+    maxRounds?: number;
+    signal?: AbortSignal;
+    complete: (options: CompleteOptions) => Promise<{
+        text: string;
+    }>;
+    validate: (code: string) => Promise<CheckResult>;
+    onProgress?: (message: string) => void;
+}
+export interface PolishResult {
+    code: string;
+    rounds: number;
+}
+/**
+ * Ask the active pi model to rewrite the deterministic seed in the requested
+ * grade, validating each attempt and feeding failures back until it parses or
+ * the round budget is exhausted.
+ */
+export declare function polishDiagram(options: PolishOptions): Promise<PolishResult>;

package/dist/diagram/grade.js

@@ -0,0 +1,70 @@
+export const GRADE_SYSTEM_PROMPT = "You are a meticulous Mermaid v11 diagram editor. You output only valid Mermaid source, never wrapped in code fences, and you keep all facts accurate.";
+export const GRADE_PROMPTS = {
+    presentation: "Produce a PRESENTATION-GRADE version: about 8-12 nodes, plain non-technical language, NO function names or framework jargon, highlight the headline numbers and the main steps, and add 1-2 short callouts. Keep it accurate but simple enough for a general audience.",
+    specification: "Produce a SPECIFICATION-GRADE (detailed engineering) version: keep the technical detail (function names, task/tool roles, post-conditions, seed data), but improve labels, grouping and readability so an engineer can follow it precisely.",
+};
+/**
+ * Map free-form user/tool wording onto a supported grade. Returns undefined when
+ * nothing matches so the caller can apply its default.
+ */
+export function resolveGrade(text) {
+    const value = text.toLowerCase();
+    if (/\bboth\b/.test(value))
+        return "both";
+    if (/(specification|spec\b|detailed|technical|engineering|developer)/.test(value))
+        return "specification";
+    if (/(presentation|present|simple|executive|slide|high[- ]level|overview)/.test(value))
+        return "presentation";
+    return undefined;
+}
+export function stripFences(raw) {
+    return raw
+        .split("\n")
+        .filter((line) => !line.trimStart().startsWith("```"))
+        .join("\n")
+        .trim();
+}
+function buildPrompt(grade, view, source, seed, feedback) {
+    const syntax = view === "sequence" ? "sequenceDiagram" : "flowchart TD";
+    return [
+        GRADE_PROMPTS[grade],
+        "",
+        `Rules: output ONLY Mermaid v11 source (no code fences); keep it a '${syntax}' diagram; keep the facts accurate; do not use reserved words such as 'end' as node ids or class names.`,
+        "",
+        "DML source:",
+        source,
+        "",
+        "Current diagram:",
+        seed,
+        "",
+        feedback,
+    ].join("\n");
+}
+/**
+ * Ask the active pi model to rewrite the deterministic seed in the requested
+ * grade, validating each attempt and feeding failures back until it parses or
+ * the round budget is exhausted.
+ */
+export async function polishDiagram(options) {
+    const maxRounds = Math.max(1, Math.min(options.maxRounds ?? 3, 6));
+    let feedback = `This is the first attempt at the ${options.grade} grade.`;
+    for (let round = 1; round <= maxRounds; round++) {
+        options.onProgress?.(`Generating ${options.grade} diagram (attempt ${round}/${maxRounds})…`);
+        const response = await options.complete({
+            systemPrompt: GRADE_SYSTEM_PROMPT,
+            prompt: buildPrompt(options.grade, options.view, options.source, options.seed, feedback),
+            maxTokens: options.maxTokens,
+            signal: options.signal,
+        });
+        const candidate = stripFences(response.text);
+        if (!candidate) {
+            feedback = "Your previous attempt was empty. Return only Mermaid source.";
+            continue;
+        }
+        const check = await options.validate(candidate);
+        if (check.ok)
+            return { code: candidate, rounds: round };
+        feedback = `Your previous attempt failed validation: ${check.error}. Fix exactly that and return only Mermaid source.`;
+    }
+    throw new Error(`Could not produce a valid ${options.grade} diagram after ${maxRounds} attempts (${feedback})`);
+}

package/dist/diagram/validate.d.ts

@@ -0,0 +1,36 @@
+export type MermaidView = "flow" | "sequence";
+export interface CheckResult {
+    ok: boolean;
+    error?: string;
+}
+export interface CommandResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+    killed: boolean;
+}
+export type RunCommand = (command: string, args: string[], options?: {
+    timeout?: number;
+}) => Promise<CommandResult>;
+/**
+ * Cheap, dependency-free validation that catches the failure modes we care
+ * about: wrong diagram type, unbalanced blocks, unbalanced quotes, reserved
+ * node names, and absurdly large output. It cannot prove Mermaid correctness.
+ */
+export declare function structuralCheck(code: string, view: MermaidView): CheckResult;
+export declare function findChrome(run: RunCommand): Promise<string | undefined>;
+export declare function chromeMermaidCheck(code: string, chrome: string, vendorDir: string, run: RunCommand): Promise<CheckResult>;
+export interface ValidateOptions {
+    run?: RunCommand;
+    vendorDir?: string;
+    chrome?: string | null;
+}
+export interface ValidationOutcome {
+    result: CheckResult;
+    gate: "structural" | "chrome";
+}
+/**
+ * Structural check always runs. When a Chrome binary and a vendored Mermaid
+ * copy are available, the real Mermaid parser is used as a second gate.
+ */
+export declare function validateMermaid(code: string, view: MermaidView, options?: ValidateOptions): Promise<ValidationOutcome>;

package/dist/diagram/validate.js

@@ -0,0 +1,148 @@
+import { access, rm, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+const CHROME_CANDIDATES = [
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium",
+    "chromium-browser",
+    "brave-browser",
+];
+const SEQUENCE_OPENERS = /^\s*(?:alt|loop|opt|par|critical|break|rect|box)\b/gm;
+const FLOW_OPENERS = /^\s*subgraph\b/gm;
+const CLOSERS = /^\s*end\s*$/gm;
+function countMatches(source, pattern) {
+    pattern.lastIndex = 0;
+    let count = 0;
+    while (pattern.exec(source))
+        count++;
+    return count;
+}
+/**
+ * Cheap, dependency-free validation that catches the failure modes we care
+ * about: wrong diagram type, unbalanced blocks, unbalanced quotes, reserved
+ * node names, and absurdly large output. It cannot prove Mermaid correctness.
+ */
+export function structuralCheck(code, view) {
+    const trimmed = code.trim();
+    if (!trimmed)
+        return { ok: false, error: "the diagram is empty" };
+    const lines = trimmed.split("\n");
+    const header = (lines[0] ?? "").trim();
+    if (view === "sequence") {
+        if (!/^sequenceDiagram\b/.test(header)) {
+            return { ok: false, error: "expected a 'sequenceDiagram' header" };
+        }
+    }
+    else if (!/^(?:flowchart|graph)\b/.test(header)) {
+        return { ok: false, error: "expected a 'flowchart' or 'graph' header" };
+    }
+    if (trimmed.length > 200_000)
+        return { ok: false, error: "the diagram is too large" };
+    if (lines.length > 5_000)
+        return { ok: false, error: "the diagram has too many lines" };
+    if (((trimmed.match(/"/g) ?? []).length) % 2 !== 0) {
+        return { ok: false, error: "unbalanced double quotes" };
+    }
+    if (view === "flow" && /^\s*end\s*[\[\(\{]/m.test(trimmed)) {
+        return { ok: false, error: "'end' cannot be used as a node id" };
+    }
+    const openers = countMatches(trimmed, view === "sequence" ? SEQUENCE_OPENERS : FLOW_OPENERS);
+    const closers = countMatches(trimmed, CLOSERS);
+    if (openers !== closers) {
+        return { ok: false, error: `unbalanced blocks: ${openers} opener(s) but ${closers} 'end' line(s)` };
+    }
+    return { ok: true };
+}
+export async function findChrome(run) {
+    const envPath = process.env.CHROME_PATH;
+    if (envPath) {
+        try {
+            await access(envPath, constants.X_OK);
+            return envPath;
+        }
+        catch {
+            // Ignore an invalid CHROME_PATH and fall back to discovery.
+        }
+    }
+    for (const binary of CHROME_CANDIDATES) {
+        try {
+            const result = await run("which", [binary], { timeout: 3_000 });
+            if (result.code === 0 && result.stdout.trim())
+                return binary;
+        }
+        catch {
+            // `which` missing or the candidate is absent; try the next one.
+        }
+    }
+    return undefined;
+}
+function decodeEntities(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'");
+}
+export async function chromeMermaidCheck(code, chrome, vendorDir, run) {
+    const tmp = path.join(vendorDir, `.check-${process.pid}-${Math.random().toString(36).slice(2, 8)}.html`);
+    const html = `<!doctype html><meta charset="utf-8">
+<script>window.__CODE__ = ${JSON.stringify(code).replace(/</g, "\\u003c")};</script>
+<script src="mermaid.min.js"></script>
+<script>
+window.addEventListener('DOMContentLoaded', async () => {
+  let out;
+  try {
+    mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' });
+    await mermaid.parse(window.__CODE__);
+    out = 'OK';
+  } catch (e) {
+    out = 'ERROR: ' + ((e && e.message) || String(e));
+  }
+  const pre = document.createElement('pre');
+  pre.id = 'result';
+  pre.textContent = out;
+  document.body.appendChild(pre);
+});
+</script>`;
+    try {
+        await writeFile(tmp, html, "utf8");
+        const result = await run(chrome, [
+            "--headless=new",
+            "--disable-gpu",
+            "--no-sandbox",
+            "--virtual-time-budget=6000",
+            "--dump-dom",
+            pathToFileURL(tmp).href,
+        ], { timeout: 60_000 });
+        const match = /<pre id="result">([\s\S]*?)<\/pre>/.exec(result.stdout);
+        if (!match)
+            return { ok: false, error: "the Mermaid validator produced no result" };
+        const output = decodeEntities(match[1] ?? "").trim();
+        return output === "OK" ? { ok: true } : { ok: false, error: output };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        await rm(tmp, { force: true }).catch(() => { });
+    }
+}
+/**
+ * Structural check always runs. When a Chrome binary and a vendored Mermaid
+ * copy are available, the real Mermaid parser is used as a second gate.
+ */
+export async function validateMermaid(code, view, options = {}) {
+    const structural = structuralCheck(code, view);
+    if (!structural.ok)
+        return { result: structural, gate: "structural" };
+    if (options.run && options.vendorDir) {
+        const chrome = options.chrome === undefined ? await findChrome(options.run) : options.chrome;
+        if (chrome) {
+            return { result: await chromeMermaidCheck(code, chrome, options.vendorDir, options.run), gate: "chrome" };
+        }
+    }
+    return { result: structural, gate: "structural" };
+}

package/dist/diagram/viewer.d.ts

@@ -0,0 +1,30 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { DiagramGrade } from "./grade.js";
+export interface DiagramEntry {
+    name: string;
+    path: string;
+    flow: string;
+    seq: string;
+    dml: string;
+    presentation: string | null;
+    specification: string | null;
+}
+export interface ViewerBuildResult {
+    viewerPath: string;
+    diagramsDir: string;
+    entries: DiagramEntry[];
+}
+export interface BuildViewerOptions {
+    cwd: string;
+    templateText: string;
+    vendorAssetPath: string;
+    extraPaths?: string[];
+}
+/**
+ * Extract every target DML, collect the optional presentation/specification
+ * sidecars, and write the self-contained viewer plus per-skill Markdown.
+ */
+export declare function buildViewer(options: BuildViewerOptions): Promise<ViewerBuildResult>;
+export declare function writeSidecar(diagramsDir: string, name: string, grade: DiagramGrade, code: string): Promise<string>;
+/** Open the viewer at a specific diagram and view using a fixed, OS-native argv. */
+export declare function openViewerInBrowser(pi: Pick<ExtensionAPI, "exec">, viewerPath: string, name: string, view: string): Promise<boolean>;

package/dist/diagram/viewer.js

@@ -0,0 +1,94 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { renderDml, renderSequence } from "./extract.js";
+import { collectDiagramTargets, diagramNameFor, displayPath, ensureDiagramDir, } from "./workspace.js";
+async function readSidecar(diagramsDir, name, grade) {
+    try {
+        const value = (await readFile(path.join(diagramsDir, `${name}.${grade}.mmd`), "utf8")).trim();
+        return value || null;
+    }
+    catch {
+        return null;
+    }
+}
+function markdownFor(entry) {
+    const blocks = [];
+    if (entry.presentation)
+        blocks.push(`## Presentation\n\n\`\`\`mermaid\n${entry.presentation}\n\`\`\``);
+    if (entry.specification)
+        blocks.push(`## Specification\n\n\`\`\`mermaid\n${entry.specification}\n\`\`\``);
+    blocks.push(`## Flow\n\n\`\`\`mermaid\n${entry.flow}\n\`\`\``);
+    blocks.push(`## Sequence\n\n\`\`\`mermaid\n${entry.seq}\n\`\`\``);
+    return blocks.join("\n\n") + "\n";
+}
+async function renderViewer(diagramsDir, entries, templateText, vendorFile) {
+    const json = JSON.stringify(entries).replace(/</g, "\\u003c");
+    const generated = new Date().toISOString().slice(0, 16).replace("T", " ");
+    const html = templateText
+        .replace("__DIAGRAMS_JSON__", json)
+        .replace("__GENERATED__", generated)
+        .replace("vendor/mermaid.min.js", pathToFileURL(vendorFile).href);
+    const viewerPath = path.join(diagramsDir, "viewer.html");
+    await writeFile(viewerPath, html, "utf8");
+    const manifest = entries.map((entry) => ({
+        name: entry.name,
+        path: entry.path,
+        views: [
+            entry.presentation ? "presentation" : null,
+            entry.specification ? "specification" : null,
+            "flow",
+            "sequence",
+        ].filter(Boolean),
+    }));
+    await writeFile(path.join(diagramsDir, "index.json"), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+    return viewerPath;
+}
+/**
+ * Extract every target DML, collect the optional presentation/specification
+ * sidecars, and write the self-contained viewer plus per-skill Markdown.
+ */
+export async function buildViewer(options) {
+    const { diagrams, vendorFile } = await ensureDiagramDir(options.cwd, options.vendorAssetPath);
+    const targets = await collectDiagramTargets(options.cwd, options.extraPaths ?? []);
+    const entries = [];
+    for (const target of targets) {
+        const name = diagramNameFor(target, targets, options.cwd);
+        const display = displayPath(options.cwd, target);
+        const source = await readFile(target, "utf8");
+        const entry = {
+            name,
+            path: display,
+            flow: renderDml(display, source, { hideOutput: true }),
+            seq: renderSequence(display, source),
+            dml: source,
+            presentation: await readSidecar(diagrams, name, "presentation"),
+            specification: await readSidecar(diagrams, name, "specification"),
+        };
+        entries.push(entry);
+        await writeFile(path.join(diagrams, `${name}.md`), markdownFor(entry), "utf8");
+    }
+    const viewerPath = await renderViewer(diagrams, entries, options.templateText, vendorFile);
+    return { viewerPath, diagramsDir: diagrams, entries };
+}
+export async function writeSidecar(diagramsDir, name, grade, code) {
+    const file = path.join(diagramsDir, `${name}.${grade}.mmd`);
+    await writeFile(file, code.endsWith("\n") ? code : `${code}\n`, "utf8");
+    return file;
+}
+/** Open the viewer at a specific diagram and view using a fixed, OS-native argv. */
+export async function openViewerInBrowser(pi, viewerPath, name, view) {
+    const url = `${pathToFileURL(viewerPath).href}?view=${encodeURIComponent(view)}#${encodeURIComponent(name)}`;
+    try {
+        if (process.platform === "darwin")
+            await pi.exec("open", [url], { timeout: 10_000 });
+        else if (process.platform === "win32")
+            await pi.exec("cmd", ["/c", "start", "", url], { timeout: 10_000 });
+        else
+            await pi.exec("xdg-open", [url], { timeout: 10_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/diagram/workspace.d.ts

@@ -0,0 +1,24 @@
+/** Resolve an arbitrary .dml path (relative to cwd or absolute) for diagramming. */
+export declare function resolveDiagramSource(cwd: string, request: string): Promise<string>;
+/**
+ * Every DML file that should appear in the viewer: all skills and plans in the
+ * active workspace, plus any extra target (which may live anywhere).
+ */
+export declare function collectDiagramTargets(cwd: string, extra?: string[]): Promise<string[]>;
+/**
+ * Stable viewer/sidecar name. Same-named DML files in different directories get
+ * a short path hash so they can never collide.
+ */
+export declare function diagramNameFor(target: string, all: string[], cwd: string): string;
+export declare function displayPath(cwd: string, target: string): string;
+export interface DiagramDir {
+    root: string;
+    diagrams: string;
+    vendor: string;
+    vendorFile: string;
+}
+/**
+ * Create .pi/deepclause/diagrams/ and place the vendored Mermaid bundle so the
+ * viewer works offline. Existing files are never overwritten.
+ */
+export declare function ensureDiagramDir(cwd: string, vendorAssetPath: string): Promise<DiagramDir>;

package/dist/diagram/workspace.js

@@ -0,0 +1,106 @@
+import { access, copyFile, mkdir, readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { getPaths } from "../workspace.js";
+/** Resolve an arbitrary .dml path (relative to cwd or absolute) for diagramming. */
+export async function resolveDiagramSource(cwd, request) {
+    const raw = request.trim().replace(/^@/, "");
+    if (!raw)
+        throw new Error("A .dml path is required");
+    const absolute = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+    let resolved;
+    try {
+        resolved = await realpath(absolute);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new Error(`DML file not found: ${request}`);
+        throw error;
+    }
+    if (!resolved.endsWith(".dml"))
+        throw new Error("The diagram source must be a .dml file");
+    const info = await stat(resolved);
+    if (!info.isFile())
+        throw new Error(`Not a file: ${request}`);
+    return resolved;
+}
+async function walkDmlFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const files = [];
+    for (const entry of entries) {
+        const full = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...await walkDmlFiles(full));
+        else if (entry.isFile() && entry.name.endsWith(".dml"))
+            files.push(full);
+    }
+    return files;
+}
+async function canonical(file) {
+    try {
+        return await realpath(file);
+    }
+    catch {
+        return path.resolve(file);
+    }
+}
+/**
+ * Every DML file that should appear in the viewer: all skills and plans in the
+ * active workspace, plus any extra target (which may live anywhere).
+ */
+export async function collectDiagramTargets(cwd, extra = []) {
+    const paths = getPaths(cwd);
+    const found = new Set();
+    for (const file of [...await walkDmlFiles(paths.skills), ...await walkDmlFiles(paths.plans), ...extra]) {
+        found.add(await canonical(file));
+    }
+    return [...found].sort();
+}
+function shortHash(value) {
+    let hash = 5381;
+    for (let index = 0; index < value.length; index++) {
+        hash = ((hash * 33) ^ value.charCodeAt(index)) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0").slice(0, 4);
+}
+/**
+ * Stable viewer/sidecar name. Same-named DML files in different directories get
+ * a short path hash so they can never collide.
+ */
+export function diagramNameFor(target, all, cwd) {
+    const base = path.basename(target, ".dml");
+    const sameBase = all.filter((candidate) => path.basename(candidate, ".dml") === base);
+    if (sameBase.length <= 1)
+        return base;
+    return `${base}-${shortHash(path.relative(cwd, target))}`;
+}
+export function displayPath(cwd, target) {
+    const relative = path.relative(cwd, target);
+    return relative && !relative.startsWith("..") && !path.isAbsolute(relative)
+        ? relative.split(path.sep).join("/")
+        : target;
+}
+/**
+ * Create .pi/deepclause/diagrams/ and place the vendored Mermaid bundle so the
+ * viewer works offline. Existing files are never overwritten.
+ */
+export async function ensureDiagramDir(cwd, vendorAssetPath) {
+    const diagrams = path.join(getPaths(cwd).root, "diagrams");
+    const vendor = path.join(diagrams, "vendor");
+    await mkdir(vendor, { recursive: true });
+    const vendorFile = path.join(vendor, "mermaid.min.js");
+    try {
+        await access(vendorFile);
+    }
+    catch {
+        await copyFile(vendorAssetPath, vendorFile);
+    }
+    return { root: getPaths(cwd).root, diagrams, vendor, vendorFile };
+}