spec-canon 0.1.2 → 0.1.4

package/README.md

@@ -66,14 +66,34 @@ npx spec-canon --help
 → 阅读 [guide/04_new_project_sop.md](docs/guide/04_new_project_sop.md)，然后使用 `spec-canon prompt guide` 查看决策树
 
 ### 我要在已有项目中开发新需求
-→ 使用 `spec-canon prompt list --stage daily` 查看日常提示词，按 Step 0 → Step 5 顺序执行
+→ 先运行 `spec-canon change start --goal ...` 建立 active change，再按 Step 0 → Step 5 执行
 
 ### 我要为已有项目引入 SDD
 → 阅读 [guide/05_iterative_project_sop.md](docs/guide/05_iterative_project_sop.md) 的冷启动策略，然后使用 `spec-canon prompt list --stage iterative`
 
+### 我要给已初始化项目补齐新版本骨架
+→ 运行 `spec-canon sync`，只补缺失文件，不覆盖已有内容
+
+## 常用命令
+
+```bash
+spec-canon init
+spec-canon init --domain auth
+spec-canon sync                    # 给已初始化项目安全补齐新骨架
+spec-canon change start -g @docs/prd.md
+spec-canon change status
+spec-canon change clear
+spec-canon prompt list
+spec-canon prompt show <id>
+spec-canon prompt guide
+```
+
+`sync` 会在项目内写入 `spec-canon/.template-manifest.json`，用于记录当前骨架状态，为后续更智能的升级能力预留基础。
+
 ## 文档结构
 
 ```
+ROADMAP.md                   ← CLI 演进计划（单一来源）
 docs/
 ├── SOP.md                    ← 导航索引（入口）
 ├── guide/                    ← 方法论（一次性阅读）
@@ -89,6 +109,10 @@ docs/
 └── templates/                ← Spec 模板（7 个）
 ```
 
+## ROADMAP
+
+见 [ROADMAP.md](ROADMAP.md)。当前版本已支持安全补齐，后续版本会在 manifest 基础上逐步增加“只刷新未被修改的文件”和 `--check` 等能力。
+
 ## 为什么叫 SpecCanon
 
 **Canon**（正典）——在 SpecCanon 体系中，`domain_spec.md` 是系统行为的权威来源。每次变更开发完成后，关键信息回填到 Domain Spec，使其成为持续演化的系统正典。

package/dist/commands/change.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerChangeCommand(program: Command): void;

package/dist/commands/change.js

