@zhuan-ai/zhuanspec 2.19.2 → 2.19.3

package/dist/core/hooks/user-input-debug-log.d.ts

@@ -0,0 +1,43 @@
+/**
+ * user-input hook 的结构化调试日志（JSONL）。
+ *
+ * 历史实现直接 append 到 `<cwd>/.user-input-debug.log`，带来三个问题：
+ *   1. 污染业务仓库：detectActiveChange 只看 `<cwd>/zhuanspec/changes`，不向上查找。
+ *      cwd 落在工作区下的业务子仓库时，每条 prompt 都只会写一行 no-active-change，
+ *      于是日志被创建在业务仓库根目录，且因为没有 .gitignore 兜底被提交进版本库。
+ *   2. 无上限：只 append 不轮转，单个文件可以无限增长。
+ *   3. 无开关：无法关闭。
+ *
+ * 现在的约定（与 `zhuanspec/.hook-debug.log`、`metrics/.accuracy-debug.log` 一致）：
+ *   - 只有 cwd 确实是 zhuanspec 项目（存在 `<cwd>/zhuanspec` 目录）时才落盘，
+ *     否则整体 no-op —— 业务仓库不会再出现这个文件。
+ *   - 落盘到 `<cwd>/zhuanspec/.user-input-debug.log`，与其它过程产物同域。
+ *   - 超过 DEBUG_LOG_MAX_BYTES 轮转一代（.1），旧代被覆盖，总占用有上限。
+ *   - `ZHUANSPEC_DEBUG_LOG=0|false|off|no` 可完全关闭。
+ */
+/** 日志文件名（放在 zhuanspec 项目目录下，与 .hook-debug.log 同级） */
+export declare const DEBUG_LOG_FILE_NAME = ".user-input-debug.log";
+/** 单个日志文件上限：512KB。超过则轮转一代，最坏占用 ~1MB */
+export declare const DEBUG_LOG_MAX_BYTES: number;
+/**
+ * 调试日志是否启用。默认启用（保持“每次调用写一行”的排障契约），
+ * 显式把 ZHUANSPEC_DEBUG_LOG 设为 0/false/off/no 时关闭。
+ */
+export declare function isDebugLogEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 解析日志落盘路径。
+ * cwd 不是 zhuanspec 项目（没有 `<cwd>/zhuanspec` 目录）时返回 null，调用方据此跳过写入，
+ * 避免在业务仓库里凭空创建文件。
+ */
+export declare function resolveDebugLogPath(cwd: string): string | null;
+/**
+ * 超过上限时轮转一代：当前文件重命名为 `<name>.1`（覆盖上一代），随后由调用方重新 append。
+ * 任何失败都静默返回，日志不能影响 hook 主流程。
+ */
+export declare function rotateDebugLogIfNeeded(logPath: string, maxBytes?: number): void;
+/**
+ * 追加一行 JSONL 调试日志。禁用、非 zhuanspec 项目或任何 IO 异常都静默跳过。
+ * 返回实际写入的路径，便于测试与排障；未写入时返回 null。
+ */
+export declare function appendDebugLog(cwd: string, payload: Record<string, unknown>, env?: NodeJS.ProcessEnv): string | null;
+//# sourceMappingURL=user-input-debug-log.d.ts.map

package/dist/core/hooks/user-input-debug-log.js

