@zhuan-ai/zhuanspec 2.15.7 → 2.16.2

package/dist/core/configurators/codex.js

@@ -13,12 +13,22 @@
  *
  *   ~/.codex/ (or $CODEX_HOME)
  *     config.toml   - Per-project [projects."…"] trusted_level = "trusted"
- *                     block (wrapped in TRUST markers keyed by absolute path)
+ *                     block (wrapped in TRUST markers keyed by absolute path).
+ *                     Also receives [hooks.state."<abs>:<event>:<i>:<j>"]
+ *                     entries grafted from other already-trusted projects,
+ *                     wrapped in HOOK_STATE markers keyed by config.toml path.
  *
  * Codex does **not** load project-scoped hooks/subagents unless the project
  * is explicitly marked trusted in the global config (see openai/codex#14601),
  * so we opportunistically write that trust entry during `zhuanspec init`.
  *
+ * Codex CLI >= 0.129 additionally requires each hook's content hash to be
+ * pre-approved (openai/codex#20321) or the user sees "N hooks need review".
+ * The `trusted_hash` in `[hooks.state.<key>]` depends only on normalised hook
+ * *content* (event + matcher + command), not on the key path, so we clone a
+ * previously approved hash to the current project's key to skip the manual
+ * review prompt in fresh workspaces.
+ *
  * Idempotency:
  *   - Hooks block is regenerated inside ZHUANSPEC markers on every run.
  *   - Trust entries are keyed by absolute path; repeated runs no-op.
@@ -28,7 +38,7 @@ import path from 'path';
 import os from 'os';
 import { promises as fs } from 'fs';
 import { FileSystemUtils } from '../../utils/file-system.js';
-import { getCodexHooksTomlBlock } from '../templates/codex-hooks-template.js';
+import { getCodexHooksTomlBlock, getCodexDefaultHookSlots } from '../templates/codex-hooks-template.js';
 import { getCodexAgentTomls, } from '../templates/codex-agents-template.js';
 import { getCodexSkillFiles } from '../templates/codex-skills-template.js';
 import { CodexSlashCommandConfigurator } from './slash/codex.js';
@@ -51,6 +61,18 @@ function buildTrustMarkers(projectPath) {
         end: `# <!-- ZHUANSPEC:TRUST:END path=${projectPath} -->`,
     };
 }
+/**
+ * Build the per-path HOOK_STATE marker pair for the global config.toml.
+ * Keyed by the **project config.toml absolute path** (not the project dir)
+ * so it aligns with the prefix of each `[hooks.state."<config-path>:..."]`
+ * key that Codex records.
+ */
+function buildHookStateMarkers(projectConfigTomlPath) {
+    return {
+        start: `# <!-- ZHUANSPEC:HOOK_STATE:START path=${projectConfigTomlPath} -->`,
+        end: `# <!-- ZHUANSPEC:HOOK_STATE:END path=${projectConfigTomlPath} -->`,
+    };
+}
 export class CodexConfigurator {
     name = 'Codex';
     /** Codex reads AGENTS.md for project instructions (no dedicated CODEX.md). */
@@ -80,6 +102,7 @@ export class CodexConfigurator {
         const skillsWritten = await this.mirrorSkills(projectPath);
         const configTomlPath = await this.writeProjectConfigToml(codexDir, agentFiles);
         const { globalConfigPath, trustEntryAdded } = await this.ensureGlobalTrustEntry(projectPath);
+        const hookTrust = await this.ensureHookTrustSeed(globalConfigPath, configTomlPath);
         const conflictingGlobalHooksJson = await this.detectGlobalHooksJsonConflict();
         // Codex CLI >= 0.117 no longer scans `~/.codex/prompts/`; delete any
         // ZhuanSpec-managed prompt left behind by pre-2.12.5 installs so the
@@ -94,6 +117,7 @@ export class CodexConfigurator {
             trustEntryAdded,
             conflictingGlobalHooksJson,
             legacyPromptsCleaned,
+            hookTrust,
         };
     }
     /**
@@ -292,5 +316,213 @@ export class CodexConfigurator {
         const block = this.buildTrustBlock(projectPath);
         return `${before}${block}${after}`;
     }
+    /**
+     * Graft `[hooks.state."<key>"] trusted_hash = "sha256:..."` entries for the
+     * current project from any other project that the user has already approved
+     * via Codex's `/hooks` TUI. The grafted block is wrapped in HOOK_STATE
+     * markers keyed by `configTomlPath` so it stays idempotent across runs and
+     * coexists with HOOK_STATE blocks for sibling projects in the same file.
+     *
+     * Strategy:
+     *   - Strip our own existing block first to avoid self-referencing seeds.
+     *   - Scan remaining `[hooks.state."<path>:<event>:<grp>:<hdl>"]` tables;
+     *     index their `trusted_hash` by the `<event>:<grp>:<hdl>` suffix so the
+     *     same logical hook in any other project can serve as a seed.
+     *   - For each ZhuanSpec default slot:
+     *       * If a native (unmanaged) entry already owns the same key in this
+     *         project, skip to avoid TOML duplicate-key errors.
+     *       * Else if a seed exists, emit a managed entry pointing the user's
+     *         project key at the known-good hash.
+     *       * Else record the slot in `skippedNoSeed` so callers can surface a
+     *         "please approve once in Codex" hint.
+     *
+     * Failures are non-fatal: any unexpected error is swallowed and reported
+     * via an empty result with `seedAvailable=false`, since hook trust is a
+     * UX optimisation — missing it just means the user sees the regular
+     * Codex review prompt.
+     */
+    async ensureHookTrustSeed(globalConfigPath, configTomlPath) {
+        const slots = getCodexDefaultHookSlots();
+        const empty = {
+            written: [],
+            skippedNoSeed: slots.map(slotSuffix),
+            skippedNative: [],
+            seedAvailable: false,
+        };
+        try {
+            let existing = '';
+            if (await FileSystemUtils.fileExists(globalConfigPath)) {
+                existing = await FileSystemUtils.readFile(globalConfigPath);
+            }
+            // 1. Strip our own block so we don't seed from ourselves and so the
+            //    "native conflict" check only sees user/legacy entries.
+            const stripped = stripHookStateBlock(existing, configTomlPath);
+            // 2. Build seed map (suffix → first hash seen anywhere except this project).
+            const allEntries = parseHookStateEntries(stripped);
+            const seedBySuffix = new Map();
+            const nativeOwnedSuffixes = new Set();
+            for (const entry of allEntries) {
+                const split = splitHookStateKey(entry.key);
+                if (!split)
+                    continue;
+                if (split.pathPart === configTomlPath) {
+                    // Native (unmanaged) entry already exists for this project's slot.
+                    nativeOwnedSuffixes.add(split.suffix);
+                    continue;
+                }
+                if (!seedBySuffix.has(split.suffix)) {
+                    seedBySuffix.set(split.suffix, entry.hash);
+                }
+            }
+            const seedAvailable = seedBySuffix.size > 0;
+            // 3. Plan per-slot writes.
+            const written = [];
+            const skippedNoSeed = [];
+            const skippedNative = [];
+            const blockEntries = [];
+            for (const slot of slots) {
+                const suffix = slotSuffix(slot);
+                if (nativeOwnedSuffixes.has(suffix)) {
+                    skippedNative.push(suffix);
+                    continue;
+                }
+                const seed = seedBySuffix.get(suffix);
+                if (!seed) {
+                    skippedNoSeed.push(suffix);
+                    continue;
+                }
+                const fullKey = `${configTomlPath}:${suffix}`;
+                blockEntries.push({ key: fullKey, hash: seed });
+                written.push(suffix);
+            }
+            // 4. Persist. When nothing to write, ensure any stale managed block is
+            //    removed (e.g. user revoked all hooks elsewhere); otherwise replace.
+            const finalContent = blockEntries.length === 0
+                ? stripped
+                : insertHookStateBlock(stripped, configTomlPath, buildHookStateBlockBody(configTomlPath, blockEntries));
+            if (finalContent !== existing) {
+                await FileSystemUtils.writeFile(globalConfigPath, finalContent);
+            }
+            return { written, skippedNoSeed, skippedNative, seedAvailable };
+        }
+        catch {
+            // Non-fatal: hook trust seeding is a UX optimisation.
+            return empty;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Hook trust seed helpers (module-private).
+//
+// These intentionally avoid pulling in a TOML parser dependency — we only
+// need to read/write a tightly scoped subset of `~/.codex/config.toml`
+// (`[hooks.state."..."]` tables with a single `trusted_hash` value) and
+// must round-trip the rest of the user's file byte-for-byte.
+// ---------------------------------------------------------------------------
+/** `<event>:<group>:<handler>` suffix used both for seed lookup and key building. */
+function slotSuffix(slot) {
+    return `${slot.eventSnake}:${slot.groupIndex}:${slot.handlerIndex}`;
+}
+/**
+ * Parse `[hooks.state."<key>"] trusted_hash = "..."` entries from a TOML
+ * blob using a line walker (no full TOML grammar needed).
+ */
+function parseHookStateEntries(content) {
+    const lines = content.split('\n');
+    const entries = [];
+    const headerRe = /^\[hooks\.state\."((?:[^"\\]|\\.)+)"\]\s*$/;
+    const hashRe = /^trusted_hash\s*=\s*"([^"]+)"\s*$/;
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(headerRe);
+        if (!m)
+            continue;
+        const rawKey = m[1];
+        // Walk forward until the next table header or EOF, capturing trusted_hash.
+        for (let j = i + 1; j < lines.length; j++) {
+            const trimmed = lines[j].trim();
+            if (trimmed === '' || trimmed.startsWith('#'))
+                continue;
+            if (trimmed.startsWith('['))
+                break;
+            const h = trimmed.match(hashRe);
+            if (h) {
+                entries.push({ key: unescapeTomlBasic(rawKey), hash: h[1] });
+                break;
+            }
+        }
+    }
+    return entries;
+}
+/**
+ * Split a hook-state key (`<config-toml-path>:<event>:<grp>:<hdl>`) into its
+ * path prefix and 3-field suffix. Handles paths containing `:` (Windows
+ * drives, etc.) by splitting on the **last** three colons.
+ */
+function splitHookStateKey(key) {
+    const parts = key.split(':');
+    if (parts.length < 4)
+        return null;
+    const suffix = parts.slice(-3).join(':');
+    const pathPart = parts.slice(0, parts.length - 3).join(':');
+    if (!pathPart)
+        return null;
+    return { pathPart, suffix };
+}
+/** Reverse TOML basic-string escapes for `\\\\` and `\\"` (sufficient for paths). */
+function unescapeTomlBasic(raw) {
+    return raw.replace(/\\\\/g, '\\').replace(/\\"/g, '"');
+}
+/** Forward TOML basic-string escape — mirrors `escapeBasic` used elsewhere. */
+function escapeTomlBasic(raw) {
+    return raw.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/** Build the body (between markers) of the HOOK_STATE managed block. */
+function buildHookStateBlockBody(configTomlPath, entries) {
+    const { start, end } = buildHookStateMarkers(configTomlPath);
+    const tables = entries.map((e) => [`[hooks.state."${escapeTomlBasic(e.key)}"]`, `trusted_hash = "${e.hash}"`].join('\n'));
+    const header = [
+        '# ZhuanSpec hook trust seeds — grafted from previously approved projects.',
+        '# Managed block; regenerated by `zhuanspec init/update`. Do not edit by hand.',
+    ].join('\n');
+    return [start, header, '', tables.join('\n\n'), end].join('\n');
+}
+/** Remove our marker-wrapped HOOK_STATE block for `configTomlPath` from `content`. */
+function stripHookStateBlock(content, configTomlPath) {
+    const { start, end } = buildHookStateMarkers(configTomlPath);
+    const startIdx = content.indexOf(start);
+    if (startIdx === -1)
+        return content;
+    const endIdx = content.indexOf(end, startIdx + start.length);
+    if (endIdx === -1)
+        return content;
+    const blockStart = startIdx;
+    let blockEnd = endIdx + end.length;
+    // Consume the trailing newline written together with the block so we
+    // don't leave an orphan blank line behind. Leave any leading newline
+    // intact so `insertHookStateBlock` produces a stable, idempotent layout.
+    if (content[blockEnd] === '\n')
+        blockEnd += 1;
+    return content.substring(0, blockStart) + content.substring(blockEnd);
+}
+/**
+ * Insert (or replace) the HOOK_STATE managed block for `configTomlPath` in
+ * `content`. When a previous block exists, it's swapped in-place to keep the
+ * file order stable. Otherwise the block is appended to EOF; we adjust the
+ * separator so a follow-up `strip + insert` round-trip produces byte-for-byte
+ * the same result (idempotency).
+ */
+function insertHookStateBlock(content, configTomlPath, block) {
+    const { start, end } = buildHookStateMarkers(configTomlPath);
+    const startIdx = content.indexOf(start);
+    if (startIdx !== -1) {
+        const endIdx = content.indexOf(end, startIdx + start.length);
+        if (endIdx !== -1) {
+            const before = content.substring(0, startIdx);
+            const after = content.substring(endIdx + end.length);
+            return `${before}${block}${after}`;
+        }
+    }
+    const separator = content.length === 0 || content.endsWith('\n') ? '' : '\n';
+    return `${content}${separator}${block}\n`;
 }
 //# sourceMappingURL=codex.js.map

package/dist/core/corrections/select-candidates.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Pending corrections candidate selection.
+ *
+ * 责任：把 `zhuanspec/changes/<id>/metrics/user_inputs.json` 里的纠偏 prompt 加工成
+ * "可读、去毛刺、去重、带建议分类" 的候选清单，给 review 阶段的踩坑沉淀决策使用。
+ *
+ * 不写文件、不改 progress.json，只做"读 + 计算 + 返回结构"。
+ */
+export type CandidateCategory = 'troubleshooting' | 'best-practices' | 'implicit-conventions';
+export type CandidateSourceLevel = 1 | 2;
+export interface CorrectionCandidate {
+    /** 1-based 序号，对应"用户回复编号清单"的编号 */
+    index: number;
+    /** 关联的 user_inputs.json.inputId */
+    inputId?: string;
+    timestamp?: string;
+    phase?: string;
+    /** 优先 fullPrompt，没有就 summary，再没有就空字符串 */
+    text: string;
+    /** 截断展示用的预览（≤ 200 字） */
+    preview: string;
+    /** 命中的纠偏关键词（取 USER_CORRECTION_KEYWORDS / REQUIREMENT_CHANGE_KEYWORDS） */
+    matchedKeywords: string[];
+    isRequirementChange: boolean;
+    /** 启发式建议分类（用户/skill 仍可改） */
+    suggestedCategory: CandidateCategory;
+    /** 拟用文件名（不含目录前缀） */
+    suggestedFilename: string;
+}
+export interface DroppedCandidate {
+    /** drop 后保留的原始序号（按出现顺序，1-based）——用于在 markdown 里展示 */
+    rawIndex: number;
+    inputId?: string;
+    timestamp?: string;
+    reason: 'empty' | 'trivial-acknowledgement' | 'too-short-no-keyword' | 'duplicate-of' | 'subset-of';
+    /** 当 reason 为 duplicate-of / subset-of 时，指向被引用的有效候选编号 */
+    refIndex?: number;
+    preview: string;
+}
+export interface CandidateSelectionResult {
+    changeId: string;
+    /** 数据源层级（1: user_inputs 带 correctionSignal；2: 关键词推断） */
+    level: CandidateSourceLevel | null;
+    totalRaw: number;
+    candidates: CorrectionCandidate[];
+    dropped: DroppedCandidate[];
+    /** 数据完整性提示——读不到 user_inputs.json 时给空候选 + 错误说明 */
+    notice?: string;
+}
+/**
+ * 从 change 目录抽取并加工纠偏候选。
+ */
+export declare function selectCorrectionCandidates(cwd: string, changeId: string): Promise<CandidateSelectionResult>;
+/**
+ * 把候选结果渲染成 markdown，用于落到 review/pending-corrections.md。
+ */
+export declare function renderPendingCorrectionsMarkdown(result: CandidateSelectionResult): string;
+//# sourceMappingURL=select-candidates.d.ts.map