@@ -0,0 +1,160 @@
+import { join } from 'node:path';
+import { ActiveChangeError, clearActiveChange, ensureSddRoot, getActiveChangeStatus, getChangeDir, readActiveChange, writeActiveChange, } from '../utils/active-change.js';
+import { getChangeSeq, getNextChangeSeq, isValidChangeName } from '../utils/change.js';
+import { ensureDir } from '../utils/fs.js';
+import { logger } from '../utils/logger.js';
+export function registerChangeCommand(program) {
+    const change = program
+        .command('change')
+        .description('管理当前 active change');
+    change
+        .command('start')
+        .description('启动或确认当前 change')
+        .option('-c, --change <name>', '已确认的变更目录名')
+        .option('-g, --goal <content>', '变更目标 / 问题描述 / PRD 引用')
+        .action(async (opts) => {
+        await runStart(opts);
+    });
+    change
+        .command('status')
+        .description('查看当前 active change 状态')
+        .action(async () => {
+        await runStatus();
+    });
+    change
+        .command('clear')
+        .description('清除当前 active change 状态')
+        .action(async () => {
+        await runClear();
+    });
+}
+async function runStart(opts) {
+    try {
+        await ensureSddRoot();
+    }
+    catch (error) {
+        handleActiveChangeError(error);
+        return;
+    }
+    if (!opts.goal) {
+        logger.error('change start 需要指定 -g, --goal');
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.change && !isValidChangeName(opts.change)) {
+        logger.error('变更目录名必须符合 <type>-<seq>-<slug> 规则');
+        process.exitCode = 1;
+        return;
+    }
+    const existing = await safeReadActiveChange();
+    if (existing instanceof Error)
+        return;
+    if (existing) {
+        const canConfirmPendingChange = !existing.change &&
+            !!opts.change &&
+            existing.goal === opts.goal;
+        const isIdempotent = existing.goal === opts.goal &&
+            existing.change === opts.change;
+        if (canConfirmPendingChange) {
+            await ensureDir(getChangeDir(opts.change, process.cwd()));
+            await writeActiveChange({
+                ...existing,
+                change: opts.change,
+            });
+            logger.success(`已确认 active change：${opts.change}`);
+            return;
+        }
+        if (isIdempotent) {
+            logger.info('当前 active change 已是目标状态，无需重复启动');
+            return;
+        }
+        logger.error('已有 active change，请先运行 spec-canon change clear');
+        process.exitCode = 1;
+        return;
+    }
+    const changeSeq = opts.change
+        ? getChangeSeq(opts.change)
+        : await getNextChangeSeq();
+    const changesDir = join(process.cwd(), 'spec-canon', 'changes');
+    await ensureDir(changesDir);
+    if (opts.change) {
+        await ensureDir(getChangeDir(opts.change, process.cwd()));
+    }
+    await writeActiveChange({
+        goal: opts.goal,
+        change: opts.change,
+        changeSeq,
+        createdAt: new Date().toISOString(),
+    });
+    logger.success('已写入 active change');
+    if (opts.change) {
+        logger.info(`change: ${opts.change}`);
+    }
+    else {
+        logger.info(`change 序号: ${changeSeq}`);
+        logger.info('下一步：运行 spec-canon prompt show ctx，确认建议的 change 名后，可再次执行 change start -g <goal> -c <change>');
+    }
+}
+async function runStatus() {
+    try {
+        await ensureSddRoot();
+        const active = await readActiveChange();
+        if (!active) {
+            logger.info('当前没有 active change');
+            return;
+        }
+        const status = await getActiveChangeStatus(active);
+        console.log(`change: ${active.change ?? '(待命名)'}`);
+        console.log(`goal: ${active.goal}`);
+        console.log(`seq: ${active.changeSeq}`);
+        console.log(`createdAt: ${active.createdAt}`);
+        logger.blank();
+        console.log('Spec 进度：');
+        console.log(`  00_context: ${mark(status.progress.context)}`);
+        console.log(`  01_requirement: ${mark(status.progress.requirement)}`);
+        console.log(`  02_interface: ${mark(status.progress.interface)}`);
+        console.log(`  03_implementation: ${mark(status.progress.implementation)}`);
+        console.log(`  04_test_spec: ${mark(status.progress.testSpec)}`);
+        console.log(`  AI_CHANGELOG: ${mark(status.progress.changelogUpdated)}`);
+        console.log(`  domain-sync: ${mark(status.progress.domainSynced)}`);
+        logger.blank();
+        console.log(`推荐下一步: ${status.nextStep}`);
+    }
+    catch (error) {
+        handleActiveChangeError(error);
+    }
+}
+async function runClear() {
+    try {
+        await ensureSddRoot();
+        const cleared = await clearActiveChange();
+        if (!cleared) {
+            logger.info('当前没有 active change，无需清除');
+            return;
+        }
+        logger.success('已清除 active change');
+    }
+    catch (error) {
+        handleActiveChangeError(error);
+    }
+}
+async function safeReadActiveChange() {
+    try {
+        return await readActiveChange();
+    }
+    catch (error) {
+        handleActiveChangeError(error);
+        return error;
+    }
+}
+function handleActiveChangeError(error) {
+    if (error instanceof ActiveChangeError) {
+        logger.error(error.message);
+        process.exitCode = 1;
+        return;
+    }
+    throw error;
+}
+function mark(value) {
+    return value ? '✅' : '—';
+}

package/dist/commands/init.js

@@ -1,8 +1,8 @@
 import { join, resolve } from 'node:path';
-import { loadTemplate, SPEC_TEMPLATES } from '../templates/index.js';
-import { ensureDir, fileExists, writeFileSafe, } from '../utils/fs.js';
+import { loadTemplate } from '../templates/index.js';
+import { fileExists, } from '../utils/fs.js';
 import { logger } from '../utils/logger.js';