@@ -0,0 +1,86 @@
+/**
+ * user-input hook 的结构化调试日志（JSONL）。
+ *
+ * 历史实现直接 append 到 `<cwd>/.user-input-debug.log`，带来三个问题：
+ *   1. 污染业务仓库：detectActiveChange 只看 `<cwd>/zhuanspec/changes`，不向上查找。
+ *      cwd 落在工作区下的业务子仓库时，每条 prompt 都只会写一行 no-active-change，
+ *      于是日志被创建在业务仓库根目录，且因为没有 .gitignore 兜底被提交进版本库。
+ *   2. 无上限：只 append 不轮转，单个文件可以无限增长。
+ *   3. 无开关：无法关闭。
+ *
+ * 现在的约定（与 `zhuanspec/.hook-debug.log`、`metrics/.accuracy-debug.log` 一致）：
+ *   - 只有 cwd 确实是 zhuanspec 项目（存在 `<cwd>/zhuanspec` 目录）时才落盘，
+ *     否则整体 no-op —— 业务仓库不会再出现这个文件。
+ *   - 落盘到 `<cwd>/zhuanspec/.user-input-debug.log`，与其它过程产物同域。
+ *   - 超过 DEBUG_LOG_MAX_BYTES 轮转一代（.1），旧代被覆盖，总占用有上限。
+ *   - `ZHUANSPEC_DEBUG_LOG=0|false|off|no` 可完全关闭。
+ */
+import path from 'path';
+import fs from 'fs';
+/** 日志文件名（放在 zhuanspec 项目目录下，与 .hook-debug.log 同级） */
+export const DEBUG_LOG_FILE_NAME = '.user-input-debug.log';
+/** 单个日志文件上限：512KB。超过则轮转一代，最坏占用 ~1MB */
+export const DEBUG_LOG_MAX_BYTES = 512 * 1024;
+/** 关闭调试日志的环境变量取值（大小写不敏感） */
+const DISABLED_VALUES = new Set(['0', 'false', 'off', 'no']);
+/**
+ * 调试日志是否启用。默认启用（保持“每次调用写一行”的排障契约），
+ * 显式把 ZHUANSPEC_DEBUG_LOG 设为 0/false/off/no 时关闭。
+ */
+export function isDebugLogEnabled(env = process.env) {
+    const raw = env.ZHUANSPEC_DEBUG_LOG;
+    if (raw === undefined || raw === '')
+        return true;
+    return !DISABLED_VALUES.has(raw.trim().toLowerCase());
+}
+/**
+ * 解析日志落盘路径。
+ * cwd 不是 zhuanspec 项目（没有 `<cwd>/zhuanspec` 目录）时返回 null，调用方据此跳过写入，
+ * 避免在业务仓库里凭空创建文件。
+ */
+export function resolveDebugLogPath(cwd) {
+    const zhuanspecDir = path.join(cwd, 'zhuanspec');
+    try {
+        if (!fs.statSync(zhuanspecDir).isDirectory())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return path.join(zhuanspecDir, DEBUG_LOG_FILE_NAME);
+}
+/**
+ * 超过上限时轮转一代：当前文件重命名为 `<name>.1`（覆盖上一代），随后由调用方重新 append。
+ * 任何失败都静默返回，日志不能影响 hook 主流程。
+ */
+export function rotateDebugLogIfNeeded(logPath, maxBytes = DEBUG_LOG_MAX_BYTES) {
+    try {
+        if (fs.statSync(logPath).size < maxBytes)
+            return;
+        fs.renameSync(logPath, `${logPath}.1`);
+    }
+    catch {
+        // 文件不存在或轮转失败都不阻塞写入
+    }
+}
+/**
+ * 追加一行 JSONL 调试日志。禁用、非 zhuanspec 项目或任何 IO 异常都静默跳过。
+ * 返回实际写入的路径，便于测试与排障；未写入时返回 null。
+ */
+export function appendDebugLog(cwd, payload, env = process.env) {
+    if (!isDebugLogEnabled(env))
+        return null;
+    const logPath = resolveDebugLogPath(cwd);
+    if (!logPath)
+        return null;
+    try {
+        rotateDebugLogIfNeeded(logPath);
+        fs.appendFileSync(logPath, `${JSON.stringify(payload)}\n`, 'utf-8');
+        return logPath;
+    }
+    catch {
+        // Logging must never block the hook
+        return null;
+    }
+}
+//# sourceMappingURL=user-input-debug-log.js.map

package/dist/core/hooks/user-input-hook.js

@@ -22,22 +22,18 @@ import crypto from 'crypto';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { getBeijingTime, atomicWriteJson, detectActiveChange } from './record-progress.js';
 import { detectHookHost, sanitizeCodexEnvelope } from '../../utils/hook-host.js';
+import { appendDebugLog } from './user-input-debug-log.js';
 import { USER_CORRECTION_KEYWORDS, REQUIREMENT_CHANGE_KEYWORDS, extractProposalSummary, buildCorrectionOptionsContext, buildRequirementChangeContext, isCodexInternalPrompt, } from './deviation-check.js';
 /**
  * Structured JSONL debug log for user-input hook.
- * Writes to <cwd>/.user-input-debug.log; failures are swallowed to keep main flow intact.
- * Every hook invocation MUST write exactly one line here, covering every branch
- * (skip-*, record, baseline-miss, baseline-write) with positive reason codes.
+ * Writes to <cwd>/zhuanspec/.user-input-debug.log; failures are swallowed to keep
+ * main flow intact. Every hook invocation MUST write exactly one line here, covering every
+ * branch (skip-*, record, baseline-miss, baseline-write) with positive reason codes.
+ * cwd 不是 zhuanspec 项目时整体跳过，避免在业务仓库里凭空创建日志文件；
+ * 落盘策略（位置 / 上限轮转 / 开关）见 user-input-debug-log.ts。
  */
 function logDebug(cwd, payload) {
-    try {
-        const logPath = path.join(cwd, '.user-input-debug.log');
-        const line = JSON.stringify({ ts: getBeijingTime(), ...payload }) + '\n';
-        fs.appendFileSync(logPath, line, 'utf-8');
-    }
-    catch {
-        // Logging must never block the hook
-    }
+    appendDebugLog(cwd, { ts: getBeijingTime(), ...payload });
 }
 /** fullPrompt 截断长度：够写知识文件的"背景/问题/解决方案"，又不会把 user_inputs.json 撑爆 */
 const FULL_PROMPT_MAX_LEN = 2000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhuan-ai/zhuanspec",
-  "version": "2.19.2",
+  "version": "2.19.3",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "zhuanspec",
@@ -39,26 +39,6 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
-  "scripts": {
-    "lint": "eslint src/",
-    "build": "node build.js",
-    "dev": "tsc --watch",
-    "dev:cli": "pnpm build && node bin/zhuanspec.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:ui": "vitest --ui",
-    "test:coverage": "vitest --coverage",
-    "test:postinstall": "node scripts/postinstall.js",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run build",
-    "postinstall": "node scripts/postinstall.js",
-    "check:pack-version": "node scripts/pack-version-check.mjs",
-    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
-    "release": "pnpm run release:ci",
-    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
-    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
-    "changeset": "changeset"
-  },
   "engines": {
     "node": ">=20.19.0"
   },
@@ -80,5 +60,23 @@
     "ora": "^8.2.0",
     "yaml": "^2.8.2",
     "zod": "^4.0.17"
+  },
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/zhuanspec.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "diagnose:cursor": "node scripts/diagnose-cursor-commands.js",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
   }
-}
+}