aodw-skill 0.7.24 → 0.7.25

package/README.md

@@ -113,6 +113,33 @@ npx aodw-skill new
 
 交互式创建新的开发任务 Ticket。
 
+### AODW v0 防漏记（推荐）
+
+```bash
+npx aodw-skill enable-guard-hook
+```
+
+默认行为（更自动）：
+- `npx aodw-skill init` 时会自动尝试安装 guard hook（若无自定义 hook 冲突）
+- 提交时自动执行 `guard --auto-fix --stage-audit`
+- 若 `latest` 版本尚未包含 `guard` 命令，hook 会自动回退尝试 `aodw-skill@beta`
+
+在当前项目安装 `pre-commit` guard，自动处理：
+- 改了代码目录（如 `cli/`、`templates/`、`src/` 等）
+- 但没有任何流程痕迹更新（如 `RT/`、`maintainers/`、`.aodw-next/06-project/`）
+- 自动生成并暂存 `.aodw-next/06-project/audit-latest.md` 作为最小补录
+
+手动命令：
+
+```bash
+npx aodw-skill guard
+npx aodw-skill audit --write
+```
+
+用途：
+- `guard`: 提交前检查是否“有改动无痕迹”
+- `audit --write`: 生成最小补录草稿到 `.aodw-next/06-project/audit-latest.md`
+
 ## 维护者发布流程
 
 后续版本发布统一采用以下方式：

package/bin/aodw.js