-const SDD_ROOT = 'spec-canon';
+import { SDD_ROOT, TEMPLATE_MANIFEST, buildManagedFiles, ensureBaseScaffoldDirs, reconcileManagedFile, writeTemplateManifest, } from '../utils/scaffold.js';
 export function registerInitCommand(program) {
     program
         .command('init')
@@ -27,42 +27,25 @@ async function runInit(opts) {
     logger.info(`初始化 SDD 文档结构到 ${targetDir}`);
     logger.blank();
     const created = [];
-    // 1. 创建目录树
-    const dirs = [
-        join(sddDir, 'domains'),
-        join(sddDir, 'changes'),
-        join(sddDir, 'decisions'),
-        join(sddDir, 'skills'),
-        join(sddDir, 'templates'),
-    ];
-    for (const dir of dirs) {
-        await ensureDir(dir);
-    }
-    // 2. 写入 .gitkeep
-    await writeFileSafe(join(sddDir, 'changes', '.gitkeep'), '');
-    created.push(`${SDD_ROOT}/changes/.gitkeep`);
-    // 3. 写入 7 个 Spec 模板
-    for (const name of SPEC_TEMPLATES) {
-        const content = await loadTemplate(name);
-        await writeFileSafe(join(sddDir, 'templates', name), content);
-        created.push(`${SDD_ROOT}/templates/${name}`);
+    const statuses = [];
+    await ensureBaseScaffoldDirs(targetDir);
+    const managedFiles = await buildManagedFiles(targetDir, {
+        includeClaude: true,
+        extraDomains: opts.domain ? [opts.domain] : [],
+    });
+    for (const file of managedFiles) {
+        const overwriteExisting = file.relativePath !== 'CLAUDE.md';
+        const status = await reconcileManagedFile(targetDir, file, {
+            overwriteExisting,
+        });
+        statuses.push(status);
+        if (status.state === 'created') {
+            created.push(file.relativePath);
+        }
     }
-    // 4. 写入 AI_CHANGELOG.md
-    const changelogContent = await loadTemplate('AI_CHANGELOG.md');
-    await writeFileSafe(join(sddDir, 'decisions', 'AI_CHANGELOG.md'), changelogContent);
-    created.push(`${SDD_ROOT}/decisions/AI_CHANGELOG.md`);
-    // 5. 写入 SKILL.md
-    const skillContent = await loadTemplate('skill.md');
-    await writeFileSafe(join(sddDir, 'skills', 'SKILL.md'), skillContent);
-    created.push(`${SDD_ROOT}/skills/SKILL.md`);
-    // 6. 写入 domains/README.md
-    const domainsReadme = await loadTemplate('domains-readme.md');
-    await writeFileSafe(join(sddDir, 'domains', 'README.md'), domainsReadme);
-    created.push(`${SDD_ROOT}/domains/README.md`);
-    // 7. 处理 CLAUDE.md
-    const claudeMdPath = join(targetDir, 'CLAUDE.md');
     const sddSection = await loadTemplate('claude-md-section.md');
-    if (await fileExists(claudeMdPath)) {
+    const claudeStatus = statuses.find((status) => status.relativePath === 'CLAUDE.md');
+    if (claudeStatus?.state !== 'created') {
         logger.warn('CLAUDE.md 已存在，请手动将以下 SDD 协议段添加到文件中：');
         logger.blank();
         logger.dim('─'.repeat(60));
@@ -71,21 +54,20 @@ async function runInit(opts) {
         logger.blank();
     }
     else {
-        const claudeMdContent = `# 项目：[项目名称]\n[一句话描述项目做什么]\n\n## 技术栈\n- [语言/框架/数据库/中间件]\n\n${sddSection}`;
-        await writeFileSafe(claudeMdPath, claudeMdContent);
-        created.push('CLAUDE.md');
         logger.success('已创建 CLAUDE.md（含 SDD 协议段）');
     }
-    // 8. 处理 --domain
     if (opts.domain) {
-        const domainDir = join(sddDir, 'domains', opts.domain);
-        await ensureDir(domainDir);
-        const domainSpecContent = await loadTemplate('domain_spec.md');
-        await writeFileSafe(join(domainDir, 'domain_spec.md'), domainSpecContent);
-        created.push(`${SDD_ROOT}/domains/${opts.domain}/domain_spec.md`);
         logger.success(`已创建业务域: ${opts.domain}`);
     }
-    // 9. 输出摘要
+    const manifestAbsolutePath = join(targetDir, SDD_ROOT, TEMPLATE_MANIFEST);
+    const manifestExisted = await fileExists(manifestAbsolutePath);
+    const manifestPath = await writeTemplateManifest(targetDir, await buildManagedFiles(targetDir, {
+        includeClaude: true,
+        includeExistingDomains: true,
+    }), statuses);
+    if (!manifestExisted) {
+        created.push(manifestPath);
+    }
     logger.blank();
     logger.success(`SDD 初始化完成！共创建 ${created.length} 个文件：`);
     logger.blank();

package/dist/commands/prompt.js

@@ -1,7 +1,9 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { ActiveChangeError, readActiveChange } from '../utils/active-change.js';
 import { findPrompt, getPromptsDir, listPrompts, loadPromptContent, } from '../prompts/catalog.js';
 import { renderPrompt } from '../prompts/renderer.js';
+import { getNextChangeSeq } from '../utils/change.js';
 import { logger } from '../utils/logger.js';
 const STAGE_LABELS = {
     daily: '日常开发 (daily)',
@@ -25,8 +27,7 @@ export function registerPromptCommand(program) {
         .description('输出指定提示词')
         .option('-c, --change <name>', '变更目录名（替换 {{CHANGE}}）')
         .option('-d, --domain <name>', '业务域名称（替换 {{DOMAIN}}）')
-        .option('-m, --module <path>', '目标模块路径（替换 {{MODULE}}）')
-        .option('-p, --prd <content>', 'PRD 内容/文件引用（替换 {{PRD}}）')
+        .option('-g, --goal <content>', '变更目标/问题描述/PRD 引用（替换 {{GOAL}}）')
         .option('--raw', '输出原始模板（不替换变量）', false)
         .action(async (id, opts) => {
         await runShow(id, opts);
@@ -105,30 +106,18 @@ async function runShow(id, opts) {
         process.stdout.write(template);
         return;
     }
-    const variables = {};
-    if (opts.change)
-        variables['CHANGE'] = opts.change;
-    if (opts.domain)
-        variables['DOMAIN'] = opts.domain;
-    if (opts.module)
-        variables['MODULE'] = opts.module;
-    if (opts.prd)
-        variables['PRD'] = opts.prd;
+    const variables = await resolveVariables(entry.id, opts);
+    if (!variables)
+        return;
     const { text, unreplaced } = renderPrompt(template, variables);
     // 提示词 → stdout
     process.stdout.write(text);
-    // ctx 提示词缺少 -d/-m 时的专属提示 → stderr
-    if (entry.id === 'ctx' && !opts.domain && !opts.module) {
-        console.error();
-        console.error('⚠ ctx 提示词需要指定 -d（从 domain_spec）或 -m（从代码库）');
-    }
     // 未替换变量警告 → stderr
     if (unreplaced.length > 0) {
         const varOpts = {
             CHANGE: '-c, --change',
             DOMAIN: '-d, --domain',
-            MODULE: '-m, --module',
-            PRD: '-p, --prd',
+            GOAL: '-g, --goal',
         };
         console.error();
         console.error("--------------------------------");
@@ -143,3 +132,62 @@ async function runGuide() {
     const content = await readFile(guidePath, 'utf-8');
     process.stdout.write(content);
 }
+function requiresGoal(id) {
+    return id === 'ctx' || id === 'req';
+}
+function requiresChange(id) {
+    return [
+        'req',
+        'iface',
+        'impl-spec',
+        'test-spec',
+        'impl',
+        'review',
+        'domain-sync',
+    ].includes(id);
+}
+function canUseActiveChange(id) {
+    return id === 'ctx' || requiresChange(id);
+}
+async function resolveVariables(id, opts) {
+    let active = null;
+    const shouldReadActive = (!opts.goal && requiresGoal(id)) ||
+        (!opts.change && canUseActiveChange(id));
+    if (shouldReadActive) {
+        try {
+            active = await readActiveChange();
+        }
+        catch (error) {
+            if (error instanceof ActiveChangeError) {
+                logger.error(error.message);
+                process.exitCode = 1;
+                return null;
+            }
+            throw error;
+        }
+    }
+    const goal = opts.goal ?? active?.goal;
+    const change = opts.change ?? active?.change;
+    if (requiresGoal(id) && !goal) {
+        logger.error(`提示词 "${id}" 需要指定 -g, --goal，或先运行 spec-canon change start`);
+        process.exitCode = 1;
+        return null;
+    }
+    if (requiresChange(id) && !change) {
+        logger.error(`提示词 "${id}" 需要指定 -c, --change，或先运行 spec-canon change start`);
+        process.exitCode = 1;
+        return null;
+    }
+    const variables = {};
+    if (goal)
+        variables['GOAL'] = goal;
+    if (change)
+        variables['CHANGE'] = change;
+    if (opts.domain)
+        variables['DOMAIN'] = opts.domain;
+    if (id === 'ctx') {
+        variables['CHANGE_SEQ'] =
+            active?.changeSeq ?? await getNextChangeSeq();
+    }
+    return variables;
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerSyncCommand(program: Command): void;

package/dist/commands/sync.js

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path';
+import { ScaffoldSyncError, syncScaffold, } from '../utils/scaffold.js';
+import { logger } from '../utils/logger.js';
+export function registerSyncCommand(program) {
+    program
+        .command('sync')
+        .description('安全补齐已初始化项目的 SDD 文档结构')
+        .option('-d, --dir <path>', '目标项目目录', process.cwd())
+        .action(async (opts) => {
+        await runSync(opts);
+    });
+}
+async function runSync(opts) {
+    const targetDir = resolve(opts.dir);
+    logger.info(`同步 SDD 文档结构到 ${targetDir}`);
+    logger.blank();
+    try {
+        const report = await syncScaffold(targetDir);
+        logger.success('SDD 同步完成');
+        logger.blank();
+        console.log(`created: ${report.created.length}`);
+        console.log(`up_to_date: ${report.upToDate.length}`);
+        console.log(`preserved: ${report.preserved.length}`);
+        console.log(`manual_review: ${report.manualReview.length}`);
+        logger.blank();
+        if (report.created.length > 0) {
+            logger.success('新增文件：');
+            for (const file of report.created) {
+                logger.dim(`  ${file}`);
+            }
+            logger.blank();
+        }
+        if (report.manualReview.length > 0) {
+            logger.warn('需要人工比对：');
+            for (const item of report.manualReview) {
+                logger.dim(`  ${item.path}`);
+                logger.dim(`    ${item.reason}`);
+            }
+            logger.blank();
+        }
+        logger.info(`已更新模板状态清单：${report.manifestPath}`);
+    }
+    catch (error) {
+        if (error instanceof ScaffoldSyncError) {
+            logger.error(error.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+}

package/dist/index.js

@@ -1,11 +1,16 @@
 import { Command } from 'commander';
+import { registerChangeCommand } from './commands/change.js';
 import { registerInitCommand } from './commands/init.js';
 import { registerPromptCommand } from './commands/prompt.js';
+import { registerSyncCommand } from './commands/sync.js';
+import { CLI_VERSION } from './version.js';
 const program = new Command();
 program
     .name('spec-canon')
     .description('CLI toolkit for Spec-Driven Development (SDD)')
-    .version('0.1.2');
+    .version(CLI_VERSION);
 registerInitCommand(program);
+registerChangeCommand(program);
 registerPromptCommand(program);
+registerSyncCommand(program);
 program.parse();

package/dist/prompts/renderer.js

@@ -1,10 +1,10 @@
-const IF_BLOCK = /\{\{#if\s+([A-Z_]+)\}\}([\s\S]*?)\{\{\/if\}\}/g;
+const IF_BLOCK = /\{\{#if\s+([A-Z_]+)\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if\}\}/g;
 const VAR_PATTERN = /\{\{([A-Z_]+)\}\}/g;
 export function renderPrompt(template, variables) {
-    // 1. 处理条件块：保留已提供变量的块内容，移除未提供的
+    // 1. 处理条件块：保留已提供变量的块内容，否则使用 else 分支（如有）
     const afterBlocks = template
-        .replace(IF_BLOCK, (_match, name, body) => {
-        return name in variables ? body : '';
+        .replace(IF_BLOCK, (_match, name, body, elseBody) => {
+        return name in variables ? body : (elseBody ?? '');
     })
         .replace(/\n{3,}/g, '\n\n') // 压缩连续空行
         .trim();

package/dist/utils/active-change.d.ts

@@ -0,0 +1,30 @@
+export interface ActiveChange {
+    goal: string;
+    change?: string;
+    changeSeq: string;
+    createdAt: string;
+}
+export interface ActiveChangeProgress {
+    context: boolean;
+    requirement: boolean;
+    interface: boolean;
+    implementation: boolean;
+    testSpec: boolean;
+    changelogUpdated: boolean;
+    domainSynced: boolean;
+}
+export interface ActiveChangeStatus {
+    active: ActiveChange;
+    progress: ActiveChangeProgress;
+    nextStep: 'ctx' | 'req' | 'iface' | 'impl-spec' | 'test-spec' | 'impl / review' | 'domain-sync' | 'change clear';
+}
+export declare class ActiveChangeError extends Error {
+}
+export declare function getSddRoot(rootDir?: string): string;
+export declare function getActiveChangePath(rootDir?: string): string;
+export declare function getChangeDir(change: string, rootDir?: string): string;
+export declare function ensureSddRoot(rootDir?: string): Promise<void>;
+export declare function readActiveChange(rootDir?: string): Promise<ActiveChange | null>;
+export declare function writeActiveChange(activeChange: ActiveChange, rootDir?: string): Promise<void>;
+export declare function clearActiveChange(rootDir?: string): Promise<boolean>;
+export declare function getActiveChangeStatus(active: ActiveChange, rootDir?: string): Promise<ActiveChangeStatus>;