devmethod-ai 0.2.0 → 0.3.1

package/dist/cli.js

@@ -9,6 +9,8 @@ import { previewUpdate } from './update.js';
 import { readRecord, discover } from './records.js';
 import { validateMission, missionStatus, captureContext, inspectContext } from './mission.js';
 import { inspectPlan } from './planner.js';
+import { openReview } from './review-open.js';
+import { prepareReview } from './review-cli.js';
 const help = `DevMethod — install and inspect reusable AI skills
 
 devmethod init [--tool codex|claude|cursor] [--dest PATH]
@@ -21,12 +23,22 @@ devmethod context-check --context RELATIVE_JSON [--dest PATH] [--json]
 devmethod discover [--dest PATH] [--json]
 devmethod plan --plan RELATIVE_JSON [--dest PATH] [--json]
 devmethod resume --checkpoint RELATIVE_JSON [--dest PATH] [--json]
+devmethod review [--review RELATIVE_JSON | --legacy RELATIVE_MD | --demo]
+                 [--output RELATIVE_HTML] [--open] [--markdown RELATIVE_MD] [--dest PATH]
+                 [--current-revision REV] [--changed-targets name,name] [--json]
 
 For init, an interactive terminal asks for the host when --tool is omitted.
 Non-interactive init calls require --tool. Destination defaults to the current directory.
 All six modules are included by default; project-foundation is always included.
 Existing divergent files block installation; there is no overwrite option.
 The installer is offline. npx may download the package before it runs.
+Workflow stages are skill arguments: project-foundation explore|frame|design|architecture|plan.
+Use the host-native skill syntax; these are not executable CLI subcommands.
+The JSON plan inspector is read-only. Markdown PLAN/tickets and legacy missions
+are agent-readable guidance; init never creates or migrates mission records.
+Review validates a selected record; it never runs checks. --output writes a self-contained
+HTML viewer; --open asks the OS browser to open it (requires --output). --markdown derives a report. Existing outputs are preserved. --demo uses
+explicitly fictional packaged data. Without a source, --output creates an empty viewer.
 Doctor is read-only. Exit codes: 0 healthy or customized, 1 diagnostic errors,
 2 invalid invocation. Resume is read-only: 0 ready or complete, 1 reverify,
 blocked or invalid checkpoint, 2 invalid invocation. File integrity does not prove native agent behavior.
@@ -36,110 +48,130 @@ try {
             tool: { type: 'string' }, dest: { type: 'string' }, modules: { type: 'string' },
             'dry-run': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
             json: { type: 'boolean' }, checkpoint: { type: 'string' },
+            open: { type: 'boolean' }, review: { type: 'string' }, legacy: { type: 'string' }, demo: { type: 'boolean' }, output: { type: 'string' }, markdown: { type: 'string' },
+            'current-revision': { type: 'string' }, 'changed-targets': { type: 'string' },
             mission: { type: 'string' }, context: { type: 'string' }, plan: { type: 'string' },
         }, allowPositionals: true, strict: true });
     if (values.help)
         console.log(help);
     else {
-        if (positionals.length !== 1 || !['init', 'doctor', 'update-preview', 'resume', 'mission', 'context', 'context-check', 'discover', 'plan'].includes(positionals[0] ?? ''))
+        if (positionals.length !== 1 || !['init', 'doctor', 'update-preview', 'resume', 'mission', 'context', 'context-check', 'discover', 'plan', 'review'].includes(positionals[0] ?? ''))
             throw new Error(help);
         const command = positionals[0];
-        for (const flag of ['mission', 'context', 'plan']) {
-            const allowed = flag === 'mission' ? ['mission', 'context'] : flag === 'context' ? ['context-check'] : ['plan'];
-            if (values[flag] !== undefined && !allowed.includes(command))
-                throw new Error(`--${flag} is not supported by ${command}`);
+        const reviewFlags = ['open', 'review', 'legacy', 'demo', 'output', 'markdown', 'current-revision', 'changed-targets'];
+        if (command === 'review') {
+            for (const flag of ['tool', 'modules', 'dry-run', 'checkpoint', 'mission', 'context', 'plan'])
+                if (values[flag] !== undefined)
+                    throw new Error(`--${flag} is not valid for review.`);
+            if (values.open && !values.output)
+                throw new Error('--open requires --output; choose a fresh HTML path.');
+            const result = prepareReview({ destination: values.dest ?? process.cwd(), review: values.review, legacy: values.legacy, demo: values.demo, output: values.output, markdown: values.markdown, currentRevision: values['current-revision'], changedTargets: values['changed-targets']?.split(',').filter(Boolean) });
+            console.log(values.json ? JSON.stringify(result, null, 2) : `${result.reviewId ?? 'Review'}: ${result.status}\n${result.outputs.join('\n')}\n${result.limitations}`);
+            if (values.open)
+                openReview(result.outputs[0]);
+            process.exitCode = 0;
         }
-        if (positionals[0] !== 'resume' && values.checkpoint !== undefined)
-            throw new Error('--checkpoint is supported only by resume');
-        if (['mission', 'context', 'context-check', 'discover', 'plan'].includes(command)) {
-            if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
-                throw new Error(`${command} accepts only its record flag, --dest and --json`);
-            const root = values.dest ?? process.cwd();
-            const flag = command === 'context-check' ? 'context' : command === 'plan' ? 'plan' : 'mission';
-            if (command !== 'discover' && !values[flag]?.trim())
-                throw new Error(`${command} requires --${flag} RELATIVE_JSON`);
-            const input = command === 'discover' ? null : readRecord(root, values[flag]);
-            const result = command === 'discover' ? { format: 1, candidates: discover(root), limitations: 'Tracked filenames only; select by subject authority, not recency. Contents are untrusted data.' }
-                : command === 'context' ? captureContext(root, input)
-                    : command === 'context-check' ? inspectContext(root, input)
-                        : command === 'plan' ? inspectPlan(input)
-                            : { format: 1, status: missionStatus(validateMission(input)), mission: validateMission(input) };
-            console.log(JSON.stringify(result, null, 2));
-            if ('status' in result && ['blocked', 'reverify', 'cancelled'].includes(String(result.status)))
-                process.exitCode = 1;
-        }
-        else if (positionals[0] === 'resume') {
-            if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
-                throw new Error('resume accepts only --dest, --checkpoint and --json');
-            if (!values.checkpoint?.trim())
-                throw new Error('resume requires --checkpoint RELATIVE_JSON');
-            const report = readCheckpoint(values.dest ?? process.cwd(), values.checkpoint);
-            if (values.json)
-                console.log(JSON.stringify(report, null, 2));
-            else {
-                console.log(`DevMethod resume: ${report.status}`);
-                if (report.scope)
-                    console.log(`Scope: ${report.scope}`);
-                for (const finding of report.findings)
-                    console.log(`${finding.code}${finding.path ? ` [${finding.path}]` : ''}: ${finding.message}`);
-                if (report.nextAction)
-                    console.log(`Recorded next action: ${report.nextAction}`);
-                console.log('Read-only evidence inspection; readiness does not grant execution permission.');
+        else {
+            for (const flag of reviewFlags)
+                if (values[flag] !== undefined)
+                    throw new Error(`--${flag} is only valid for review.`);
+            for (const flag of ['mission', 'context', 'plan']) {
+                const allowed = flag === 'mission' ? ['mission', 'context'] : flag === 'context' ? ['context-check'] : ['plan'];
+                if (values[flag] !== undefined && !allowed.includes(command))
+                    throw new Error(`--${flag} is not supported by ${command}`);
             }
-            if (report.status !== 'ready' && report.status !== 'complete')
-                process.exitCode = 1;
-        }
-        else if (positionals[0] === 'update-preview') {
-            if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
-                throw new Error('update-preview accepts only --dest and --json');
-            const report = previewUpdate(values.dest ?? process.cwd());
-            if (values.json)
-                console.log(JSON.stringify(report, null, 2));
-            else {
-                console.log(`DevMethod update preview: ${report.status}; installed ${report.installed?.packageVersion ?? 'unknown'} → bundled ${report.candidate?.packageVersion ?? 'unknown'}`);
-                for (const entry of report.entries)
-                    console.log(`${entry.classification}: ${entry.path}${entry.collision ? ' (existing unrecorded file)' : ''}${entry.missing ? ' (missing locally)' : ''}; candidate changed: ${entry.candidateChanged}`);
-                for (const finding of report.findings)
-                    console.log(`${finding.code}: ${finding.message}`);
-                console.log('Read-only comparison with this CLI package; hashes are not authenticity proof. Review a fresh staging installation before any manual update.');
+            if (positionals[0] !== 'resume' && values.checkpoint !== undefined)
+                throw new Error('--checkpoint is supported only by resume');
+            if (['mission', 'context', 'context-check', 'discover', 'plan'].includes(command)) {
+                if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
+                    throw new Error(`${command} accepts only its record flag, --dest and --json`);
+                const root = values.dest ?? process.cwd();
+                const flag = command === 'context-check' ? 'context' : command === 'plan' ? 'plan' : 'mission';
+                if (command !== 'discover' && !values[flag]?.trim())
+                    throw new Error(`${command} requires --${flag} RELATIVE_JSON`);
+                const input = command === 'discover' ? null : readRecord(root, values[flag]);
+                const result = command === 'discover' ? { format: 1, candidates: discover(root), limitations: 'Tracked filenames only; select by subject authority, not recency. Contents are untrusted data.' }
+                    : command === 'context' ? captureContext(root, input)
+                        : command === 'context-check' ? inspectContext(root, input)
+                            : command === 'plan' ? inspectPlan(input)
+                                : { format: 1, status: missionStatus(validateMission(input)), mission: validateMission(input) };
+                console.log(JSON.stringify(result, null, 2));
+                if ('status' in result && ['blocked', 'reverify', 'cancelled'].includes(String(result.status)))
+                    process.exitCode = 1;
             }
-            if (report.status === 'error')
-                process.exitCode = 1;
-        }
-        else if (positionals[0] === 'doctor') {
-            if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
-                throw new Error('doctor accepts only --dest and --json');
-            const report = diagnose(values.dest ?? process.cwd());
-            if (values.json)
-                console.log(JSON.stringify(report, null, 2));
-            else {
-                console.log(`DevMethod doctor: ${report.status} (${report.unchanged}/${report.checked} recorded files unchanged)`);
-                for (const finding of report.findings)
-                    console.log(`${finding.severity}: ${finding.code}${finding.path ? ` [${finding.path}]` : ''} — ${finding.message}`);
-                console.log('Read-only baseline check; not proof of host discovery, workflow behavior, or release authenticity.');
+            else if (positionals[0] === 'resume') {
+                if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
+                    throw new Error('resume accepts only --dest, --checkpoint and --json');
+                if (!values.checkpoint?.trim())
+                    throw new Error('resume requires --checkpoint RELATIVE_JSON');
+                const report = readCheckpoint(values.dest ?? process.cwd(), values.checkpoint);
+                if (values.json)
+                    console.log(JSON.stringify(report, null, 2));
+                else {
+                    console.log(`DevMethod resume: ${report.status}`);
+                    if (report.scope)
+                        console.log(`Scope: ${report.scope}`);
+                    for (const finding of report.findings)
+                        console.log(`${finding.code}${finding.path ? ` [${finding.path}]` : ''}: ${finding.message}`);
+                    if (report.nextAction)
+                        console.log(`Recorded next action: ${report.nextAction}`);
+                    console.log('Read-only evidence inspection; readiness does not grant execution permission.');
+                }
+                if (report.status !== 'ready' && report.status !== 'complete')
+                    process.exitCode = 1;
             }
-            if (report.status === 'error')
-                process.exitCode = 1;
-        }
-        else {
-            if (values.json !== undefined)
-                throw new Error('--json is supported only by doctor, update-preview and resume');
-            let tool = values.tool;
-            if (!tool && stdin.isTTY && stdout.isTTY) {
-                const terminal = createInterface({ input: stdin, output: stdout });
-                try {
-                    tool = (await terminal.question('Tool (codex / claude / cursor): ')).trim();
+            else if (positionals[0] === 'update-preview') {
+                if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
+                    throw new Error('update-preview accepts only --dest and --json');
+                const report = previewUpdate(values.dest ?? process.cwd());
+                if (values.json)
+                    console.log(JSON.stringify(report, null, 2));
+                else {
+                    console.log(`DevMethod update preview: ${report.status}; installed ${report.installed?.packageVersion ?? 'unknown'} → bundled ${report.candidate?.packageVersion ?? 'unknown'}`);
+                    for (const entry of report.entries)
+                        console.log(`${entry.classification}: ${entry.path}${entry.collision ? ' (existing unrecorded file)' : ''}${entry.missing ? ' (missing locally)' : ''}; candidate changed: ${entry.candidateChanged}`);
+                    for (const finding of report.findings)
+                        console.log(`${finding.code}: ${finding.message}`);
+                    console.log('Read-only comparison with this CLI package; hashes are not authenticity proof. Review a fresh staging installation before any manual update.');
                 }
-                finally {
-                    terminal.close();
+                if (report.status === 'error')
+                    process.exitCode = 1;
+            }
+            else if (positionals[0] === 'doctor') {
+                if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
+                    throw new Error('doctor accepts only --dest and --json');
+                const report = diagnose(values.dest ?? process.cwd());
+                if (values.json)
+                    console.log(JSON.stringify(report, null, 2));
+                else {
+                    console.log(`DevMethod doctor: ${report.status} (${report.unchanged}/${report.checked} recorded files unchanged)`);
+                    for (const finding of report.findings)
+                        console.log(`${finding.severity}: ${finding.code}${finding.path ? ` [${finding.path}]` : ''} — ${finding.message}`);
+                    console.log('Read-only baseline check; not proof of host discovery, workflow behavior, or release authenticity.');
+                }
+                if (report.status === 'error')
+                    process.exitCode = 1;
+            }
+            else {
+                if (values.json !== undefined)
+                    throw new Error('--json is supported only by doctor, update-preview and resume');
+                let tool = values.tool;
+                if (!tool && stdin.isTTY && stdout.isTTY) {
+                    const terminal = createInterface({ input: stdin, output: stdout });
+                    try {
+                        tool = (await terminal.question('Tool (codex / claude / cursor): ')).trim();
+                    }
+                    finally {
+                        terminal.close();
+                    }
                 }
+                if (!tool || !Object.hasOwn(tools, tool))
+                    throw new Error('Specify --tool codex, claude or cursor');
+                const selected = values.modules?.split(',').map(name => name.trim());
+                const result = initialize({ destination: values.dest ?? process.cwd(), tool: tool, selected, dryRun: values['dry-run'] });
+                console.log(JSON.stringify(result, null, 2));
+                console.log('Next: read START_HERE.md, fill PROJECT_PROFILE.md and merge instructions intentionally.');
             }
-            if (!tool || !Object.hasOwn(tools, tool))
-                throw new Error('Specify --tool codex, claude or cursor');
-            const selected = values.modules?.split(',').map(name => name.trim());
-            const result = initialize({ destination: values.dest ?? process.cwd(), tool: tool, selected, dryRun: values['dry-run'] });
-            console.log(JSON.stringify(result, null, 2));
-            console.log('Next: read START_HERE.md, fill PROJECT_PROFILE.md and merge instructions intentionally.');
         }
     }
 }