deepclause-sdk 0.0.89 → 0.1.0

package/dist/validate.js

@@ -0,0 +1,338 @@
+/**
+ * DML validation and linting.
+ *
+ * Parses DML with the real Prolog reader and applies structural/lint checks.
+ * This is the surviving part of the old compiler module (the Markdown->DML
+ * generator was removed); it is exported as `deepclause-sdk/validate` and used
+ * by the CLI's `validate_dml` runtime tool and by downstream apps
+ * (`deepclause-pi`, `sop2harness`).
+ */
+import { loadProlog } from './prolog/loader.js';
+// =============================================================================
+// Prolog Validation
+// =============================================================================
+let prologInstance = null;
+/**
+ * Get or initialize Prolog instance for validation
+ */
+async function getProlog() {
+    if (!prologInstance) {
+        prologInstance = await loadProlog();
+    }
+    return prologInstance;
+}
+/**
+ * Validate DML code using the actual Prolog parser
+ */
+export async function validateWithProlog(dml) {
+    const errors = [];
+    const warnings = [];
+    try {
+        const swipl = await getProlog();
+        // Write code to temp file
+        const tempPath = `/tmp/validate_${Date.now()}_${Math.random().toString(36).substring(7)}.pl`;
+        swipl.FS.writeFile(tempPath, dml);
+        // Try to parse the file using read_term which will catch syntax errors
+        try {
+            swipl.prolog.query(`catch(
+          (
+            open('${tempPath}', read, Stream, []),
+            call_cleanup(
+              read_all_terms(Stream),
+              close(Stream)
+            )
+          ),
+          Error,
+          (
+            Error = error(syntax_error(Message), _) -> 
+              true 
+            ; 
+              (term_to_atom(Error, Message), true)
+          )
+        ), 
+        read_all_terms(S) :- 
+          repeat,
+          read_term(S, T, [syntax_errors(error)]),
+          (T == end_of_file -> ! ; fail)`);
+            // Simple approach: try to consult the file
+            try {
+                swipl.prolog.call(`consult('${tempPath}')`);
+            }
+            catch (consultError) {
+                const errMsg = consultError instanceof Error ? consultError.message : String(consultError);
+                if (errMsg.includes('syntax') || errMsg.includes('error')) {
+                    // Extract meaningful error message
+                    const match = errMsg.match(/(?:syntax_error|error)\s*\(\s*['"]?([^'")\]]+)/i);
+                    if (match) {
+                        errors.push(`Syntax error: ${match[1]}`);
+                    }
+                    else {
+                        errors.push(`Parse error: ${errMsg.substring(0, 200)}`);
+                    }
+                }
+            }
+        }
+        catch (e) {
+            const errMsg = e instanceof Error ? e.message : String(e);
+            if (errMsg.includes('syntax') || errMsg.includes('error')) {
+                errors.push(errMsg.substring(0, 200));
+            }
+        }
+        // Check for required elements
+        if (!dml.includes('agent_main')) {
+            errors.push('Missing agent_main predicate - every DML program must define agent_main');
+        }
+        // Check for balanced delimiters
+        const delimiterCheck = checkBalancedDelimiters(dml);
+        errors.push(...delimiterCheck.errors);
+        // Check for common mistakes
+        const lintResult = lintDML(dml);
+        errors.push(...lintResult.errors);
+        warnings.push(...lintResult.warnings);
+        // Cleanup temp file
+        try {
+            swipl.FS.unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+    catch (error) {
+        // If Prolog itself fails, fall back to basic validation
+        return validateDMLSyntaxBasic(dml);
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings: warnings.length > 0 ? warnings : undefined
+    };
+}
+/**
+ * Check balanced delimiters
+ */
+function checkBalancedDelimiters(dml) {
+    const errors = [];
+    // Remove strings and comments for delimiter checking
+    const stripped = dml
+        .replace(/"(?:[^"\\]|\\.)*"/g, '""') // Remove string contents
+        .replace(/%.*$/gm, '') // Remove line comments
+        .replace(/\/\*[\s\S]*?\*\//g, ''); // Remove block comments
+    let parenCount = 0;
+    let bracketCount = 0;
+    let braceCount = 0;
+    for (const char of stripped) {
+        if (char === '(')
+            parenCount++;
+        if (char === ')')
+            parenCount--;
+        if (char === '[')
+            bracketCount++;
+        if (char === ']')
+            bracketCount--;
+        if (char === '{')
+            braceCount++;
+        if (char === '}')
+            braceCount--;
+        if (parenCount < 0) {
+            errors.push('Unbalanced parentheses: extra closing )');
+            break;
+        }
+        if (bracketCount < 0) {
+            errors.push('Unbalanced brackets: extra closing ]');
+            break;
+        }
+        if (braceCount < 0) {
+            errors.push('Unbalanced braces: extra closing }');
+            break;
+        }
+    }
+    if (parenCount > 0)
+        errors.push(`Unbalanced parentheses: ${parenCount} unclosed (`);
+    if (bracketCount > 0)
+        errors.push(`Unbalanced brackets: ${bracketCount} unclosed [`);
+    if (braceCount > 0)
+        errors.push(`Unbalanced braces: ${braceCount} unclosed {`);
+    return { errors };
+}
+/**
+ * Extract all string literals from DML code (both single and double quoted)
+ */
+function extractStringLiterals(dml) {
+    const doubleQuoted = [];
+    const singleQuoted = [];
+    // Double-quoted strings
+    for (const m of dml.matchAll(/"((?:[^"\\]|\\.)*)"/g)) {
+        doubleQuoted.push(m[1]);
+    }
+    // Single-quoted atoms
+    for (const m of dml.matchAll(/'((?:[^'\\]|\\.)*)'/g)) {
+        singleQuoted.push(m[1]);
+    }
+    return { doubleQuoted, singleQuoted };
+}
+/**
+ * Strip comments and string contents for structural analysis
+ */
+function stripForAnalysis(dml) {
+    return dml
+        .replace(/%.*$/gm, '') // line comments
+        .replace(/\/\*[\s\S]*?\*\//g, '') // block comments
+        .replace(/"(?:[^"\\]|\\.)*"/g, '""') // double-quoted string contents
+        .replace(/'(?:[^'\\]|\\.)*'/g, "''"); // single-quoted atom contents
+}
+/**
+ * Lint DML for common issues — focused on string handling and structural errors.
+ * Returns errors (will crash at runtime) and warnings (likely wrong).
+ */
+function lintDML(dml) {
+    const errors = [];
+    const warnings = [];
+    const stripped = stripForAnalysis(dml);
+    const { doubleQuoted, singleQuoted } = extractStringLiterals(dml);
+    const allStrings = [...doubleQuoted, ...singleQuoted];
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STRING HANDLING ERRORS — these WILL crash or produce wrong output
+    // ═══════════════════════════════════════════════════════════════════════════
+    // E1: format() passed directly to output() or answer()
+    //     format/3 binds its first arg, it does NOT return a value.
+    //     output(format("...", [...])) is always wrong.
+    if (/output\s*\(\s*format\s*\(/.test(dml)) {
+        errors.push('ERROR: format/3 does not return a value. `output(format(...))` will crash. Fix: format(string(S), "...", [...]), output(S).');
+    }
+    if (/answer\s*\(\s*format\s*\(/.test(dml)) {
+        errors.push('ERROR: format/3 does not return a value. `answer(format(...))` will crash. Fix: format(string(S), "...", [...]), answer(S).');
+    }
+    // E2: ~Variable in task/prompt description strings (only ~w, ~d, ~a, ~s work with format)
+    //     task("Analyze ~Topic", R) does NOT interpolate. Use {Topic}.
+    for (const s of doubleQuoted) {
+        if (/~[A-Z][a-zA-Z0-9_]*/.test(s)) {
+            errors.push(`ERROR: ~Variable interpolation does not work in DML. Found in: "...${s.substring(0, 60)}...". Use {Variable} syntax instead (e.g. {Topic} not ~Topic).`);
+            break;
+        }
+    }
+    // E3: {Variable} inside format/3 template string
+    //     format(string(S), "Hello {Name}", []) — the {Name} won't be interpolated by format.
+    //     This is a style-mixing bug.
+    const formatCalls = dml.matchAll(/format\s*\(\s*(?:string|atom)\s*\([^)]*\)\s*,\s*"([^"]*)"/g);
+    for (const m of formatCalls) {
+        const tmpl = m[1];
+        if (/\{[A-Z][a-zA-Z0-9_]*\}/.test(tmpl)) {
+            errors.push(`ERROR: {Variable} inside format() template does nothing — format uses ~w placeholders. Found: "${tmpl.substring(0, 60)}". Use EITHER {Variable} in task() strings OR ~w in format() strings, never both in the same string.`);
+            break;
+        }
+    }
+    // E4: String concatenation with + operator
+    //     "hello" + "world" or Var + Var — Prolog's + is arithmetic only.
+    if (/"\s*\+\s*"/.test(dml) || /"\s*\+\s*[A-Z]/.test(dml) || /[A-Z][a-zA-Z_0-9]*\s*\+\s*"/.test(dml)) {
+        errors.push('ERROR: The + operator is arithmetic only in Prolog, not string concatenation. Use {Variable} interpolation in task() strings, or atom_concat/3, or format/3 for building strings.');
+    }
+    // E5: task() with non-string first arg — task(llm(...)) or task(prompt(...))
+    if (/task\s*\(\s*(?:llm|prompt)\s*\(/.test(stripped)) {
+        errors.push('ERROR: task() takes a plain string as first argument. task(llm(...)) and task(prompt(...)) are wrong. Use: task("description string", Var).');
+    }
+    // E6: Hallucinated predicates — these do NOT exist in DML runtime
+    //     But skip if user defines the predicate themselves (pred(...) :- ...).
+    const hallucinated = [
+        ['json_parse', 'json_parse/2 does not exist. Use task() to extract data from JSON via LLM.'],
+        ['http_get', 'http_get does not exist. Use exec(url_fetch(url: URL), R).'],
+        ['string_format', 'string_format does not exist. Use format(string(R), FormatStr, Args).'],
+        ['get_field', 'get_field does not exist. Use get_dict(Key, Dict, Value) — note: Key comes first.'],
+        ['string_join', 'string_join does not exist. Use atomic_list_concat(List, Sep, Atom).'],
+        ['string_lower', 'string_lower does not exist. Use downcase_atom(Atom, Lower).'],
+        ['string_trim', 'string_trim does not exist. Use normalize_space(string(Out), In).'],
+        ['contains', 'contains/2 does not exist. Use sub_atom/5 or sub_string/5.'],
+    ];
+    for (const [name, msg] of hallucinated) {
+        const usePattern = new RegExp(`(?<!\\w)${name}\\s*\\(`, 'g');
+        if (usePattern.test(stripped)) {
+            // Check if user defines this predicate (name(...) :- or name(...) .)
+            const defPattern = new RegExp(`^${name}\\s*\\([^)]*\\)\\s*(?::-|\\.)`, 'm');
+            if (!defPattern.test(stripped)) {
+                errors.push(`ERROR: ${msg}`);
+            }
+        }
+    }
+    // E7: url_fetch used as a bare predicate (not wrapped in exec)
+    //     url_fetch("url", R) is wrong. Must be exec(url_fetch(url: "..."), R).
+    if (/(?<!exec\s*\(\s*)url_fetch\s*\(\s*"/.test(stripped)) {
+        errors.push('ERROR: url_fetch is not a predicate. Must use exec/2 wrapper: exec(url_fetch(url: URL), R).');
+    }
+    // E8: curl/wget in bash command strings
+    for (const s of allStrings) {
+        if (/\b(?:curl|wget)\s/.test(s)) {
+            errors.push('ERROR: curl and wget are banned — the VM has no direct internet. Use exec(url_fetch(url: URL), R) to fetch web content.');
+            break;
+        }
+    }
+    // E9: writeln() used for user output — not a DML predicate
+    if (/(?<!\w)writeln\s*\(/.test(stripped)) {
+        // Check it's not inside an open/close file I/O block (write to stream is OK)
+        // Simple heuristic: if there's no open() call, writeln is definitely wrong
+        if (!/\bopen\s*\(/.test(stripped) || /writeln\s*\(\s*['"]/.test(dml)) {
+            errors.push('ERROR: writeln() is not a DML output predicate. Use output() for progress messages and answer() for final results.');
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STRING HANDLING WARNINGS — likely wrong, should fix
+    // ═══════════════════════════════════════════════════════════════════════════
+    // W1: Mixing {Variable} interpolation and format/3 in the same clause
+    //     Not always wrong (different strings), but a code smell with small models
+    const hasInterpolation = /\{[A-Z][a-zA-Z0-9_]*\}/.test(dml);
+    const hasFormat = /format\s*\(/.test(stripped);
+    if (hasInterpolation && hasFormat) {
+        warnings.push('WARNING: Code mixes {Variable} interpolation and format/3. This is allowed but can confuse the runtime if mixed in the same string. Ensure {Variable} is only in task()/output()/answer() strings and ~w is only in format() strings.');
+    }
+    // W2: No tool definitions — model probably wrote pure Prolog
+    if (!/\btool\s*\(/.test(dml)) {
+        warnings.push('WARNING: No tool() definitions found. This is fine for pure Prolog or direct exec()-only skills, but LLM-driven skills usually need tool()/3 wrappers for task() calls.');
+    }
+    // W3: No task() call — model probably wrote pure Prolog logic
+    if (!/\btask\s*\(/.test(stripped)) {
+        warnings.push('WARNING: No task() call found. This is fine for deterministic or simple skills. Skills that need open-ended reasoning, summarization, extraction, or classification should usually use task().');
+    }
+    // W4: No system() call — LLM has no instructions
+    if (!/\bsystem\s*\(/.test(stripped)) {
+        warnings.push('WARNING: No system() call found. Add system() when the skill uses task()/prompt() and the LLM needs instructions on how to use tools.');
+    }
+    // W5: No answer() call — skill completes silently
+    if (!/\banswer\s*\(/.test(stripped)) {
+        warnings.push('WARNING: No answer() call found. The skill will complete without returning a result to the user.');
+    }
+    // W6: No output() before task/exec — skill appears frozen
+    if (/\btask\s*\(/.test(stripped) && !/\boutput\s*\(/.test(stripped)) {
+        warnings.push('WARNING: No output() calls found. Add output() before long-running task() or exec() calls so the skill doesn\'t appear frozen.');
+    }
+    // W7: Single agent_main clause — no fallback
+    const mainMatches = stripped.match(/agent_main\s*[\(\.]/g);
+    if (mainMatches && mainMatches.length === 1) {
+        warnings.push('WARNING: Only one agent_main clause. Add a fallback clause with a static error message (no LLM calls) as required by Rule 7.');
+    }
+    // W8: Dict dot notation — Result.field etc.
+    //     Only check outside strings — match Var.key pattern in code
+    if (/[A-Z][a-zA-Z_0-9]*\.[a-z][a-z_]+(?!\s*\()/.test(stripped)) {
+        warnings.push('WARNING: Possible dict dot notation (e.g. Result.stdout). This may not work — use get_dict(Key, Dict, Value) instead.');
+    }
+    return { errors, warnings };
+}
+/**
+ * Basic syntax validation (fallback when Prolog fails)
+ */
+function validateDMLSyntaxBasic(dml) {
+    const errors = [];
+    if (!dml.includes('agent_main')) {
+        errors.push('Missing agent_main predicate');
+    }
+    const delimiterCheck = checkBalancedDelimiters(dml);
+    errors.push(...delimiterCheck.errors);
+    // Check for unclosed strings
+    const stringPattern = /"(?:[^"\\]|\\.)*"/g;
+    const cleanedDml = dml.replace(stringPattern, '""');
+    if ((cleanedDml.match(/"/g) || []).length % 2 !== 0) {
+        errors.push('Unclosed string literal');
+    }
+    return {
+        valid: errors.length === 0,
+        errors: [...new Set(errors)]
+    };
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/dist/visualize/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `deepclause visualize` — turn a harness (its `listing`, including `doc/2` and
+ * `module_doc/1`) into a Mermaid diagram.
+ *
+ * Two granularities, mirroring sop2harness:
+ *   - `presentation`: a general-audience overview (inputs, steps, answer).
+ *   - `spec`: engineering detail (decisions, thresholds, task/exec calls,
+ *     branches, fallbacks).
+ *
+ * The Mermaid source is always the deliverable; PNG/SVG rendering is best
+ * effort via `@mermaid-js/mermaid-cli` (`mmdc`) when it is available.
+ */
+export type DiagramMode = 'presentation' | 'spec';
+export interface DiagramPromptInput {
+    /** Entry predicate, e.g. `router/2`. */
+    entry: string;
+    mode: DiagramMode;
+    /** The harness `listing` text (source + `doc/2` annotations + manifest). */
+    listing: string;
+}
+/**
+ * Build the diagram-generation prompt. The model only sees the harness listing
+ * (source + docs) and the entry point, and must return Mermaid only.
+ */
+export declare function buildDiagramPrompt(input: DiagramPromptInput): string;
+/** Extract Mermaid source from a model reply (strips fences and leading prose). */
+export declare function extractMermaid(text: string): string;
+/** Light structural validation (same spirit as sop2harness). */
+export declare function validateMermaid(source: string): string[];
+/** A mermaid renderer command, if one is available. */
+export declare function findMermaidRenderer(): {
+    command: string;
+    args: string[];
+} | undefined;
+/**
+ * Render a `.mmd` file to an image. Returns the renderer used, or throws with a
+ * helpful message when no renderer is available.
+ */
+export declare function renderMermaidFile(mmdPath: string, outputPath: string): Promise<string>;
+/** Split `name/arity` (or `name`) into a predicate name and arity. */
+export declare function parseEntry(entry: string): {
+    name: string;
+    arity?: number;
+};
+/** Resolve the `.mmd` path and the optional image path from `--output`. */
+export declare function resolveOutputPaths(output: string | undefined, entry: string): {
+    mmdPath: string;
+    imagePath?: string;
+};
+/** Write the Mermaid source (creating directories as needed). */
+export declare function writeMermaid(mmdPath: string, source: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/visualize/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/visualize/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,MAAM,CAAC;AAIlD,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,WAAW,CAAC;IAClB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAuCpE;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYnD;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAoBxD;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,SAAS,CAQrF;AAiBD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsC5F;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAU1E;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CASrH;AAED,iEAAiE;AACjE,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjF"}

package/dist/visualize/index.js

@@ -0,0 +1,189 @@
+/**
+ * `deepclause visualize` — turn a harness (its `listing`, including `doc/2` and
+ * `module_doc/1`) into a Mermaid diagram.
+ *
+ * Two granularities, mirroring sop2harness:
+ *   - `presentation`: a general-audience overview (inputs, steps, answer).
+ *   - `spec`: engineering detail (decisions, thresholds, task/exec calls,
+ *     branches, fallbacks).
+ *
+ * The Mermaid source is always the deliverable; PNG/SVG rendering is best
+ * effort via `@mermaid-js/mermaid-cli` (`mmdc`) when it is available.
+ */
+import { spawnSync } from 'child_process';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+const DIAGRAM_TYPE = /^\s*(flowchart|graph|sequenceDiagram|classDiagram|stateDiagram|erDiagram|journey|gantt|pie)\b/i;
+/**
+ * Build the diagram-generation prompt. The model only sees the harness listing
+ * (source + docs) and the entry point, and must return Mermaid only.
+ */
+export function buildDiagramPrompt(input) {
+    const kind = input.mode === 'presentation'
+        ? [
+            'KIND: presentation — a general-audience overview.',
+            '- Show the skill name, its inputs, the main steps in order, and the final answer.',
+            '- Read like a process a stakeholder could follow. Avoid Prolog syntax and predicate names in labels.',
+        ].join('\n')
+        : [
+            'KIND: specification — engineering detail.',
+            '- Show every decision (choose/verify/rate/probability, holds), threshold, and rule fact.',
+            '- Show task/N and prompt/N model calls (with their typed outputs), exec/2 tool calls, branches,',
+            '  backtracking, and explicit fallback paths.',
+        ].join('\n');
+    return [
+        'You are a technical writer who turns DeepClause (Prolog/DML) agent harnesses into Mermaid diagrams.',
+        '',
+        `Produce ONE Mermaid diagram for the skill \`${input.entry}\` in the harness below.`,
+        '',
+        'OUTPUT RULES',
+        '- Return ONLY Mermaid source. No prose, no explanation, no ``` code fences.',
+        '- The first line must be `flowchart TD` or `flowchart LR`.',
+        '- Quote any node label containing spaces or punctuation: A["text"], B["x = 1"].',
+        '- Plain flowchart syntax only (nodes, edges, subgraphs). No `classDef`/`style`/`click` directives.',
+        '- Keep it readable: at most about 20 nodes.',
+        '',
+        'HARNESS SEMANTICS',
+        '- task/N, prompt/N: a model call (prompt/N has fresh context).',
+        '- exec(Tool(...)): a host tool call (usually bash).',
+        '- choose/verify/rate/probability, holds: a semantic judgment (a decision).',
+        '- Multiple clauses / `;` / `->`: alternative paths; show the "else"/fallback.',
+        '',
+        kind,
+        '',
+        `HARNESS (focus: ${input.entry}; the listing includes each predicate and its doc/2 annotation)`,
+        '```',
+        input.listing.trim() || '(empty harness)',
+        '```',
+    ].join('\n');
+}
+/** Extract Mermaid source from a model reply (strips fences and leading prose). */
+export function extractMermaid(text) {
+    let out = (text ?? '').trim();
+    const fence = out.match(/```(?:mermaid)?\s*\n?([\s\S]*?)```/i);
+    if (fence) {
+        out = fence[1].trim();
+    }
+    const lines = out.split('\n');
+    const start = lines.findIndex((line) => DIAGRAM_TYPE.test(line));
+    if (start > 0) {
+        out = lines.slice(start).join('\n').trim();
+    }
+    return out;
+}
+/** Light structural validation (same spirit as sop2harness). */
+export function validateMermaid(source) {
+    const issues = [];
+    const lines = source.split('\n').map((line) => line.trim()).filter(Boolean);
+    if (lines.length === 0) {
+        return ['the diagram is empty'];
+    }
+    const first = lines.find((line) => !line.startsWith('%%'));
+    if (!first) {
+        issues.push('no diagram body (only comments)');
+    }
+    else if (!DIAGRAM_TYPE.test(first)) {
+        issues.push(`unrecognized diagram type: ${first.split(/\s+/)[0]}`);
+    }
+    for (const [open, close] of [['{', '}'], ['[', ']'], ['(', ')']]) {
+        const opens = (source.match(new RegExp(`\\${open}`, 'g')) ?? []).length;
+        const closes = (source.match(new RegExp(`\\${close}`, 'g')) ?? []).length;
+        if (opens !== closes) {
+            issues.push(`unbalanced ${open}${close} (${opens}/${closes})`);
+        }
+    }
+    return issues;
+}
+/** A mermaid renderer command, if one is available. */
+export function findMermaidRenderer() {
+    const which = process.platform === 'win32' ? 'where' : 'which';
+    for (const candidate of ['mmdc', 'mmdc.cmd']) {
+        if (spawnSync(which, [candidate], { stdio: 'ignore' }).status === 0) {
+            return { command: candidate, args: [] };
+        }
+    }
+    return undefined;
+}
+/** Absolute path to a system Chromium/Chrome, for puppeteer to launch. */
+function findChrome() {
+    const which = process.platform === 'win32' ? 'where' : 'which';
+    for (const candidate of ['google-chrome', 'chromium', 'chromium-browser', 'chrome']) {
+        const result = spawnSync(which, [candidate], { encoding: 'utf8' });
+        if (result.status === 0) {
+            const first = (result.stdout ?? '').trim().split('\n')[0].trim();
+            if (first) {
+                return first;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Render a `.mmd` file to an image. Returns the renderer used, or throws with a
+ * helpful message when no renderer is available.
+ */
+export async function renderMermaidFile(mmdPath, outputPath) {
+    const renderer = findMermaidRenderer();
+    const command = renderer ? renderer.command : 'npx';
+    const args = renderer ? [...renderer.args] : ['--yes', '@mermaid-js/mermaid-cli'];
+    args.push('-i', mmdPath, '-o', outputPath, '-b', 'white');
+    const env = { ...process.env };
+    if (!env.PUPPETEER_EXECUTABLE_PATH) {
+        const chrome = findChrome();
+        if (chrome) {
+            env.PUPPETEER_EXECUTABLE_PATH = chrome;
+        }
+    }
+    // Reuse the system browser instead of downloading Chromium for puppeteer.
+    if (env.PUPPETEER_EXECUTABLE_PATH && env.PUPPETEER_SKIP_DOWNLOAD == null) {
+        env.PUPPETEER_SKIP_DOWNLOAD = 'true';
+    }
+    // Chrome sandbox flags (mirrors sop2harness's `mmdc -p <config>` usage).
+    const configPath = path.join(os.tmpdir(), `deepclause-mermaid-${process.pid}.json`);
+    await fs.writeFile(configPath, JSON.stringify({
+        args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+    }));
+    args.push('-p', configPath);
+    try {
+        const result = spawnSync(command, args, { env, encoding: 'utf8' });
+        if (result.status !== 0) {
+            const reason = (result.stderr || result.stdout || '').trim().split('\n').slice(-3).join(' ');
+            throw new Error(`Mermaid renderer failed${reason ? `: ${reason}` : ''}. `
+                + 'Install it with `npm i -g @mermaid-js/mermaid-cli` (or use `--output <file>.mmd`).');
+        }
+        return renderer ? renderer.command : 'npx @mermaid-js/mermaid-cli';
+    }
+    finally {
+        await fs.rm(configPath, { force: true });
+    }
+}
+/** Split `name/arity` (or `name`) into a predicate name and arity. */
+export function parseEntry(entry) {
+    const match = entry.trim().match(/^([A-Za-z_][A-Za-z0-9_]*)\s*\/\s*(\d+)$/);
+    if (match) {
+        return { name: match[1], arity: Number(match[2]) };
+    }
+    const bare = entry.trim().match(/^([A-Za-z_][A-Za-z0-9_]*)$/);
+    if (bare) {
+        return { name: bare[1] };
+    }
+    throw new Error(`invalid entry '${entry}': expected Name/Arity (e.g. router/2)`);
+}
+/** Resolve the `.mmd` path and the optional image path from `--output`. */
+export function resolveOutputPaths(output, entry) {
+    const fallback = `${entry.replace(/[^A-Za-z0-9_.-]/g, '_') || 'diagram'}.mmd`;
+    const target = output ?? fallback;
+    if (target.toLowerCase().endsWith('.mmd')) {
+        return { mmdPath: target };
+    }
+    const ext = path.extname(target);
+    const mmdPath = ext ? `${target.slice(0, -ext.length)}.mmd` : `${target}.mmd`;
+    return { mmdPath, imagePath: target };
+}
+/** Write the Mermaid source (creating directories as needed). */
+export async function writeMermaid(mmdPath, source) {
+    await fs.mkdir(path.dirname(path.resolve(mmdPath)), { recursive: true });
+    await fs.writeFile(mmdPath, `${source.trim()}\n`, 'utf8');
+}
+//# sourceMappingURL=index.js.map

package/dist/visualize/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/visualize/index.ts"],"names":[],"mappings":"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"}