specdo 1.0.2

package/dist/core/config-store.js

@@ -0,0 +1,280 @@
+/**
+ * ConfigStore — `specdo/config.yaml` 唯一读写入口
+ *
+ * 设计要点（与 phases/03-phase2-commands.md §`config.overrides 最低契约` 完全对齐）：
+ *
+ *   1. **Schema 定义**：使用 Zod 描述当前 config 顶层结构与 overrides 树
+ *   2. **`enabled: false`**：禁用指定 stage（不是删整个 domain），renderer 跳过注入
+ *   3. **override action 三选一**：同一 item 必须且只能包含 prepend / append / replace 之一
+ *   4. **未知 domain / stage / field**：必须由 validate 报错（friendly path）
+ *   5. **优先级**：内置 domain → config.overrides 深合并；CLI 参数不得临时改写 domain
+ *
+ * 模块只读，写入由 init 命令处理。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as YAML from 'yaml';
+import { z } from 'zod';
+import { ALL_DOMAINS, applyOverrides as applyDomainOverrides, getDomainByName, } from '../domains/index.js';
+// ─── Schema ─────────────────────────────────────────────────────
+const overrideItemSchema = z
+    .object({
+    prepend: z.string().optional(),
+    append: z.string().optional(),
+    replace: z.string().optional(),
+})
+    .strict()
+    .superRefine((obj, ctx) => {
+    const keys = ['prepend', 'append', 'replace'].filter((k) => obj[k] !== undefined);
+    if (keys.length !== 1) {
+        const message = keys.length === 0
+            ? 'override item must contain exactly one action: prepend / append / replace'
+            : 'prepend, append, and replace are mutually exclusive; choose exactly one action per override item';
+        ctx.addIssue({ code: 'custom', message });
+    }
+});
+const stageOverridesSchema = z
+    .object({
+    enabled: z.boolean().optional(),
+    questions: z.array(overrideItemSchema).optional(),
+    checklist: z.array(overrideItemSchema).optional(),
+    focusAreas: z.array(overrideItemSchema).optional(),
+    antiPatterns: z.array(overrideItemSchema).optional(),
+    patterns: z.record(z.string(), z.string()).optional(),
+})
+    .superRefine((stage, ctx) => {
+    for (const field of ['questions', 'checklist', 'focusAreas', 'antiPatterns']) {
+        const items = stage[field];
+        if (!items || items.length === 0)
+            continue;
+        const hasReplace = items.some((item) => item.replace !== undefined);
+        const hasPrependOrAppend = items.some((item) => item.prepend !== undefined || item.append !== undefined);
+        if (hasReplace && hasPrependOrAppend) {
+            ctx.addIssue({
+                code: 'custom',
+                path: [field],
+                message: 'replace cannot be combined with prepend/append in the same override field; choose replace-only or prepend/append-only',
+            });
+        }
+    }
+})
+    .strict();
+const domainOverridesSchema = z
+    .object({
+    explore: stageOverridesSchema.optional(),
+    design: stageOverridesSchema.optional(),
+    implement: stageOverridesSchema.optional(),
+    verify: stageOverridesSchema.optional(),
+})
+    .strict();
+const configSchema = z
+    .object({
+    domainVersion: z.string().regex(/^1(\.\d+)?$/, "domainVersion must start with '1'"),
+    overrides: z.record(z.string(), domainOverridesSchema).optional(),
+})
+    .strict();
+const KNOWN_DOMAIN_NAMES = new Set(ALL_DOMAINS.map((d) => d.name));
+const KNOWN_STAGES = ['explore', 'design', 'implement', 'verify'];
+/**
+ * 加载并校验 specdo/config.yaml。
+ *
+ * - 文件不存在 → issues=[NOT_FOUND]，config=null
+ * - YAML parse 失败 → issues=[YAML]，config=null
+ * - Zod schema 失败 → issues=[zod paths]，config=null
+ * - 未知 domain / stage / field → 由 strict() + 自定义校验产出 friendly path
+ */
+export function loadConfig(cwd) {
+    const cfgPath = locateConfigPath(cwd);
+    if (!cfgPath) {
+        return {
+            raw: null,
+            config: null,
+            issues: [{ path: 'specdo/config.yaml', message: "Not initialized. Run 'specdo init' first." }],
+        };
+    }
+    let raw;
+    try {
+        raw = YAML.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    }
+    catch (err) {
+        return {
+            raw: null,
+            config: null,
+            issues: [{ path: 'specdo/config.yaml', message: `YAML parse failed: ${err.message}` }],
+        };
+    }
+    if (raw === null || raw === undefined) {
+        return {
+            raw,
+            config: null,
+            issues: [{ path: 'specdo/config.yaml', message: 'config is empty' }],
+        };
+    }
+    const parsed = configSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => ({
+            path: formatZodPath(i.path),
+            message: i.message,
+        }));
+        return { raw, config: null, issues };
+    }
+    // 自定义层校验：unknown domain name
+    const config = parsed.data;
+    const issues = [];
+    if (config.overrides) {
+        for (const domainName of Object.keys(config.overrides)) {
+            if (!KNOWN_DOMAIN_NAMES.has(domainName)) {
+                issues.push({
+                    path: `overrides.${domainName}`,
+                    message: `Unknown domain "${domainName}". Known: ${[...KNOWN_DOMAIN_NAMES].join(', ')}.`,
+                });
+            }
+        }
+    }
+    return { raw, config, issues };
+}
+/**
+ * 应用项目级 overrides，返回所有可用领域（按 ALL_DOMAINS 顺序），含统计信息。
+ *
+ * 即使有 issues 也尽量产出可用 ResolvedDomain（issues 由调用方 validate 报告）。
+ */
+export function resolveDomains(config) {
+    const overridesMap = config?.overrides ?? {};
+    return ALL_DOMAINS.map((domain) => {
+        const rawOverride = overridesMap[domain.name];
+        if (!rawOverride) {
+            return {
+                domain,
+                hasDisabledStages: false,
+                overrideCounts: KNOWN_STAGES.map((stage) => ({
+                    stage,
+                    appended: 0,
+                    prepended: 0,
+                    replaced: 0,
+                    patternsAdded: 0,
+                    enabled: domain[stage] !== undefined,
+                })),
+            };
+        }
+        // 转换为 DomainOverrides；每个 item 必须恰好一个 action，
+        // applyOverrides 负责实际深合并 + 整段替换。
+        const compiled = compileOverrides(rawOverride);
+        const overridden = applyDomainOverrides(domain, compiled.overrides);
+        const hasDisabled = rawOverride.explore?.enabled === false ||
+            rawOverride.design?.enabled === false ||
+            rawOverride.implement?.enabled === false ||
+            rawOverride.verify?.enabled === false;
+        return {
+            domain: overridden,
+            hasDisabledStages: hasDisabled,
+            overrideCounts: KNOWN_STAGES.map((stage) => {
+                const cnt = compiled.counts[stage];
+                return {
+                    stage,
+                    appended: cnt.appended,
+                    prepended: cnt.prepended,
+                    replaced: cnt.replaced,
+                    patternsAdded: cnt.patternsAdded,
+                    enabled: overridden[stage] !== undefined,
+                };
+            }),
+        };
+    });
+}
+export function getResolvedDomain(config, name) {
+    if (!getDomainByName(name))
+        return undefined;
+    return resolveDomains(config).find((r) => r.domain.name === name);
+}
+/** locate specdo/config.{yaml,yml}; null if neither exists */
+export function locateConfigPath(cwd) {
+    for (const candidate of ['specdo/config.yaml', 'specdo/config.yml']) {
+        const abs = path.join(cwd, candidate);
+        if (safeIsFile(abs))
+            return abs;
+    }
+    return null;
+}
+function compileOverrides(raw) {
+    const counts = {
+        explore: { appended: 0, prepended: 0, replaced: 0, patternsAdded: 0 },
+        design: { appended: 0, prepended: 0, replaced: 0, patternsAdded: 0 },
+        implement: { appended: 0, prepended: 0, replaced: 0, patternsAdded: 0 },
+        verify: { appended: 0, prepended: 0, replaced: 0, patternsAdded: 0 },
+    };
+    const overrides = {};
+    for (const stage of KNOWN_STAGES) {
+        const stageRaw = raw[stage];
+        if (!stageRaw)
+            continue;
+        const compiledStage = {};
+        if (stageRaw.enabled !== undefined)
+            compiledStage.enabled = stageRaw.enabled;
+        for (const field of ['questions', 'checklist', 'focusAreas', 'antiPatterns']) {
+            const items = stageRaw[field];
+            if (!items)
+                continue;
+            const hasReplace = items.some((item) => item.replace !== undefined);
+            const hasPrependOrAppend = items.some((item) => item.prepend !== undefined || item.append !== undefined);
+            if (hasReplace && hasPrependOrAppend) {
+                throw new Error(`Invalid override field ${stage}.${field}: replace cannot be combined with prepend/append`);
+            }
+            const compiled = [];
+            for (const item of items) {
+                const actionKeys = ['prepend', 'append', 'replace'].filter((key) => item[key] !== undefined);
+                if (actionKeys.length !== 1) {
+                    throw new Error(`Invalid override item for ${stage}.${field}: choose exactly one of prepend / append / replace`);
+                }
+                const action = actionKeys[0];
+                if (action === 'prepend') {
+                    if (item.prepend === undefined) {
+                        throw new Error(`Invalid override item for ${stage}.${field}: prepend value is missing`);
+                    }
+                    compiled.push({ prepend: item.prepend });
+                    counts[stage].prepended += 1;
+                }
+                else if (action === 'append') {
+                    if (item.append === undefined) {
+                        throw new Error(`Invalid override item for ${stage}.${field}: append value is missing`);
+                    }
+                    compiled.push({ append: item.append });
+                    counts[stage].appended += 1;
+                }
+                else {
+                    if (item.replace === undefined) {
+                        throw new Error(`Invalid override item for ${stage}.${field}: replace value is missing`);
+                    }
+                    compiled.push({ replace: item.replace });
+                    counts[stage].replaced += 1;
+                }
+            }
+            // 把 compiled 写到对应字段
+            compiledStage[field] = compiled;
+        }
+        if (stageRaw.patterns) {
+            compiledStage.patterns = { ...stageRaw.patterns };
+            counts[stage].patternsAdded = Object.keys(stageRaw.patterns).length;
+        }
+        overrides[stage] = compiledStage;
+    }
+    return { overrides, counts };
+}
+function formatZodPath(p) {
+    return p
+        .map((seg, idx) => {
+        if (typeof seg === 'number')
+            return `[${seg}]`;
+        const str = String(seg);
+        return idx === 0 ? str : `.${str}`;
+    })
+        .join('');
+}
+function safeIsFile(p) {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=config-store.js.map

package/dist/core/config-store.js.map

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

package/dist/core/context-store.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ContextStore — `context.json` 唯一读写入口
+ *
+ * 设计要点（与 phases/03-phase2-commands.md §ContextStore 完全对齐）：
+ *
+ *   1. **原子写入**：write-then-rename + fsync 数据 + best-effort fsync
+ *      目录；崩溃恢复必须可读
+ *   2. **.bak 快照**：每次写入前先把当前 context.json 复制到
+ *      context.json.bak，作为 last-good 快照
+ *   3. **损坏恢复**：read() 解析失败时尝试 .bak；.bak 也损坏则重建为空
+ *      context 并附带显式 warning
+ *   4. **临时锁**：使用 Node 原生 `fs.open(lockPath, 'wx')` 获取互斥；
+ *      冲突时按 50/100/200ms 重试，3 次仍失败则检查死锁（锁文件年龄 >30s
+ *      或无效内容视为 stale，强制删除并重试一次）。锁文件内容为
+ *      `{ pid, timestamp }` 用于死锁检测。不引入 proper-lockfile 等运行时依赖
+ *   5. **深合并**：stage 对象内深合并；数组字段整段替换；tasksEvidence
+ *      按 key 合并；--undo 必须显式删除 String(N)
+ */
+import type { ChangeContext, ApplyStageState, ArchiveStageState, ExploreStageState, ProposeStageState, SyncStageState } from '../domains/types.js';
+export type StageKey = 'explore' | 'propose' | 'apply' | 'sync' | 'archive';
+export interface ContextStoreOptions {
+    /** specdo/changes/<name>/ 路径 */
+    changeDir: string;
+    /**
+     * 时间源（测试可注入）；返回 ISO 字符串。默认 `() => new Date().toISOString()`
+     */
+    now?: () => string;
+}
+export declare class ContextLockError extends Error {
+    readonly exitCode = 3;
+    constructor(message: string);
+}
+export declare class ContextStore {
+    private readonly contextPath;
+    private readonly backupPath;
+    private readonly lockPath;
+    private readonly changeDir;
+    private readonly now;
+    /** read() 时累积的 warning，调用方可选择性展示 */
+    lastReadWarnings: string[];
+    constructor(options: ContextStoreOptions);
+    /**
+     * 读取 context.json；不存在时返回带必填字段的默认空 context（不写盘）。
+     *
+     * 损坏处理：
+     *   - 主文件 JSON 解析失败 → 尝试 .bak → 仍失败 → 重建空 context 并 warn
+     *   - 类型不匹配（version != 2 等）→ warn 但保留尽可能多字段
+     */
+    read(): ChangeContext;
+    /**
+     * 深合并写入：仅替换调用方传入的字段，保留磁盘上未提及的字段。
+     *
+     * 规则：
+     *   - 顶层 stage 对象使用深合并（per stage 单独合并）
+     *   - 数组字段整段替换
+     *   - tasksEvidence 按 key 合并；如果调用方显式给出 tasksEvidence 整段
+     *     替换，调用方必须自行包含完整 map（用于 --undo 删除 key 场景）
+     *   - 总是更新 change.updatedAt
+     */
+    writeDeep(partial: DeepPartialContext): void;
+    /** 整段替换；调用方需保证传入完整 ChangeContext */
+    writeFull(next: ChangeContext): void;
+    getStage<T = unknown>(stage: StageKey): T | null;
+    /** 暴露给测试 / doctor 读取 path 信息 */
+    describe(): {
+        contextPath: string;
+        backupPath: string;
+        lockPath: string;
+    };
+    private defaultContext;
+    private tryLoadJson;
+    /**
+     * 将原始 JSON 强转为 ChangeContext。容错处理：
+     *   - 缺失 version → 默认 2 并 warn
+     *   - 缺失 change 元数据 → 用默认填充并 warn
+     *   - 未知顶层字段 → 保留（架构 §3.3）
+     */
+    private coerceContext;
+    private persist;
+    private withLock;
+}
+/** apply stage 的 partial 写入类型，tasksEvidence 允许 null 值（表示删除对应 key） */
+export type ApplyStagePatch = Partial<Omit<ApplyStageState, 'tasksEvidence'>> & {
+    tasksEvidence?: Record<string, string | null>;
+};
+export interface DeepPartialContext {
+    change?: Partial<ChangeContext['change']>;
+    explore?: Partial<ExploreStageState> | null;
+    propose?: Partial<ProposeStageState> | null;
+    apply?: ApplyStagePatch | null;
+    sync?: Partial<SyncStageState> | null;
+    archive?: Partial<ArchiveStageState> | null;
+    /** 用于完全删除某个 stage（e.g. apply --undo 后清空 apply key） */
+    resetStages?: StageKey[];
+}
+//# sourceMappingURL=context-store.d.ts.map

package/dist/core/context-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-store.d.ts","sourceRoot":"","sources":["../../src/core/context-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACf,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAgB,QAAQ,KAAK;gBACjB,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,oCAAoC;IAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAM;gBAE3B,OAAO,EAAE,mBAAmB;IAQxC;;;;;;OAMG;IACH,IAAI,IAAI,aAAa;IA6BrB;;;;;;;;;OASG;IACH,SAAS,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAQ5C,oCAAoC;IACpC,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAMpC,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,QAAQ,GAAG,CAAC,GAAG,IAAI;IAMhD,gCAAgC;IAChC,QAAQ,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAMzE,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,WAAW;IAoBnB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IA+CrB,OAAO,CAAC,OAAO;IAyCf,OAAO,CAAC,QAAQ;CA0FjB;AAID,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC,GAAG;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAC/C,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;IACtC,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC;IAC5C,sDAAsD;IACtD,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC;CAC1B"}