@@ -18,6 +18,8 @@ import {
 import { serve } from './commands/serve.js';
 import { createNewRT } from './commands/new.js';
 import { initTools } from './commands/init-tools.js';
+import { guardDocTrace, auditDocTrace } from './commands/trace-guard.js';
+import { enableGuardHook } from './commands/install-guard-hook.js';
 import { saveProjectConfig, saveUserConfig, getProjectConfig, getUserConfig } from './utils/config.js';
 import {
   detectTechStack,
@@ -408,6 +410,9 @@ async function runInit() {
     }
   }
 
+  // 4. Enable v0 guard hook automatically in user project
+  await enableGuardHook({ silent: true });
+
   console.log(chalk.green('\n✅ AODW-Next 初始化成功!'));
   console.log(chalk.white(`项目: ${projectName}`));
 
@@ -690,6 +695,24 @@ program
   .description('Initialize development tools (ESLint, Prettier, Ruff, Black, etc.)')
   .action(initTools);
 
+program
+  .command('guard')
+  .description('v0 guard: block code changes without trace updates')
+  .option('--auto-fix', 'Auto-generate minimal audit trace when missing')
+  .option('--stage-audit', 'Stage generated audit trace file automatically')
+  .action(guardDocTrace);
+
+program
+  .command('audit')
+  .description('Generate a minimal AODW audit draft from staged changes')
+  .option('--write', 'Write draft into .aodw-next/06-project/audit-latest.md')
+  .action(auditDocTrace);
+
+program
+  .command('enable-guard-hook')
+  .description('Install pre-commit hook to enforce AODW v0 trace guard')
+  .action(enableGuardHook);
+
 
 // Main Entry Point
 if (!process.argv.slice(2).length) {

package/bin/commands/install-guard-hook.js

@@ -0,0 +1,69 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+
+function getHookPath() {
+  return path.join(process.cwd(), '.git', 'hooks', 'pre-commit');
+}
+
+function getHookContent() {
+  return `#!/usr/bin/env sh
+# AODW v0 trace guard hook
+# Auto-generated by aodw-skill enable-guard-hook
+
+if [ -x "./node_modules/.bin/aodw-skill" ]; then
+  ./node_modules/.bin/aodw-skill guard --auto-fix --stage-audit
+  exit $?
+fi
+
+# Fallback strategy:
+# 1) Try latest installed/resolved aodw-skill
+# 2) If command not found in that version, fallback to beta channel
+npx --yes aodw-skill guard --auto-fix --stage-audit && exit 0
+npx --yes aodw-skill@beta guard --auto-fix --stage-audit
+exit $?
+`;
+}
+
+export async function enableGuardHook(options = {}) {
+  const { silent = false } = options;
+  const hookPath = getHookPath();
+  const gitDir = path.join(process.cwd(), '.git');
+
+  if (!fs.existsSync(gitDir)) {
+    if (!silent) {
+      console.log(chalk.red('❌ 当前目录不是 git 仓库，无法安装 pre-commit hook。'));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  await fs.ensureDir(path.dirname(hookPath));
+
+  let shouldOverwrite = true;
+  if (fs.existsSync(hookPath)) {
+    const existing = await fs.readFile(hookPath, 'utf8');
+    if (!existing.includes('AODW v0 trace guard hook')) {
+      if (!silent) {
+        console.log(chalk.yellow('⚠️ 检测到已有 pre-commit hook。'));
+        console.log(chalk.yellow('   为避免覆盖你的自定义逻辑，本次不自动改写。'));
+        console.log(chalk.cyan('   建议手工在现有 hook 中加入: aodw-skill guard --auto-fix --stage-audit'));
+      }
+      shouldOverwrite = false;
+    }
+  }
+
+  if (!shouldOverwrite) {
+    process.exitCode = 1;
+    return;
+  }
+
+  await fs.writeFile(hookPath, getHookContent(), 'utf8');
+  await fs.chmod(hookPath, 0o755);
+
+  if (!silent) {
+    console.log(chalk.green('✅ 已启用 AODW v0 guard pre-commit hook。'));
+    console.log(chalk.gray('   提交时将自动检查并自动补录最小流程痕迹。'));
+  }
+}
+

package/bin/commands/trace-guard.js

@@ -0,0 +1,156 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+
+const CORE_DIR = process.env.AODW_CORE_DIR || '.aodw-next';
+
+function getStagedFiles() {
+  try {
+    const output = execSync('git diff --cached --name-only --diff-filter=ACMR', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return output
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean);
+  } catch (error) {
+    throw new Error('无法读取 staged 文件，请确认当前目录是 git 仓库并且 git 可用。');
+  }
+}
+
+function isCodePath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+
+  // v0: 先覆盖最关键目录，避免规则过重
+  if (normalized.startsWith('cli/') || normalized.startsWith('templates/')) {
+    return true;
+  }
+
+  // 面向用户项目的常见代码目录（保持宽松，不做复杂识别）
+  const commonCodeDirs = ['src/', 'app/', 'backend/', 'frontend/', 'api/'];
+  return commonCodeDirs.some((dir) => normalized.startsWith(dir));
+}
+
+function isTracePath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+
+  const tracePrefixes = [
+    'RT/',
+    'maintainers/',
+    `${CORE_DIR}/06-project/`,
+  ];
+
+  if (tracePrefixes.some((prefix) => normalized.startsWith(prefix))) {
+    return true;
+  }
+
+  const traceFileNames = ['rt-lite.md', 'meta.yaml', 'changelog.md', 'tests.md'];
+  return traceFileNames.some((name) => normalized.endsWith(`/${name}`) || normalized === name);
+}
+
+function splitFiles(stagedFiles) {
+  const codeFiles = stagedFiles.filter(isCodePath);
+  const traceFiles = stagedFiles.filter(isTracePath);
+  const otherFiles = stagedFiles.filter((filePath) => !codeFiles.includes(filePath) && !traceFiles.includes(filePath));
+
+  return { codeFiles, traceFiles, otherFiles };
+}
+
+function writeAuditDraft(stagedFiles, splitResult) {
+  const { codeFiles, traceFiles, otherFiles } = splitResult;
+  const now = new Date().toISOString();
+  const lines = [
+    '# AODW Audit Draft',
+    '',
+    `- generated_at: ${now}`,
+    `- staged_files_count: ${stagedFiles.length}`,
+    '',
+    '## 1) Code Changes',
+    ...(codeFiles.length > 0 ? codeFiles.map((f) => `- ${f}`) : ['- (none)']),
+    '',
+    '## 2) Trace Updates',
+    ...(traceFiles.length > 0 ? traceFiles.map((f) => `- ${f}`) : ['- (none)']),
+    '',
+    '## 3) Other Changes',
+    ...(otherFiles.length > 0 ? otherFiles.map((f) => `- ${f}`) : ['- (none)']),
+    '',
+    '## 4) Fill-in Checklist',
+    '- 改了什么（1-3 行）：',
+    '- 影响范围（模块/目录）：',
+    '- 验证方式（最小步骤）：',
+    '',
+  ];
+
+  const outputPath = path.join(process.cwd(), CORE_DIR, '06-project', 'audit-latest.md');
+  fs.ensureDirSync(path.dirname(outputPath));
+  fs.writeFileSync(outputPath, `${lines.join('\n')}\n`, 'utf8');
+  return outputPath;
+}
+
+function stageFile(filePath) {
+  const relativePath = path.relative(process.cwd(), filePath);
+  execSync(`git add "${relativePath}"`, { stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+export function guardDocTrace(options = {}) {
+  const { autoFix = false, stageAudit = false } = options;
+  const stagedFiles = getStagedFiles();
+  const splitResult = splitFiles(stagedFiles);
+  const { codeFiles, traceFiles } = splitResult;
+
+  if (codeFiles.length === 0) {
+    console.log(chalk.green('✅ guard 通过：未检测到代码目录改动。'));
+    return;
+  }
+
+  if (traceFiles.length > 0) {
+    console.log(chalk.green('✅ guard 通过：检测到流程痕迹更新。'));
+    return;
+  }
+
+  if (autoFix) {
+    try {
+      const outputPath = writeAuditDraft(stagedFiles, splitResult);
+      if (stageAudit) {
+        stageFile(outputPath);
+      }
+      console.log(chalk.yellow('⚠️ guard 自动补录：检测到代码改动但无流程痕迹。'));
+      console.log(chalk.green(`✅ 已自动生成${stageAudit ? '并暂存' : ''}补录文件: ${path.relative(process.cwd(), outputPath)}`));
+      return;
+    } catch (error) {
+      console.log(chalk.red(`❌ guard 自动补录失败: ${error.message}`));
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  console.log(chalk.red('\n❌ guard 未通过：检测到代码改动，但未检测到流程痕迹更新。'));
+  console.log(chalk.yellow('\n检测到的代码改动:'));
+  codeFiles.forEach((file) => console.log(chalk.yellow(`  - ${file}`)));
+
+  console.log(chalk.cyan('\n补救建议（v0）:'));
+  console.log(chalk.cyan('  1) 运行: aodw-skill audit --write'));
+  console.log(chalk.cyan(`  2) 或手工更新 ${CORE_DIR}/06-project/ 或 RT/ 或 maintainers/ 下的记录`));
+
+  process.exitCode = 1;
+}
+
+export async function auditDocTrace(options = {}) {
+  const stagedFiles = getStagedFiles();
+  const splitResult = splitFiles(stagedFiles);
+  const outputPath = path.join(process.cwd(), CORE_DIR, '06-project', 'audit-latest.md');
+
+  if (options.write) {
+    writeAuditDraft(stagedFiles, splitResult);
+    console.log(chalk.green(`✅ 已写入审计草稿: ${path.relative(process.cwd(), outputPath)}`));
+    return;
+  }
+
+  writeAuditDraft(stagedFiles, splitResult);
+  const content = await fs.readFile(outputPath, 'utf8');
+  await fs.remove(outputPath);
+  console.log(content);
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aodw-skill",
-  "version": "0.7.24",
+  "version": "0.7.25",
   "description": "Next-channel CLI tool to scaffold AODW in your project",
   "main": "bin/aodw.js",
   "files": [