@pugi/cli 0.1.0-beta.4 → 0.1.0-beta.41

package/dist/runtime/plan-decompose.js

@@ -0,0 +1,531 @@
+import { mkdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+/**
+ * α6.8 `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

package/dist/runtime/version.js

@@ -0,0 +1,65 @@
+/**
+ * Pugi CLI ↔ admin-api version handshake — shared constants.
+ *
+ * The CLI declares its installed version on every outbound request to
+ * the admin-api so the server can enforce a minClientVersion floor and
+ * surface a soft-warn for stale-but-allowed installs. See ADR-225 and
+ * `apps/admin-api/src/runtime/version.contract.ts` for the server side.
+ *
+ * # Why the constants live here, not in `@pugi/sdk`
+ *
+ * The SDK ships to customers as part of the public npm package; bumping
+ * a header name there would force a coupled CLI ↔ SDK release. Keeping
+ * the constants in the CLI gives us room to evolve the handshake
+ * without coupling the SDK's release cadence to it.
+ */
+/**
+ * Defensive semver sanitizer — single source of truth for the
+ * `0.0.0-unknown` fallback when a partially-published pnpm release
+ * leaks `workspace:*` into the version literal. `runtime/cli.ts`
+ * re-exports this under its `__test__` surface so the existing
+ * cli.ts test corpus keeps working with zero churn.
+ *
+ * Lives here (not in cli.ts) because the version handshake interceptor
+ * needs the same guarantee without pulling in the heavyweight cli.ts
+ * module graph during transport bootstrap.
+ */
+export function sanitizeSemver(raw) {
+    if (typeof raw !== 'string')
+        return '0.0.0-unknown';
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return '0.0.0-unknown';
+    const stripped = trimmed.replace(/^(workspace:|npm:|file:)/, '');
+    if (/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(stripped)) {
+        return stripped;
+    }
+    return '0.0.0-unknown';
+}
+/**
+ * Installed CLI version — single source of truth for the handshake
+ * header value. Mirrors the literal in `runtime/cli.ts` (intentional
+ * duplication because the cli.ts module pulls in Ink + half the CLI
+ * surface and the transport interceptor must remain side-effect-free
+ * during import). When bumping the CLI version BOTH literals must be
+ * updated; the release smoke-test (`pack:smoke`) verifies they agree.
+ */
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.41');
+/**
+ * Outbound: the CLI's installed semver. Read at request time by
+ * `version-interceptor.ts` and injected on every `fetch` call.
+ */
+export const PUGI_CLI_VERSION_HEADER = 'X-Pugi-Cli-Version';
+/**
+ * Inbound: the server's recommendation for which CLI version operators
+ * should be on. Surfaces through the UpdateBanner alongside the npm
+ * registry poll (the higher of the two wins).
+ */
+export const PUGI_CLI_UPGRADE_RECOMMENDED_HEADER = 'X-Pugi-Cli-Upgrade-Recommended';
+/**
+ * Inbound: server's own admin-api version. Useful for diagnostics
+ * (`pugi doctor --json`) but no enforcement logic keys off it — server
+ * drift between admin-api releases is normal during rolling deploys.
+ */
+export const PUGI_SERVER_VERSION_HEADER = 'X-Pugi-Server-Version';
+//# sourceMappingURL=version.js.map