@planu/cli 4.13.0 → 5.0.0

package/dist/engine/spec-format/markdown-sections.js

@@ -0,0 +1,105 @@
+function markdownLines(content) {
+    const lines = [];
+    let start = 0;
+    while (start < content.length) {
+        const newline = content.indexOf('\n', start);
+        const end = newline === -1 ? content.length : newline + 1;
+        const contentEnd = newline === -1
+            ? end
+            : newline > start && content[newline - 1] === '\r'
+                ? newline - 1
+                : newline;
+        lines.push({ start, contentEnd, end });
+        start = end;
+    }
+    return lines;
+}
+/** Locate one exact markdown section without normalizing or copying source bytes. */
+export function findMarkdownSectionRange(content, headingName) {
+    let selected = null;
+    let fence = null;
+    for (const line of markdownLines(content)) {
+        const text = content.slice(line.start, line.contentEnd);
+        const fenceMatch = /^[ \t]{0,3}(`{3,}|~{3,})/.exec(text);
+        if (fenceMatch?.[1]) {
+            const marker = fenceMatch[1][0];
+            if (fence === null) {
+                fence = { marker, length: fenceMatch[1].length };
+            }
+            else if (fence.marker === marker && fenceMatch[1].length >= fence.length) {
+                fence = null;
+            }
+            continue;
+        }
+        if (fence !== null) {
+            continue;
+        }
+        const heading = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/.exec(text);
+        if (!heading?.[1] || heading[2] === undefined) {
+            continue;
+        }
+        const level = heading[1].length;
+        if (selected !== null && level <= selected.level) {
+            return { ...selected, end: line.start };
+        }
+        if (selected === null && heading[2].trim().toLowerCase() === headingName.trim().toLowerCase()) {
+            selected = {
+                headingStart: line.start,
+                contentStart: line.end,
+                end: content.length,
+                level,
+            };
+        }
+    }
+    return selected;
+}
+/**
+ * Extract the text content under a markdown heading that matches any keyword.
+ */
+export function extractSection(content, ...headingKeywords) {
+    const lines = content.split('\n');
+    let capturing = false;
+    let capturedLevel = 0;
+    const captured = [];
+    for (const line of lines) {
+        const headingMatch = /^(#{1,6})\s+(.+)/.exec(line);
+        if (headingMatch?.[1] !== undefined && headingMatch[2] !== undefined) {
+            const level = headingMatch[1].length;
+            const title = headingMatch[2].toLowerCase();
+            if (capturing && level <= capturedLevel) {
+                break;
+            }
+            if (!capturing && headingKeywords.some((keyword) => title.includes(keyword))) {
+                capturing = true;
+                capturedLevel = level;
+                continue;
+            }
+        }
+        if (capturing) {
+            captured.push(line);
+        }
+    }
+    return captured.length > 0 ? captured.join('\n') : null;
+}
+/** Extract bullet and numbered-list item text from a markdown block. */
+export function extractListItems(content) {
+    const items = [];
+    for (const line of content.split('\n')) {
+        const listMatch = /^\s*[-*+]\s+\[?\s*[xX ]?\s*\]?\s*(.+)/.exec(line);
+        if (listMatch?.[1]) {
+            const item = listMatch[1].trim();
+            if (item.length > 5) {
+                items.push(item);
+            }
+        }
+        const numberedMatch = /^\s*\d+[.)]\s+(.+)/.exec(line);
+        if (numberedMatch?.[1]) {
+            const item = numberedMatch[1].trim();
+            if (item.length > 5) {
+                items.push(item);
+            }
+        }
+    }
+    return items;
+}
+//# sourceMappingURL=markdown-sections.js.map

package/dist/engine/spec-format/read-technical-section.js

@@ -60,11 +60,39 @@ export function extractSectionBody(body, sectionName) {
  * against the masked variant.
  */
 function maskFencedBlocks(body) {
-    return body.replace(/(```|~~~)[\s\S]*?\1/g, (block) => {
-        // Replace every non-newline char with a space so offsets (and line
-        // numbers) are preserved exactly. Keep newlines intact.
-        return block.replace(/[^\n]/g, ' ');
-    });
+    const masked = body.split('');
+    let activeMarker = null;
+    let minimumClosingLength = 0;
+    let lineStart = 0;
+    while (lineStart < body.length) {
+        const newlineIndex = body.indexOf('\n', lineStart);
+        const lineEnd = newlineIndex === -1 ? body.length : newlineIndex;
+        const line = body.slice(lineStart, lineEnd);
+        if (activeMarker === null) {
+            const opening = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+            if (opening !== undefined) {
+                activeMarker = opening[0];
+                minimumClosingLength = opening.length;
+            }
+        }
+        else {
+            const closing = /^ {0,3}(`+|~+)[ \t]*$/.exec(line)?.[1];
+            if (closing?.startsWith(activeMarker) === true && closing.length >= minimumClosingLength) {
+                activeMarker = null;
+                minimumClosingLength = 0;
+            }
+        }
+        if (activeMarker !== null || minimumClosingLength === 0) {
+            const isFenceBoundary = /^ {0,3}(`{3,}|~{3,})/.test(line) || /^ {0,3}(`+|~+)[ \t]*$/.test(line);
+            if (activeMarker !== null || isFenceBoundary) {
+                for (let index = lineStart; index < lineEnd; index += 1) {
+                    masked[index] = ' ';
+                }
+            }
+        }
+        lineStart = newlineIndex === -1 ? body.length : newlineIndex + 1;
+    }
+    return masked.join('');
 }
 function escapeRegex(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/dist/engine/spec-format/technical-md-populator.js

@@ -18,7 +18,7 @@ function extractPathsFromSection(sectionText) {
     return paths;
 }
 function parseSectionedFileLists(body) {
-    const filesSection = /##\s+Files\s+likely\s+to\s+change[\s\S]*?(?=\n##\s|$)/.exec(body);
+    const filesSection = /##\s+Files(?:\s+likely\s+to\s+change)?\s*[\s\S]*?(?=\n##\s|$)/.exec(body);
     const scopedBody = filesSection?.[0] ?? body;
     const createSection = /###\s+Create[\s\S]*?(?=\n###|\n##\s|$)/.exec(scopedBody);
     const modifySection = /###\s+Modify[\s\S]*?(?=\n###|\n##\s|$)/.exec(scopedBody);
@@ -67,7 +67,8 @@ async function categorizeByExistence(paths, projectPath) {
  */
 export async function extractFilesFromSpecBody(specBody, projectPath) {
     const structured = parseSectionedFileLists(specBody);
-    if (structured !== null && (structured.create.length > 0 || structured.modify.length > 0)) {
+    if (structured !== null &&
+        (structured.create.length > 0 || structured.modify.length > 0 || structured.test.length > 0)) {
         return structured;
     }
     const allPaths = [...new Set(Array.from(specBody.matchAll(FILE_PATH_RE), (m) => m[0]))];

package/dist/engine/spec-format/unified-spec-builder.d.ts

@@ -1,3 +1,6 @@
+import type { CanonicalUnifiedSpecInput, UnifiedSpecCandidateValidation } from '../../types/index.js';
+/** Compose the one canonical persisted spec document from already-grounded inputs. */
+export declare function buildCanonicalUnifiedSpecContent(input: CanonicalUnifiedSpecInput): string;
 /**
  * Combine a generated lean spec.md body and a generated lean technical.md body
  * into a single unified spec.md content. The technical body's YAML frontmatter
@@ -10,4 +13,8 @@
  * inject sections the user did not author themselves.
  */
 export declare function buildUnifiedSpecContent(leanSpecBody: string, leanTechnicalBody: string): string;
+/** Pure pre-persistence validation for the complete unified spec candidate. */
+export declare function validateUnifiedSpecCandidate(candidate: string, options?: {
+    groundedFilePaths?: Iterable<string>;
+}): UnifiedSpecCandidateValidation;
 //# sourceMappingURL=unified-spec-builder.d.ts.map

package/dist/engine/spec-format/unified-spec-builder.js

@@ -1,6 +1,44 @@
 // engine/spec-format/unified-spec-builder.ts — SPEC-709/SPEC-1010 Bug C: Build unified spec.md.
 // Closes the SPEC-630 residue: every new spec is born unified, never written as a
 // two-file spec.md + technical.md pair only to be merged on the next list_specs run.
+import { stripFrontmatter } from '../frontmatter-parser.js';
+const REQUIRED_SECTIONS = [
+    'Problem',
+    'Goal',
+    'Technical',
+    'Implementation Contract',
+    'Acceptance Criteria',
+    'Files',
+    'Out of scope',
+];
+/** Compose the one canonical persisted spec document from already-grounded inputs. */
+export function buildCanonicalUnifiedSpecContent(input) {
+    const frontmatter = /^---\n[\s\S]*?\n---\n?/.exec(input.leanSpecBody)?.[0]?.trimEnd() ?? '';
+    const source = input.sourceDescription.replace(/\r\n/g, '\n').trim();
+    const explicitProblem = extractTopLevelSectionBody(source, 'Problem');
+    const proseBeforeHeading = source.split(/^##[ \t]+\S.*$/m, 1)[0]?.trim() ?? '';
+    const problem = firstNonEmpty(explicitProblem, proseBeforeHeading, source);
+    const explicitGoal = extractTopLevelSectionBody(source, 'Goal');
+    const goal = firstNonEmpty(explicitGoal, firstSentence(problem), problem);
+    const explicitTechnical = extractTopLevelSectionBody(source, 'Technical');
+    const generatedNotes = extractTopLevelSectionBody(input.technicalBody, 'Implementation Notes');
+    const technical = firstNonEmpty(explicitTechnical, generatedNotes, 'Implement only the grounded ownership and observable behavior declared by this contract.');
+    const acceptance = extractExecutableCriteria(source, input.criteria);
+    const explicitOutOfScope = extractTopLevelSectionBody(source, 'Out of scope');
+    const outOfScope = input.outOfScope.length > 0
+        ? input.outOfScope.map((item) => `- ${item}`).join('\n')
+        : (explicitOutOfScope ?? '');
+    const sections = [
+        renderSection('Problem', problem),
+        renderSection('Goal', goal),
+        renderSection('Technical', technical),
+        input.implementationContract.trim(),
+        renderSection('Acceptance Criteria', acceptance),
+        renderSection('Files', renderOwnedFiles(input.files)),
+        renderSection('Out of scope', outOfScope),
+    ];
+    return `${frontmatter ? `${frontmatter}\n\n` : ''}${sections.join('\n\n')}\n`;
+}
 /**
  * Combine a generated lean spec.md body and a generated lean technical.md body
  * into a single unified spec.md content. The technical body's YAML frontmatter
@@ -78,4 +116,168 @@ function extractSection(body, sectionName) {
     const end = next ? next.index : body.length;
     return body.slice(start, end).trimEnd();
 }
+/** Pure pre-persistence validation for the complete unified spec candidate. */
+// eslint-disable-next-line max-lines-per-function -- validation order mirrors the public issue contract
+export function validateUnifiedSpecCandidate(candidate, options = {}) {
+    const body = stripFrontmatter(candidate.replace(/\r\n/g, '\n'));
+    const scannable = maskFencedAndQuotedText(body);
+    const issues = [];
+    const positions = new Map();
+    for (const section of REQUIRED_SECTIONS) {
+        const pattern = new RegExp(`^##[ \\t]+${escapeRegex(section)}[ \\t]*$`, 'gim');
+        positions.set(section, Array.from(scannable.matchAll(pattern), (match) => match.index));
+    }
+    for (const section of REQUIRED_SECTIONS) {
+        const matches = positions.get(section) ?? [];
+        if (matches.length === 0) {
+            issues.push({
+                code: 'MISSING_REQUIRED_SECTION',
+                section,
+                message: `Missing required top-level section: ${section}`,
+            });
+        }
+        else if (matches.length > 1) {
+            issues.push({
+                code: 'DUPLICATE_REQUIRED_SECTION',
+                section,
+                message: `Required top-level section appears more than once: ${section}`,
+            });
+        }
+    }
+    const observedOrder = REQUIRED_SECTIONS.flatMap((section) => (positions.get(section) ?? []).slice(0, 1).map((position) => ({ section, position }))).sort((left, right) => left.position - right.position);
+    if (observedOrder.length === REQUIRED_SECTIONS.length &&
+        observedOrder.some((entry, index) => entry.section !== REQUIRED_SECTIONS[index])) {
+        issues.push({
+            code: 'MISORDERED_REQUIRED_SECTION',
+            message: `Required sections must appear in canonical order: ${REQUIRED_SECTIONS.join(' -> ')}`,
+        });
+    }
+    const embedded = findEmbeddedRequiredSections(body);
+    for (const section of embedded) {
+        issues.push({
+            code: 'EMBEDDED_REQUIRED_SECTION',
+            section,
+            message: `Required section heading is embedded in quoted, fenced, or nested content: ${section}`,
+        });
+    }
+    if (/\b(?:Needs decision|TBD|TODO)\b/i.test(scannable)) {
+        issues.push({
+            code: 'UNRESOLVED_CONTRACT_PLACEHOLDER',
+            message: 'Unified candidate contains an unresolved contract placeholder.',
+        });
+    }
+    const acceptanceSection = extractTopLevelSectionBody(scannable, 'Acceptance Criteria');
+    if (acceptanceSection === null ||
+        !/\bGIVEN\b[\s\S]*\bWHEN\b[\s\S]*\bTHEN\b/i.test(acceptanceSection)) {
+        issues.push({
+            code: 'MISSING_EXECUTABLE_CRITERIA',
+            section: 'Acceptance Criteria',
+            message: 'Acceptance Criteria must contain executable GIVEN/WHEN/THEN behavior.',
+        });
+    }
+    if (options.groundedFilePaths !== undefined) {
+        const grounded = new Set(options.groundedFilePaths);
+        const filesSection = extractTopLevelSectionBody(scannable, 'Files') ?? '';
+        const ownedPaths = Array.from(filesSection.matchAll(/^[ \t]*-[ \t]+`?([^`\r\n]+?)`?[ \t]*$/gm), (match) => match[1]?.trim() ?? '').filter((path) => path.length > 0 && path !== 'None.');
+        for (const path of [...new Set(ownedPaths)]) {
+            if (!grounded.has(path)) {
+                issues.push({
+                    code: 'UNGROUNDED_FILE_OWNERSHIP',
+                    path,
+                    message: `File ownership is not grounded in explicit input or project evidence: ${path}`,
+                });
+            }
+        }
+    }
+    return { valid: issues.length === 0, issues };
+}
+function maskFencedAndQuotedText(body) {
+    const lines = body.split('\n');
+    let fence = null;
+    return lines
+        .map((line) => {
+        const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        if (marker) {
+            const kind = marker[0];
+            fence = fence === null ? kind : fence === kind ? null : fence;
+            return ' '.repeat(line.length);
+        }
+        if (fence !== null || /^\s*>/.test(line)) {
+            return ' '.repeat(line.length);
+        }
+        return line;
+    })
+        .join('\n');
+}
+function findEmbeddedRequiredSections(body) {
+    const embedded = new Set();
+    let fence = null;
+    for (const line of body.split('\n')) {
+        const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+        if (marker) {
+            const kind = marker[0];
+            fence = fence === null ? kind : fence === kind ? null : fence;
+            continue;
+        }
+        const candidate = (fence !== null ? line : line.replace(/^\s*>\s?/, '')).trim();
+        if (fence === null && !/^\s*>/.test(line) && !/^#{3,6}\s+/.test(line)) {
+            continue;
+        }
+        const title = /^#{2,6}\s+(.+?)\s*$/.exec(candidate)?.[1];
+        const canonical = REQUIRED_SECTIONS.find((section) => title?.toLowerCase() === section.toLowerCase());
+        if (canonical) {
+            embedded.add(canonical);
+        }
+    }
+    return [...embedded];
+}
+function extractTopLevelSectionBody(body, section) {
+    const heading = new RegExp(`^##[ \\t]+${escapeRegex(section)}[ \\t]*$`, 'mi').exec(body);
+    if (!heading) {
+        return null;
+    }
+    const start = heading.index + heading[0].length;
+    const rest = body.slice(start);
+    const next = /^##[ \t]+\S.*$/m.exec(rest);
+    return rest.slice(0, next?.index ?? rest.length).trim();
+}
+function renderSection(title, body) {
+    return `## ${title}\n\n${body.trim()}`;
+}
+function firstNonEmpty(...values) {
+    return (values.find((value) => value !== undefined && value !== null && value.length > 0) ?? '');
+}
+function firstSentence(text) {
+    const sentence = text
+        .split(/(?<=[.!?])\s+/)
+        .map((part) => part.trim())
+        .find((part) => part.length > 0 && !part.startsWith('#'));
+    return sentence ?? null;
+}
+function extractExecutableCriteria(source, criteria) {
+    const explicit = /\bGIVEN\b[\s\S]*?(?=(?:\n##|\bFILES:|\bFUNCTIONS:|\bTEST:|$))/i
+        .exec(source)?.[0]
+        ?.trim()
+        .replace(/[.\s]+$/, '.');
+    if (explicit) {
+        return `- ${explicit}`;
+    }
+    return criteria
+        .map((criterion) => `- GIVEN the requested change is implemented WHEN the behavior is exercised THEN ${criterion.text}`)
+        .join('\n');
+}
+function renderOwnedFiles(files) {
+    const sections = [];
+    for (const [title, entries] of [
+        ['Create', files.create],
+        ['Modify', files.modify],
+        ['Test', files.test],
+    ]) {
+        sections.push(`### ${title}`);
+        sections.push('');
+        sections.push(...(entries.length > 0 ? entries.map((entry) => `- \`${entry.path}\``) : ['- None.']));
+        sections.push('');
+    }
+    return sections.join('\n').trim();
+}
 //# sourceMappingURL=unified-spec-builder.js.map

package/dist/engine/spec-generator/api-key-resolver.d.ts

@@ -1,4 +1,4 @@
 export declare class ApiKeyResolver {
-    resolveAnthropicKey(projectPath: string): Promise<string | undefined>;
+    resolveAnthropicKey(_projectPath: string): Promise<string | undefined>;
 }
 //# sourceMappingURL=api-key-resolver.d.ts.map

package/dist/engine/spec-generator/api-key-resolver.js

@@ -1,31 +1,10 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
 export class ApiKeyResolver {
-    async resolveAnthropicKey(projectPath) {
+    resolveAnthropicKey(_projectPath) {
         const envKey = process.env.PLANU_ANTHROPIC_API_KEY ?? process.env.ANTHROPIC_API_KEY;
         if (envKey?.trim()) {
-            return envKey.trim();
+            return Promise.resolve(envKey.trim());
         }
-        for (const file of [
-            join(projectPath, 'src/config/api-keys.json'),
-            join(projectPath, '.planu/api-keys.json'),
-        ]) {
-            const key = await readKeyFile(file);
-            if (key) {
-                return key;
-            }
-        }
-        return undefined;
-    }
-}
-async function readKeyFile(path) {
-    try {
-        const parsed = JSON.parse(await readFile(path, 'utf-8'));
-        const key = parsed.anthropic?.apiKey;
-        return key?.trim() ? key.trim() : undefined;
-    }
-    catch {
-        return undefined;
+        return Promise.resolve(undefined);
     }
 }
 //# sourceMappingURL=api-key-resolver.js.map

package/dist/engine/spec-generators/issue-extractor.js

@@ -1,8 +1,14 @@
-// engine/spec-generators/issue-extractor.ts — SPEC-472: Convert ExtractedIssue to spec draft
-// Per-source extractors live in subdirectory but are loaded dynamically when needed.
+import { technologyValue } from '../technology-registry.js';
 const FRONTEND_LABELS = new Set(['ui', 'ux', 'frontend', 'design', 'css', 'component']);
 const BACKEND_LABELS = new Set(['api', 'backend', 'database', 'sql', 'server', 'rpc']);
-const INFRA_LABELS = new Set(['infra', 'ci', 'cd', 'deploy', 'docker', 'kubernetes']);
+const INFRA_LABELS = new Set([
+    'infra',
+    'ci',
+    'cd',
+    'deploy',
+    technologyValue('technology-docker-d548c5'),
+    technologyValue('technology-kubernetes-94abcb'),
+]);
 const BUGFIX_LABELS = new Set(['bug', 'bugfix', 'fix', 'defect', 'broken']);
 const DOCS_LABELS = new Set(['docs', 'documentation', 'readme']);
 const REFACTOR_LABELS = new Set(['refactor', 'cleanup', 'tech-debt', 'rewrite']);

package/dist/engine/spec-migrator/canonical-deduplicator.d.ts

@@ -0,0 +1,18 @@
+import type { CanonicalRepairManifest, CanonicalRepairPlan, CanonicalRepairRawStore, RepairCanonicalStoreInput } from '../../types/index.js';
+declare function digest(value: Buffer | string): string;
+declare function isContained(parent: string, child: string): boolean;
+declare function artifactPath(projectId: string, artifactId: string): string;
+declare function parseRawStore(raw: Buffer): CanonicalRepairRawStore;
+/** Pure planner. It does not read or write the canonical store. */
+export declare function buildCanonicalRepairPlan(raw: Buffer, manifest: CanonicalRepairManifest, manifestDigest?: string, requestedProjectId?: string): CanonicalRepairPlan;
+/** Runs dry-run or the explicitly authorized, lock-protected repair. */
+export declare function repairDuplicateSpecIds(input: RepairCanonicalStoreInput): Promise<CanonicalRepairPlan>;
+export declare function rollbackCanonicalRepair(projectId: string, receiptPath: string): Promise<void>;
+export declare const CANONICAL_DEDUPLICATOR_INTERNALS: {
+    digest: typeof digest;
+    parseRawStore: typeof parseRawStore;
+    artifactPath: typeof artifactPath;
+    isContained: typeof isContained;
+};
+export {};
+//# sourceMappingURL=canonical-deduplicator.d.ts.map