@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/runtime/plan-decompose.js

@@ -1,531 +0,0 @@
-import { mkdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
-import { relative, resolve, sep } from 'node:path';
-import { z } from 'zod';
-/**
- * `pugi plan --decompose <idea>` — pattern ported (not copied) from
- * the piercelamb/deep-project plugin (MIT-licensed, 134 stars). The Deep
- * Trilogy splits a high-level idea into focused components, each backed
- * by its own `spec.md`, plus a `project-manifest.md` with the dependency
- * DAG. Pugi's port reuses our existing `pugi plan` engine task and
- * persists artifacts under `.pugi/plan/<session-id>/` so the decomposed
- * specs are reviewable + resumable in the same shape as the rest of the
- * artifact store.
- *
- * Why a separate module: the engine task in `runtime/cli.ts` is already
- * 200+ LOC. Lifting the prompt suffix, JSON parser, and atomic writer
- * out keeps the integration in `runEngineTask` to a single import + a
- * single post-result branch. The module exports a small surface
- * (parser + writer + helpers) so the spec can drive each piece in
- * isolation against golden fixtures.
- *
- * Reference: https://github.com/piercelamb/deep-project (MIT). Pugi
- * extracted the high-level pattern (split-into-components + manifest
- * DAG + per-component spec) and ships a Pugi-native implementation.
- */
-/**
- * Suffix appended to the operator's `pugi plan --decompose` prompt so
- * the model emits a single JSON block at the end of its final answer.
- * The JSON is the machine-readable contract; the prose preceding it
- * (rationale, alternatives considered) lands inside `manifest.md` for
- * the operator's review.
- *
- * Design choices anchored by the Deep-Project pattern + our own
- * planning ergonomics:
- *  - 3-7 component sweet spot: more than 7 produces unreviewable
- *    spaghetti, fewer than 3 wastes the decomposition step. The
- *    schema enforces this hard so the prompt promise matches the
- *    contract.
- *  - `dependsOn` references component names verbatim — the writer
- *    enforces uniqueness and resolves the DAG, so a typo there
- *    fails loud at parse time rather than producing a silently
- *    wrong manifest.
- *  - JSON fence is mandatory so the parser can `slice` it out
- *    deterministically; loose JSON-in-prose extractions are
- *    brittle and trigger false positives.
- */
-export const DECOMPOSE_PROMPT_SUFFIX = [
-    '',
-    '## Decomposition request',
-    '',
-    'Split the idea above into 3-7 focused components. Each component must be:',
-    '- Small enough to fit a single supervised build session (~half a day).',
-    '- Explicit about its dependencies on other components by name.',
-    '- Specified well enough that a fresh `pugi plan <component-name>` session could pick it up.',
-    '',
-    'After your prose rationale, emit a SINGLE fenced JSON block at the END of your answer.',
-    'The JSON block MUST match this shape exactly:',
-    '',
-    '```json',
-    '{',
-    ' "components": [',
-    '   {',
-    '     "name": "kebab-case-name",',
-    '     "summary": "one-sentence headline",',
-    '     "spec": "multi-line spec body — what to build, acceptance criteria, files touched",',
-    '     "dependsOn": ["other-component-name", "..."]',
-    '   }',
-    ' ]',
-    '}',
-    '```',
-    '',
-    'Constraints:',
-    '- `name` is kebab-case, 1-48 chars, unique across components.',
-    '- `dependsOn` references other component names from the same list. Empty array if no dependencies.',
-    '- Order components in topological order (dependencies first).',
-    '- Do NOT emit additional fields. Do NOT emit multiple JSON blocks. Do NOT inline implementation code.',
-].join('\n');
-/**
- * Windows reserved filename basenames (case-insensitive). The atomic
- * writer rejects any component name that lowercases to one of these so
- * a future Windows checkout never trips on `splits/01-con/spec.md` etc.
- * The kebab-case regex already blocks the colon-separated `com1:` style,
- * but the bare `con` / `nul` / `prn` / `aux` / `comN` / `lptN` forms
- * still pass the regex; the denylist closes that gap.
- */
-const WINDOWS_RESERVED_BASENAMES = new Set([
-    'con',
-    'prn',
-    'aux',
-    'nul',
-    'com1',
-    'com2',
-    'com3',
-    'com4',
-    'com5',
-    'com6',
-    'com7',
-    'com8',
-    'com9',
-    'lpt1',
-    'lpt2',
-    'lpt3',
-    'lpt4',
-    'lpt5',
-    'lpt6',
-    'lpt7',
-    'lpt8',
-    'lpt9',
-]);
-/**
- * Reject any free-text field whose body would close a triple-backtick
- * fence and re-open the surrounding Markdown to model-controlled
- * interpretation. Mermaid blocks and the SPLIT_MANIFEST JSON block are
- * both rendered inside ``` fences in the manifest, so a stray ``` in
- * `summary` / `prompt` / `name` / `spec` would tip the renderer mid
- * fence. We reject at the schema layer (fail loud) rather than escape
- * at render time — escaping would still let model-authored text leak
- * into the Mermaid AST and we have no need to round-trip backticks.
- */
-const TRIPLE_BACKTICK_RE = /```/;
-/**
- * Single decomposed component. The shape mirrors the JSON contract in
- * the prompt suffix exactly so the parser is a one-shot `z.parse`.
- */
-const componentSchema = z.object({
-    name: z
-        .string()
-        .min(1)
-        .max(48)
-        .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'name must be kebab-case (a-z, 0-9, hyphen)')
-        .refine((value) => !TRIPLE_BACKTICK_RE.test(value), {
-        message: 'name must not contain triple backticks',
-    })
-        .refine((value) => !WINDOWS_RESERVED_BASENAMES.has(value.toLowerCase()), {
-        message: 'name collides with a Windows reserved filename',
-    }),
-    summary: z
-        .string()
-        .min(1)
-        .max(200)
-        .refine((value) => !TRIPLE_BACKTICK_RE.test(value), {
-        message: 'summary must not contain triple backticks',
-    }),
-    spec: z
-        .string()
-        .min(1)
-        .refine((value) => !TRIPLE_BACKTICK_RE.test(value), {
-        message: 'spec must not contain triple backticks',
-    }),
-    // Reject empty strings at the array element level so a stray `""` in
-    // `dependsOn` cannot pass the structural validation and turn into a
-    // mystery node id later.
-    dependsOn: z.array(z.string().min(1)).default([]),
-});
-export const decompositionSchema = z
-    .object({
-    // 3-7 components matches the prompt contract verbatim. Tighter
-    // bounds catch malformed outputs (e.g. a model that returned a
-    // single mega-component or a list of fifteen) at parse time.
-    components: z.array(componentSchema).min(3).max(7),
-})
-    .superRefine((value, ctx) => {
-    const names = new Set();
-    for (const [index, component] of value.components.entries()) {
-        if (names.has(component.name)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ['components', index, 'name'],
-                message: `duplicate component name "${component.name}"`,
-            });
-        }
-        names.add(component.name);
-    }
-    for (const [index, component] of value.components.entries()) {
-        for (const [depIndex, dep] of component.dependsOn.entries()) {
-            if (!names.has(dep)) {
-                // Surface the unresolved reference at parse time so the writer
-                // is guaranteed a referentially-closed DAG.
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    path: ['components', index, 'dependsOn', depIndex],
-                    message: `dependsOn references unknown component "${dep}"`,
-                });
-            }
-            if (dep === component.name) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    path: ['components', index, 'dependsOn', depIndex],
-                    message: `component "${component.name}" cannot depend on itself`,
-                });
-            }
-        }
-    }
-});
-/**
- * Extract the LAST fenced JSON block from the model's final text and
- * validate it against the decomposition schema. The LAST block is the
- * right choice because models sometimes emit example JSON inside the
- * rationale to illustrate a point, then emit the canonical block at
- * the bottom. Honouring "last" makes the contract unambiguous.
- *
- * Fence patterns accepted: ```json ... ``` (preferred) and bare
- * ``` ... ``` when the body is valid JSON. We do NOT support naked
- * JSON outside a fence: that is brittle (any model that wraps prose
- * in quotes would tip the parser) and the prompt mandates the fence.
- *
- * Line endings: the regex tolerates both LF and CRLF newlines so a
- * Windows-checkout transcript pastes through without ceremony.
- */
-export function parseDecompositionFromText(text) {
-    const blocks = extractFencedJsonBlocks(text);
-    if (blocks.length === 0) {
-        return {
-            ok: false,
-            reason: 'no_json_block',
-            detail: 'model did not emit a fenced JSON block',
-        };
-    }
-    // Pick the LAST block — see docstring. The rationale is everything
-    // before that block's opening fence.
-    const last = blocks[blocks.length - 1];
-    const rationale = text.slice(0, last.fenceStart).trim();
-    let parsed;
-    try {
-        parsed = JSON.parse(last.body);
-    }
-    catch (error) {
-        return {
-            ok: false,
-            reason: 'invalid_json',
-            detail: error instanceof Error ? error.message : String(error),
-        };
-    }
-    const result = decompositionSchema.safeParse(parsed);
-    if (!result.success) {
-        return {
-            ok: false,
-            reason: 'invalid_schema',
-            detail: result.error.issues
-                .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
-                .join('; '),
-        };
-    }
-    return { ok: true, decomposition: result.data, rationale };
-}
-function extractFencedJsonBlocks(text) {
-    const blocks = [];
-    // Matches ```json\n...\n``` and ```\n...\n``` (capture group 1 is body).
-    // We use `[\s\S]*?` (non-greedy) so adjacent fences do not merge into a
-    // single capture. The `\r?\n` tolerance keeps CRLF transcripts working
-    // without a separate normalization pass.
-    const pattern = /```(?:json)?[ \t]*\r?\n([\s\S]*?)\r?\n```/g;
-    let match = pattern.exec(text);
-    while (match !== null) {
-        blocks.push({
-            fenceStart: match.index,
-            fenceEnd: match.index + match[0].length,
-            body: match[1].trim(),
-        });
-        match = pattern.exec(text);
-    }
-    return blocks;
-}
-export function writeDecomposition(input) {
-    const { root, sessionId, prompt, decomposition, rationale } = input;
-    const generatedAt = input.generatedAt ?? new Date().toISOString();
-    const planDir = resolve(root, '.pugi', 'plan', sessionId);
-    const splitsDir = resolve(planDir, 'splits');
-    const stagingSuffix = `splits.tmp-${sessionId}-${process.pid}-${Date.now()}`;
-    const stagingDir = resolve(planDir, stagingSuffix);
-    const manifestFinalPath = resolve(planDir, 'manifest.md');
-    const manifestTmpPath = `${manifestFinalPath}.tmp-${process.pid}-${Date.now()}`;
-    mkdirSync(planDir, { recursive: true });
-    mkdirSync(stagingDir, { recursive: true });
-    const splitPaths = [];
-    try {
-        for (const [index, component] of decomposition.components.entries()) {
-            const numbered = `${String(index + 1).padStart(2, '0')}-${component.name}`;
-            const componentDir = resolve(stagingDir, numbered);
-            // Defense-in-depth: even though the schema rejects `..` / `/` /
-            // NUL / Windows reserved basenames in `name`, re-assert that the
-            // resolved path stays inside the staging directory before any
-            // byte is written. One regex change away from escape becomes one
-            // assertion away from escape.
-            assertContained(stagingDir, componentDir);
-            mkdirSync(componentDir, { recursive: true });
-            const specPath = resolve(componentDir, 'spec.md');
-            assertContained(stagingDir, specPath);
-            writeFileSync(specPath, formatSpec(component, decomposition, generatedAt), {
-                encoding: 'utf8',
-                mode: 0o600,
-            });
-            splitPaths.push({
-                name: numbered,
-                // The relative path is reported against the FINAL splits dir so
-                // operator-facing output never mentions the staging prefix.
-                path: relative(root, resolve(splitsDir, numbered, 'spec.md')),
-            });
-        }
-        // Manifest staged next to its final path so a single rename swaps
-        // it into place. Same atomicity argument as the splits tree.
-        writeFileSync(manifestTmpPath, formatManifest({
-            prompt,
-            decomposition,
-            rationale,
-            generatedAt,
-            sessionId,
-        }), { encoding: 'utf8', mode: 0o600 });
-        // Final flip — both renames happen after every byte is on disk.
-        // `splits/` is published first because the manifest body references
-        // it; that ordering means a reader who sees the manifest can trust
-        // every path inside it resolves.
-        renameSync(stagingDir, splitsDir);
-        renameSync(manifestTmpPath, manifestFinalPath);
-    }
-    catch (error) {
-        // Best-effort cleanup of staged artifacts so a failed run does not
-        // leave a `splits.tmp-...` carcass behind. We swallow cleanup
-        // errors to keep the original failure as the surfaced cause.
-        try {
-            rmSync(stagingDir, { recursive: true, force: true });
-        }
-        catch {
-            // ignore
-        }
-        try {
-            rmSync(manifestTmpPath, { force: true });
-        }
-        catch {
-            // ignore
-        }
-        throw error;
-    }
-    return {
-        planDir,
-        manifestPath: manifestFinalPath,
-        splitPaths,
-    };
-}
-/**
- * Assert that `candidate` (already absolute via `resolve`) lives inside
- * `parent`. Catches the unlikely-but-possible case where the kebab
- * regex is relaxed in a future PR and a `..` slips through.
- */
-function assertContained(parent, candidate) {
-    const parentWithSep = parent.endsWith(sep) ? parent : `${parent}${sep}`;
-    if (candidate !== parent && !candidate.startsWith(parentWithSep)) {
-        throw new Error(`decomposition path escape detected: ${candidate} is not inside ${parent}`);
-    }
-}
-/**
- * Render the per-component `spec.md`. Sections kept narrow so the file
- * is grep-friendly and the next `pugi plan` session can pick it up
- * with minimal context loading.
- */
-export function formatSpec(component, decomposition, generatedAt) {
-    const dependants = decomposition.components
-        .filter((other) => other.dependsOn.includes(component.name))
-        .map((other) => other.name);
-    const lines = [];
-    lines.push(`# ${component.name}`);
-    lines.push('');
-    lines.push(`> ${component.summary}`);
-    lines.push('');
-    lines.push(`**Generated:** ${generatedAt}`);
-    lines.push('');
-    lines.push('## Depends on');
-    lines.push('');
-    if (component.dependsOn.length === 0) {
-        lines.push('_(none — this component can start in parallel with other roots)_');
-    }
-    else {
-        for (const dep of component.dependsOn)
-            lines.push(`- ${dep}`);
-    }
-    lines.push('');
-    lines.push('## Blocked by this component');
-    lines.push('');
-    if (dependants.length === 0) {
-        lines.push('_(none — this is a leaf component)_');
-    }
-    else {
-        for (const dep of dependants)
-            lines.push(`- ${dep}`);
-    }
-    lines.push('');
-    lines.push('## Spec');
-    lines.push('');
-    lines.push(component.spec.trim());
-    lines.push('');
-    return lines.join('\n');
-}
-export function formatManifest(input) {
-    const { prompt, decomposition, rationale, generatedAt, sessionId } = input;
-    const lines = [];
-    lines.push('# Pugi Plan — Decomposition Manifest');
-    lines.push('');
-    lines.push(`**Prompt:** ${prompt}`);
-    lines.push(`**Session:** ${sessionId}`);
-    lines.push(`**Generated:** ${generatedAt}`);
-    lines.push(`**Component count:** ${decomposition.components.length}`);
-    lines.push('');
-    if (rationale) {
-        lines.push('## Rationale');
-        lines.push('');
-        lines.push(rationale);
-        lines.push('');
-    }
-    lines.push('## Components');
-    lines.push('');
-    for (const [index, component] of decomposition.components.entries()) {
-        const numbered = `${String(index + 1).padStart(2, '0')}-${component.name}`;
-        const deps = component.dependsOn.length === 0 ? '_(no deps)_' : component.dependsOn.join(', ');
-        lines.push(`- **${numbered}** — ${component.summary} (depends on: ${deps})`);
-    }
-    lines.push('');
-    lines.push('## Dependency DAG');
-    lines.push('');
-    lines.push('```mermaid');
-    lines.push('graph TD');
-    for (const component of decomposition.components) {
-        const safeNode = sanitizeMermaidId(component.name);
-        lines.push(` ${safeNode}["${component.name}"]`);
-    }
-    for (const component of decomposition.components) {
-        const toNode = sanitizeMermaidId(component.name);
-        for (const dep of component.dependsOn) {
-            const fromNode = sanitizeMermaidId(dep);
-            lines.push(` ${fromNode} --> ${toNode}`);
-        }
-    }
-    lines.push('```');
-    lines.push('');
-    lines.push('## Execution order');
-    lines.push('');
-    const topo = topologicalOrder(decomposition);
-    const order = topo.order;
-    for (const [index, name] of order.entries()) {
-        lines.push(`${index + 1}. ${name}`);
-    }
-    lines.push('');
-    if (topo.cycleNodes.length > 0) {
-        // Cycle detected — surface explicitly so the operator does not have
-        // to count "fewer lines than components" by hand. We do not refuse
-        // to render the manifest: it still has every spec link plus the
-        // mermaid graph, which actually visualises the cycle.
-        lines.push('## Cycles detected');
-        lines.push('');
-        lines.push(`The dependency graph contains a cycle involving ${topo.cycleNodes.length} component(s). ` +
-            'Re-run `pugi plan --decompose` with a clearer prompt or edit the manifest manually before executing splits in order.');
-        lines.push('');
-        for (const node of topo.cycleNodes) {
-            lines.push(`- ${node}`);
-        }
-        lines.push('');
-    }
-    lines.push('## SPLIT_MANIFEST');
-    lines.push('');
-    lines.push('```json');
-    lines.push(JSON.stringify({
-        schema: 1,
-        sessionId,
-        generatedAt,
-        components: decomposition.components.map((component, index) => ({
-            name: component.name,
-            path: `splits/${String(index + 1).padStart(2, '0')}-${component.name}/spec.md`,
-            summary: component.summary,
-            dependsOn: component.dependsOn,
-        })),
-        executionOrder: order,
-        cycleNodes: topo.cycleNodes,
-    }, null, 2));
-    lines.push('```');
-    lines.push('');
-    return lines.join('\n');
-}
-/**
- * Kahn-style topological sort. The schema already rejected
- * self-references and unknown deps; cycles are still possible (A->B,
- * B->A). On cycle detection we append the remaining nodes verbatim to
- * `order` (so the manifest still renders something useful) and surface
- * the same nodes in `cycleNodes` so the caller can flag the situation
- * loudly.
- */
-export function topologicalOrder(decomposition) {
-    const remaining = new Map();
-    for (const component of decomposition.components) {
-        remaining.set(component.name, new Set(component.dependsOn));
-    }
-    const ordered = [];
-    const cycleNodes = [];
-    while (remaining.size > 0) {
-        const ready = [];
-        for (const [name, deps] of remaining.entries()) {
-            if (deps.size === 0)
-                ready.push(name);
-        }
-        if (ready.length === 0) {
-            // Cycle — append the remaining names in declaration order so the
-            // manifest is still useful, AND surface the same nodes in the
-            // cycle report.
-            for (const component of decomposition.components) {
-                if (remaining.has(component.name)) {
-                    ordered.push(component.name);
-                    cycleNodes.push(component.name);
-                }
-            }
-            break;
-        }
-        // Sort ready bucket alphabetically for determinism: multiple
-        // independent roots otherwise come out in `Map.keys()` insertion
-        // order, which depends on the upstream JSON which we don't control.
-        ready.sort();
-        for (const name of ready) {
-            ordered.push(name);
-            remaining.delete(name);
-            for (const deps of remaining.values()) {
-                deps.delete(name);
-            }
-        }
-    }
-    return { order: ordered, cycleNodes };
-}
-function sanitizeMermaidId(name) {
-    // Mermaid graph node ids must be valid identifiers (no hyphens at
-    // arbitrary positions, no leading digits). We map kebab-case names
-    // to safe ids by replacing hyphens with underscores and prefixing
-    // a leading non-letter with `n_`.
-    const replaced = name.replace(/-/g, '_');
-    return /^[A-Za-z]/.test(replaced) ? replaced : `n_${replaced}`;
-}
-//# sourceMappingURL=plan-decompose.js.map