@thynameisjayvee/alpha-cli 0.1.0

package/dist/core/generator/index.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+import { logger, emit } from '../../utils/logger.js';
+import { writeFile, ensureDir, readJsonFile } from '../../utils/file-system.js';
+import { getAlphaDir, getSpecsDir } from '../../utils/paths.js';
+import { readInputJson } from '../../utils/input.js';
+import { v4 as uuidv4 } from 'uuid';
+const SPEC_TYPES = [
+    'feature',
+    'bugfix',
+    'refactor',
+    'enhancement',
+];
+async function loadContext() {
+    const alphaDir = getAlphaDir();
+    let project = null;
+    let stack = null;
+    try {
+        project = await readJsonFile(`${alphaDir}/project-context.json`);
+    }
+    catch {
+        project = null;
+    }
+    try {
+        stack = await readJsonFile(`${alphaDir}/tech-stack.json`);
+    }
+    catch {
+        stack = null;
+    }
+    return { project, stack };
+}
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-]/g, '');
+}
+/**
+ * Build a Specification from flexible input. The caller (LLM) supplies the
+ * acceptance criteria, dependencies and implementation options; Alpha only
+ * fills structural defaults.
+ */
+function buildSpec(raw) {
+    const now = new Date().toISOString();
+    const type = SPEC_TYPES.includes(raw.type)
+        ? raw.type
+        : 'feature';
+    return {
+        id: raw.id || uuidv4(),
+        title: raw.title || 'Untitled Specification',
+        type,
+        description: raw.description || '',
+        acceptanceCriteria: Array.isArray(raw.acceptanceCriteria)
+            ? raw.acceptanceCriteria
+            : [],
+        dependencies: Array.isArray(raw.dependencies)
+            ? raw.dependencies
+            : [],
+        implementationOptions: Array.isArray(raw.implementationOptions)
+            ? raw.implementationOptions
+            : [],
+        metadata: {
+            createdAt: raw?.metadata?.createdAt || now,
+            updatedAt: now,
+            version: raw?.metadata?.version || '1.0.0',
+            status: raw?.metadata?.status || 'finalized',
+            codebasePath: process.cwd(),
+        },
+    };
+}
+function renderSpecMarkdown(spec) {
+    const criteria = spec.acceptanceCriteria.length > 0
+        ? spec.acceptanceCriteria
+            .map((c) => `- [${c.priority.toUpperCase()}] [${c.layer.toUpperCase()}] ${c.description}`)
+            .join('\n')
+        : '- _TODO: add Given/When/Then acceptance criteria across unit / integration / e2e layers_';
+    const dependencies = spec.dependencies.length > 0
+        ? spec.dependencies
+            .map((d) => `- **${d.name}** (${d.type}) - ${d.status === 'exists' ? '✓' : '⚠'} ${d.description}`)
+            .join('\n')
+        : '- _TODO: list files/modules/services this spec depends on_';
+    const options = spec.implementationOptions.length > 0
+        ? spec.implementationOptions
+            .map((opt, idx) => `### Option ${idx + 1}: ${opt.title}${opt.recommended ? ' ⭐ RECOMMENDED' : ''}\n\n${opt.description}\n\n**Approach:** ${opt.approach}\n\n**Pros:**\n${opt.pros
+            .map((p) => `- ${p}`)
+            .join('\n')}\n\n**Cons:**\n${opt.cons
+            .map((c) => `- ${c}`)
+            .join('\n')}\n\n**Estimated Effort:** ${opt.estimatedEffort}\n\n**Risks:**\n${opt.risks
+            .map((r) => `- ${r}`)
+            .join('\n')}`)
+            .join('\n\n---\n')
+        : '_TODO: propose 2-3 implementation options with pros/cons and a recommendation_';
+    return `# ${spec.title}
+
+**Type:** ${spec.type}  
+**Status:** ${spec.metadata.status}  
+**Version:** ${spec.metadata.version}  
+**Created:** ${spec.metadata.createdAt}
+
+## Description
+
+${spec.description || '_TODO: describe the change_'}
+
+## Dependencies
+
+${dependencies}
+
+## Acceptance Criteria
+
+${criteria}
+
+## Implementation Options
+
+${options}
+
+## Notes
+
+This specification is intentionally flexible. Implementers should review the
+options and choose the best approach based on current context and constraints.
+`;
+}
+async function finalizeSpec(spec) {
+    const specsDir = getSpecsDir();
+    await ensureDir(specsDir);
+    const specPath = `${specsDir}/${spec.id}-${slugify(spec.title)}.md`;
+    await writeFile(specPath, renderSpecMarkdown(spec));
+    logger.success(`Specification saved to ${specPath}`);
+    return specPath;
+}
+function renderAuthoringPrompt() {
+    return [
+        `# Specification Authoring`,
+        ``,
+        `Author a specification, then submit it to Alpha:`,
+        ``,
+        '```bash',
+        `alpha spec --input spec.json`,
+        `# or: echo '<json>' | alpha spec --input -`,
+        '```',
+        ``,
+        `Expected JSON shape:`,
+        '```json',
+        `{`,
+        `  "title": "...",`,
+        `  "type": "feature | bugfix | refactor | enhancement",`,
+        `  "description": "...",`,
+        `  "acceptanceCriteria": [`,
+        `    { "description": "Given..., When..., Then...", "layer": "unit|integration|e2e|manual", "priority": "must|should|could" }`,
+        `  ],`,
+        `  "dependencies": [`,
+        `    { "name": "...", "type": "file|module|service|external|skill", "description": "...", "status": "exists|needs-creation|needs-modification" }`,
+        `  ],`,
+        `  "implementationOptions": [`,
+        `    { "title": "...", "description": "...", "approach": "...", "pros": [], "cons": [], "estimatedEffort": "low|medium|high", "risks": [], "recommended": true }`,
+        `  ]`,
+        `}`,
+        '```',
+        ``,
+        `Tip: pass \`--title "..."\` to have Alpha write an empty skeleton file you`,
+        `can fill in directly under \`.alpha/specs/\`.`,
+    ].join('\n');
+}
+async function specInteractive() {
+    const inquirer = (await import('inquirer')).default;
+    const chalk = (await import('chalk')).default;
+    logger.section('Specification Details');
+    const { specType } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'specType',
+            message: chalk.cyan('What type of specification is this?'),
+            choices: SPEC_TYPES.map((t) => ({ name: t, value: t })),
+        },
+    ]);
+    const { title } = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'title',
+            message: chalk.cyan('Specification title:'),
+            validate: (input) => (input.trim() ? true : 'Title is required'),
+        },
+    ]);
+    const { description } = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'description',
+            message: chalk.cyan('Brief description (1-2 sentences):'),
+            validate: (input) => input.trim() ? true : 'Description is required',
+        },
+    ]);
+    return buildSpec({ type: specType, title, description });
+}
+export async function generateSpec(options = {}) {
+    try {
+        const inputData = await readInputJson(options.input);
+        if (options.interactive) {
+            const spec = await specInteractive();
+            const specPath = await finalizeSpec(spec);
+            emit('spec', { ...spec, path: specPath });
+            return spec;
+        }
+        if (inputData) {
+            const spec = buildSpec(inputData);
+            const specPath = await finalizeSpec(spec);
+            emit('spec', { ...spec, path: specPath });
+            return spec;
+        }
+        // Default emit mode.
+        if (options.title) {
+            const spec = buildSpec({
+                title: options.title,
+                type: options.type,
+                description: options.description,
+            });
+            const specPath = await finalizeSpec(spec);
+            emit('spec', { mode: 'skeleton', path: specPath, spec }, `${renderSpecMarkdown(spec)}\n\nSkeleton written to ${specPath}`);
+            return spec;
+        }
+        emit('spec', { mode: 'authoring' }, renderAuthoringPrompt());
+        return null;
+    }
+    catch (error) {
+        logger.error(`Spec generation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        process.exitCode = 1;
+        return null;
+    }
+}
+// CLI entry point
+if (process.argv[1]?.endsWith('generate.ts')) {
+    generateSpec();
+}
+//# sourceMappingURL=index.js.map

package/dist/core/generator/index.js.map

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

package/dist/core/implementation/index.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Options for the `implement` command.
+ *
+ * Alpha never edits code or spawns agents. `implement` parses the latest review
+ * report and emits a structured plan (per-finding prompts) for the calling LLM
+ * to execute itself. `--verify` re-runs the deterministic checks afterwards.
+ */
+export interface ImplementOptions {
+    /** Run the human-facing interactive selection (inquirer). */
+    interactive?: boolean;
+    /** Comma-separated severities to include, e.g. "critical,high". */
+    severity?: string;
+    /** Comma-separated finding ids (or 1-based indexes) to include. */
+    findings?: string;
+    /** Re-run deterministic checks to see if findings are resolved. */
+    verify?: boolean;
+    /** Delete the report when verification passes for every selected finding. */
+    cleanup?: boolean;
+}
+export declare function runImplementation(options?: ImplementOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/implementation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/implementation/index.ts"],"names":[],"mappings":";AAaA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA4bD,wBAAsB,iBAAiB,CACrC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAqFf"}

package/dist/core/implementation/index.js

@@ -0,0 +1,398 @@
+#!/usr/bin/env node
+import * as path from 'path';
+import { promises as fs } from 'fs';
+import { logger, emit, isJsonMode } from '../../utils/logger.js';
+import { readFile, deleteFile, fileExists } from '../../utils/file-system.js';
+import { getReportsDir } from '../../utils/paths.js';
+async function findLatestReport() {
+    const reportsDir = getReportsDir();
+    try {
+        try {
+            await fs.access(reportsDir);
+        }
+        catch {
+            return null;
+        }
+        const files = await fs.readdir(reportsDir);
+        const mdFiles = files.filter((f) => f.endsWith('.md'));
+        if (mdFiles.length === 0) {
+            return null;
+        }
+        const filesWithStats = await Promise.all(mdFiles.map(async (file) => {
+            const filePath = path.join(reportsDir, file);
+            const stats = await fs.stat(filePath);
+            return { name: file, path: filePath, mtime: stats.mtime };
+        }));
+        filesWithStats.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+        return filesWithStats[0]?.path || null;
+    }
+    catch (error) {
+        logger.warn(`Failed to find latest report: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        return null;
+    }
+}
+async function parseReport(reportPath) {
+    const content = await readFile(reportPath);
+    const filename = path.basename(reportPath);
+    const idMatch = filename.match(/^([a-f0-9-]+)/i);
+    const reportId = idMatch ? idMatch[1] : 'unknown';
+    const { marked } = await import('marked');
+    const tokens = marked.lexer(content);
+    const findings = [];
+    let currentFinding = null;
+    let currentSection = '';
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type === 'heading' && token.depth === 3) {
+            const headingText = 'text' in token ? token.text : '';
+            if (headingText.startsWith('Finding')) {
+                if (currentFinding && currentFinding.title) {
+                    findings.push(currentFinding);
+                }
+                currentFinding = {
+                    id: `finding-${findings.length}`,
+                    title: headingText.replace(/^Finding\s+F?-?\d+:?\s*/i, '').trim(),
+                    description: '',
+                    severity: 'medium',
+                    location: undefined,
+                    dependencies: [],
+                    recommendationOptions: [],
+                };
+                currentSection = '';
+            }
+        }
+        if (currentFinding && token.type === 'paragraph') {
+            const paragraphText = 'text' in token ? token.text : '';
+            if (paragraphText.includes('**Severity:**')) {
+                const severityMatch = paragraphText.match(/\*\*Severity:\*\*\s*(🔴\s*)?(\w+)/i);
+                if (severityMatch && severityMatch[2]) {
+                    currentFinding.severity =
+                        severityMatch[2].toLowerCase();
+                }
+            }
+            if (paragraphText.includes('**Location:**')) {
+                const locationMatch = paragraphText.match(/\*\*Location:\*\*\s*`([^`]+)`/);
+                if (locationMatch) {
+                    const locationParts = locationMatch[1].split(':');
+                    currentFinding.location = {
+                        file: locationParts[0],
+                        line: parseInt(locationParts[1] || '0'),
+                    };
+                }
+            }
+        }
+        if (currentFinding &&
+            currentSection !== 'options' &&
+            token.type === 'paragraph') {
+            const paragraphText = 'text' in token ? token.text : '';
+            if (!paragraphText.includes('**Severity:**') &&
+                !paragraphText.includes('**Location:**') &&
+                !paragraphText.includes('Option')) {
+                currentFinding.description += paragraphText + ' ';
+            }
+        }
+        if (token.type === 'heading' && token.depth === 4) {
+            const headingText = 'text' in token ? token.text : '';
+            if (headingText.toLowerCase().includes('option')) {
+                currentSection = 'options';
+            }
+        }
+        if (currentFinding &&
+            currentSection === 'options' &&
+            token.type === 'list') {
+            const listToken = token;
+            for (const item of listToken.items) {
+                const itemText = 'text' in item ? item.text : '';
+                if (itemText.match(/^\d+\.\s+\*\*(.*?)\*\*/)) {
+                    const titleMatch = itemText.match(/^\d+\.\s+\*\*(.*?)\*\*/);
+                    const title = titleMatch ? titleMatch[1].trim() : 'Unknown Option';
+                    const isRecommended = itemText.includes('⭐') ||
+                        itemText.toLowerCase().includes('recommended');
+                    const effortMatch = itemText.match(/\*\*Estimated Effort:\*\*\s*(\w+)/i);
+                    const effort = effortMatch
+                        ? effortMatch[1].toLowerCase()
+                        : 'medium';
+                    const steps = [];
+                    if ('tokens' in item && item.tokens) {
+                        for (const subToken of item.tokens) {
+                            if (subToken.type === 'list') {
+                                const subList = subToken;
+                                for (const subItem of subList.items) {
+                                    if ('text' in subItem) {
+                                        steps.push(subItem.text.trim());
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    currentFinding.recommendationOptions.push({
+                        id: `opt-${currentFinding.recommendationOptions.length}`,
+                        title,
+                        description: '',
+                        implementationSteps: steps,
+                        estimatedEffort: effort,
+                        risks: [],
+                        recommended: isRecommended,
+                    });
+                }
+            }
+        }
+    }
+    if (currentFinding && currentFinding.title) {
+        findings.push(currentFinding);
+    }
+    return {
+        id: reportId,
+        title: `Review Report: ${reportId}`,
+        reviewTarget: 'codebase',
+        findings,
+        summary: {
+            totalFindings: findings.length,
+            critical: findings.filter((f) => f.severity === 'critical').length,
+            high: findings.filter((f) => f.severity === 'high').length,
+            medium: findings.filter((f) => f.severity === 'medium').length,
+            low: findings.filter((f) => f.severity === 'low').length,
+            info: findings.filter((f) => f.severity === 'info').length,
+        },
+        createdAt: new Date().toISOString(),
+        status: 'ready-for-implementation',
+    };
+}
+/**
+ * Non-interactive finding selection driven by flags.
+ * `--findings` takes precedence over `--severity`; with neither, all are kept.
+ */
+function selectFindingsByFlags(findings, options) {
+    if (options.findings) {
+        const wanted = options.findings
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        return findings.filter((f, idx) => {
+            const oneBasedIndex = String(idx + 1);
+            return wanted.includes(f.id) || wanted.includes(oneBasedIndex);
+        });
+    }
+    if (options.severity) {
+        const wanted = new Set(options.severity
+            .split(',')
+            .map((s) => s.trim().toLowerCase())
+            .filter(Boolean));
+        return findings.filter((f) => wanted.has(f.severity));
+    }
+    return findings;
+}
+async function selectFindingsInteractive(findings) {
+    logger.subSection('Select Findings');
+    if (findings.length === 0) {
+        logger.warn('No findings to implement');
+        return [];
+    }
+    const inquirer = (await import('inquirer')).default;
+    const chalk = (await import('chalk')).default;
+    const { selectionType } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'selectionType',
+            message: chalk.cyan('Which findings would you like to implement?'),
+            choices: [
+                { name: 'All findings', value: 'all' },
+                { name: 'Critical and High only', value: 'critical-high' },
+                { name: 'Custom selection', value: 'custom' },
+            ],
+        },
+    ]);
+    if (selectionType === 'all') {
+        return findings;
+    }
+    if (selectionType === 'critical-high') {
+        return findings.filter((f) => f.severity === 'critical' || f.severity === 'high');
+    }
+    const { selectedIndices } = await inquirer.prompt([
+        {
+            type: 'checkbox',
+            name: 'selectedIndices',
+            message: chalk.cyan('Select findings to implement:'),
+            choices: findings.map((f, idx) => ({
+                name: `[${f.severity.toUpperCase()}] ${f.title}`,
+                value: idx,
+                checked: f.severity === 'critical' || f.severity === 'high',
+            })),
+        },
+    ]);
+    return selectedIndices.map((idx) => findings[idx]);
+}
+/**
+ * Pick a recommendation option for a finding without a human:
+ * prefer the recommended option, otherwise the first available.
+ */
+function pickOption(finding) {
+    if (finding.recommendationOptions.length === 0) {
+        return null;
+    }
+    return (finding.recommendationOptions.find((opt) => opt.recommended) ||
+        finding.recommendationOptions[0]);
+}
+async function pickOptionInteractive(finding) {
+    if (finding.recommendationOptions.length === 0) {
+        logger.warn(`No recommendation options for finding: ${finding.title}`);
+        return null;
+    }
+    const recommended = finding.recommendationOptions.find((opt) => opt.recommended);
+    if (recommended) {
+        logger.info(`Using recommended option for "${finding.title}": ${recommended.title}`);
+        return recommended;
+    }
+    const inquirer = (await import('inquirer')).default;
+    const chalk = (await import('chalk')).default;
+    const { selectedOption } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'selectedOption',
+            message: chalk.cyan(`Select implementation option for "${finding.title}":`),
+            choices: finding.recommendationOptions.map((opt, idx) => ({
+                name: `${opt.title} (${opt.estimatedEffort} effort)`,
+                value: idx,
+            })),
+        },
+    ]);
+    return finding.recommendationOptions[selectedOption];
+}
+/**
+ * Build the prompt the calling LLM should act on to fix a single finding.
+ */
+function generateImplementationPrompt(finding, option) {
+    const promptParts = [
+        `## Task: Fix Code Issue`,
+        ``,
+        `**Issue:** ${finding.title}`,
+        `**Severity:** ${finding.severity}`,
+        `**Description:** ${finding.description}`,
+    ];
+    if (finding.location) {
+        promptParts.push(``, `**Location:**`, `- File: ${finding.location.file || 'Unknown'}`, finding.location.line ? `- Line: ${finding.location.line}` : '');
+    }
+    if (option) {
+        promptParts.push(``, `**Implementation Approach:** ${option.title}`, option.description ? `\n${option.description}` : '', ``, `**Steps:**`, ...option.implementationSteps.map((step, i) => `${i + 1}. ${step}`));
+    }
+    promptParts.push(``, `**Instructions:**`, `- Make the minimal changes needed to fix this issue`, `- Preserve existing code style and formatting`, `- Do not modify unrelated code`, `- After making changes, verify the fix works correctly`, `- Report what changes you made`);
+    return promptParts.filter((line) => line !== '').join('\n');
+}
+/**
+ * Re-run lightweight deterministic checks to see whether a finding still
+ * reproduces. This is a best-effort signal, not a guarantee.
+ */
+async function verifyFindingResolved(finding) {
+    if (finding.title.includes('Console')) {
+        const methodMatch = finding.title.match(/Console\.(\w+)/);
+        if (methodMatch && finding.location?.file) {
+            try {
+                const content = await readFile(finding.location.file);
+                const pattern = new RegExp(`console\\.${methodMatch[1]}\\s*\\(`);
+                return !pattern.test(content);
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    // For findings we cannot deterministically re-check, report "unknown" as
+    // unresolved so the caller does not assume success.
+    return false;
+}
+function renderPlanMarkdown(report, plan) {
+    const lines = [
+        `# Implementation Plan`,
+        ``,
+        `Report: ${report.id}`,
+        `Selected findings: ${plan.length} of ${report.summary.totalFindings}`,
+        ``,
+        `Alpha does not edit code. Work through each task below and apply the`,
+        `changes yourself, then run \`alpha implement --verify\` to check progress.`,
+        ``,
+    ];
+    plan.forEach((item, idx) => {
+        lines.push(`---`, ``, `## ${idx + 1}. ${item.finding.title}`, ``);
+        if (item.verify !== undefined && item.resolved !== undefined) {
+            lines.push(`Verification: ${item.resolved ? 'resolved ✓' : 'still present ⚠'}`, ``);
+        }
+        lines.push(item.prompt, ``);
+    });
+    return lines.join('\n');
+}
+export async function runImplementation(options = {}) {
+    const reportPath = await findLatestReport();
+    if (!reportPath || !(await fileExists(reportPath))) {
+        logger.error('No review report found. Run `alpha review` first.');
+        process.exitCode = 1;
+        return;
+    }
+    logger.section('Implementation');
+    logger.info(`Found report: ${reportPath}`);
+    const report = await parseReport(reportPath);
+    logger.info(`Report contains ${report.summary.totalFindings} finding(s)`);
+    const selectedFindings = options.interactive
+        ? await selectFindingsInteractive(report.findings)
+        : selectFindingsByFlags(report.findings, options);
+    if (selectedFindings.length === 0) {
+        logger.warn('No findings selected for implementation');
+        emit('implement', { report: report.id, plan: [] });
+        return;
+    }
+    const plan = [];
+    for (const finding of selectedFindings) {
+        const option = options.interactive
+            ? await pickOptionInteractive(finding)
+            : pickOption(finding);
+        plan.push({
+            finding,
+            option,
+            prompt: generateImplementationPrompt(finding, option),
+        });
+    }
+    let allResolved = false;
+    if (options.verify) {
+        logger.subSection('Verification');
+        allResolved = true;
+        for (const item of plan) {
+            const resolved = await verifyFindingResolved(item.finding);
+            item.verify = true;
+            item.resolved = resolved;
+            if (resolved) {
+                logger.success(`  ✓ ${item.finding.title}`);
+            }
+            else {
+                logger.warn(`  ⚠ ${item.finding.title} - still present or unverifiable`);
+                allResolved = false;
+            }
+        }
+    }
+    if (options.verify && options.cleanup && allResolved) {
+        await deleteFile(reportPath);
+        logger.success(`Report deleted: ${reportPath}`);
+    }
+    emit('implement', {
+        report: report.id,
+        reportPath,
+        selected: plan.length,
+        verified: options.verify || false,
+        allResolved: options.verify ? allResolved : undefined,
+        plan: plan.map((item) => ({
+            findingId: item.finding.id,
+            title: item.finding.title,
+            severity: item.finding.severity,
+            location: item.finding.location,
+            option: item.option?.title || null,
+            resolved: item.resolved,
+            prompt: item.prompt,
+        })),
+    }, renderPlanMarkdown(report, plan));
+    if (!isJsonMode()) {
+        logger.info('Apply the changes above, then re-run with --verify to confirm.');
+    }
+}
+// CLI entry point
+if (process.argv[1]?.endsWith('index.ts')) {
+    runImplementation();
+}
+//# sourceMappingURL=index.js.map