@ultime/codecraft 1.0.3 → 1.2.0

package/docs/04-gates.md

@@ -1,6 +1,7 @@
 # Gates（两层门禁）
 
 > Codecraft 只内置“规范性通用门禁”；业务门禁由项目实现，Codecraft 负责编排与汇总。
+> 示例命令按 JS/TS 生态（`pnpm`）书写；gate 契约本身与语言无关，Node 项目同样适用。
 
 ## 1. 两层模型
 
@@ -30,12 +31,16 @@
   "gates": [
     { "name": "typecheck", "run": "pnpm typecheck", "timeoutMs": 120000 },
     { "name": "test", "run": "pnpm test", "timeoutMs": 120000 }
+  ],
+  "ignore": [
+    { "rule": "A17", "file": "src/pages/legacy/**", "reason": "legacy page", "expires": "2026-12-31" }
   ]
 }
 ```
 
 - `pack`：`app` / `library` / `design-system` / `auto`；CLI `--pack` 优先。
 - `gates`：数组；每项必须有 `run`，可选 `name` / `timeoutMs`。
+- `ignore`：例外登记（A12）；`rule` / `file` / `reason` 必填，`expires` 可选。过期条目不生效，报告中单列；安全规则 `A21` 不可豁免。
 - 配置文件默认 `codecraft.config.json`；可用 `--config` 指定。
 
 ## 4. 按项目类型选门禁

package/docs/05-patterns.md

@@ -1,6 +1,7 @@
 # 设计模式工具箱（可选）
 
 > 用途：AI 与人的「可选工具」，不是必背清单；按力（forces）选，不按名字选。
+> 范围：模式本身与语言无关；第 4 / 5 节分别是 JS/TS 惯用与前端 / UI 专用。
 > 术语：English（中文）。
 > 原则：**先有痛点，再选模式；没有代价说明的模式，不许用。**
 

package/docs/06-architecture.md

@@ -2,6 +2,7 @@
 
 > 用途：系统级 / 模块级 / 演进级的决策方法；代码级模式见 `05-patterns.md`。
 > 原则：**方法先于模式；约束先于图；边界先于抽象。**
+> 范围：方法本身与语言无关，可用于 JS/TS 前端与 Node 后端；文中目录与框架取舍以 JS/TS 为准。
 > 术语：English（中文）。
 
 ## 0. 先分开六个词
@@ -104,6 +105,7 @@ src/
 ```
 
 - 依赖只能向下；同层不互相 import；跨模块只走 public API。
+- 结构默认与框架无关：原生能表达的先写原生，Vue / React 只作页面与组件的落点。
 - `shared/api` + adapter + interceptors 是承重墙，不塞进 feature。
 - server state 与 client state 分开：server state 用 query 层；client state 用 store / 状态机。
 - 测试分层：纯 core 单测 → feature 行为测试 → 页面 smoke → API 契约测试。

package/docs/07-ai-prompts.md

@@ -1,12 +1,28 @@
 # AI 使用提示词（Prompts）
 
 > 用途：给使用者一份可以直接复制的说法，让 AI 按 Codecraft 的模式工作。
+> 范围：提示词按 JS/TS 项目写；Node 后端只复用审计 / 架构 / 评审类提示词。
 > 读法：先看「最小开场」，再按场景复制；提示词不替代规则，规则正文仍在 `docs/`。
 > 关系：入口见 `adapters/`；输出格式见 `prompts/output.md`；约束见 `02-ai-contract.md`。
 
 ## 1. 先让 AI 找到 Codecraft
 
-在项目的 agent 入口里留一条指针，不要复制规则：
+最快的方式：
+
+```bash
+npx @ultime/codecraft install
+```
+
+或走 npm 同步：
+
+```bash
+npm i -D @ultime/codecraft skills-npm
+npx skills-npm setup
+```
+
+装好后项目里会有 `.agents/skills/codecraft/SKILL.md`（以及检测到的 agent 目录）。
+
+也可以手动在 agent 入口里留一条指针，不要复制规则：
 
 - Trae：项目 `.trae/rules/codecraft.md`
 - Claude：`CLAUDE.md`

package/evals/golden-tasks.md

@@ -1,5 +1,7 @@
 # Golden Tasks（评估任务）
 
+> 任务默认按 JS/TS 前端项目设计；Node 后端只复用审计 / 架构 / 评审类任务，数据库、缓存、并发不在本批评估内。
+
 用于验证 skill 是否真的按规范工作。每条任务记录：结果、版本、误报 / 漏报。
 
 ## 1. 新项目架构计划
@@ -107,6 +109,13 @@
 - 期望：命中 A21；只报文件与行号，不回显密钥；提示轮换。
 - 失败信号：漏报；把密钥原文打印到报告；把普通变量名误报为密钥。
 
+## 16. 安装到 agent
+
+- 输入：空项目，无 agent 配置目录。
+- 命令：`codecraft install --root . --agent generic`；再执行一次；最后 `--force`。
+- 期望：生成 `.agents/skills/codecraft/SKILL.md`、`docs/`、`scenarios/`、`prompts/`；第二次 skip；`--force` 覆盖。
+- 失败信号：复制到错误目录；覆盖用户已有内容；`SKILL.md` 引用断链。
+
 ## 评分
 
 - 每条任务：pass / fail。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.0.3",
-  "description": "Language-agnostic code standard as an installable skill package.",
+  "version": "1.2.0",
+  "description": "面向 JS/TS 的代码规范与架构设计（前端默认，Node 后端可复用结构规则），作为可安装的 skill 包。",
   "keywords": [
     "ai",
     "code-standard",
@@ -10,7 +10,8 @@
     "audit",
     "architecture",
     "review",
-    "scaffold"
+    "scaffold",
+    "agent-skills"
   ],
   "author": "UltimeLam",
   "license": "MIT",
@@ -30,6 +31,7 @@
     "codecraft": "bin/codecraft.mjs"
   },
   "files": [
+    "SKILL.md",
     "bin",
     "src",
     "docs",

package/src/cli.mjs

@@ -4,6 +4,8 @@ import { check } from './check.mjs'
 import { loadConfig, runGates } from './gates.mjs'
 import { buildPlan, summarizePlan } from './plan.mjs'
 import { applyInitPlan, buildInitPlan } from './init.mjs'
+import { applyIgnores } from './ignore.mjs'
+import { applyInstallPlan, buildInstallPlan, parseAgents } from './install.mjs'
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
 const VERSION = PACKAGE.version
@@ -15,12 +17,18 @@ Commands:
   audit       check + configured gates; read-only report
   plan        Read-only upgrade plan from findings
   init        Scaffold an app or package (dry-run unless --apply)
+  install     Install the skill into agent skills directories
   version     Print version
 
 Options:
   --root <path>            Project root (default: cwd)
   --pack app|library|design-system|auto  Rule pack (default: auto)
   --config <path>          Config file (default: codecraft.config.json)
+  --agent auto|claude|trae|cursor|generic  Install target, comma-separated (default: auto)
+  --global                 Install into the home directory
+  --dest <path>            Explicit destination (relative to root / home)
+  --force                  Replace an existing codecraft skill directory
+  --dry-run                Show the install plan without writing
   --no-gates               Skip gates in audit / plan
   --with-gates             Run configured gates in plan
   --fail-fast              Stop gates after the first failure
@@ -51,17 +59,53 @@ export function main(argv) {
   }
 
   const command = args.command || 'check'
-  if (!['check', 'audit', 'plan', 'init'].includes(command)) {
-    console.error(`codecraft: unknown command "${command}"`)
+  if (!['check', 'audit', 'plan', 'init', 'install'].includes(command)) {
+    console.error(`codecraft: unknown command "${command}"\n  next: run codecraft --help`)
     return 2
   }
 
   const root = path.resolve(process.cwd(), args.root)
   if (!fs.existsSync(root)) {
-    console.error(`codecraft: root not found: ${root}`)
+    console.error(`codecraft: root not found: ${root}\n  next: pass --root <project> or run from the project directory`)
     return 2
   }
 
+  if (command === 'install') {
+    let agents
+    try {
+      agents = parseAgents(args.agent)
+    } catch (error) {
+      console.error(`codecraft: ${error.message}`)
+      return 2
+    }
+    try {
+      const plan = buildInstallPlan(root, { agents, global: args.global, dest: args.dest })
+      const applied = args.dryRun ? null : applyInstallPlan(plan, { force: args.force })
+      const meta = {
+        version: VERSION,
+        mode: 'install',
+        root,
+        scope: args.global ? 'global' : 'project',
+        agent: args.agent,
+        dest: args.dest || null,
+        dryRun: args.dryRun,
+        targets: plan.length,
+        created: applied?.created.length ?? 0,
+        replaced: applied?.replaced.length ?? 0,
+        skipped: applied?.skipped.length ?? 0,
+      }
+      if (args.format === 'json') {
+        console.log(JSON.stringify({ ...meta, plan, applied }, null, 2))
+      } else {
+        console.log(formatInstall(meta, plan, applied))
+      }
+      return plan.length ? 0 : 1
+    } catch (error) {
+      console.error(`codecraft: ${error.message}`)
+      return 1
+    }
+  }
+
   let config
   try {
     config = loadConfig(root, args.config)
@@ -72,13 +116,15 @@ export function main(argv) {
 
   const pack = resolvePack(args.pack, config.config.pack, root)
   if (!pack) {
-    console.error('codecraft: invalid config pack; expected app, library or auto')
+    console.error(
+      `codecraft: invalid config pack "${config.config.pack}"\n  next: use app, library, design-system or auto`,
+    )
     return 2
   }
 
   if (command === 'init') {
     if (args.apply && !args.name) {
-      console.error('codecraft: init --apply requires --name <name>')
+      console.error('codecraft: init --apply requires --name <name>\n  next: add --name <demo>')
       return 2
     }
     const plan = buildInitPlan(root, pack === 'design-system' ? 'library' : pack, args.name)
@@ -106,10 +152,12 @@ export function main(argv) {
   const result = check(root, { pack })
   const severity = args.ci ? 'error' : args.severity
   const findings = result.findings.map((finding) => ({ ...finding, severity }))
+  const filtered = applyIgnores(findings, config.config.ignore ?? [])
+  const activeFindings = filtered.findings
   const gates = shouldRunGates(command, args)
     ? runGates(root, config.config.gates ?? [], { failFast: args.failFast })
     : []
-  const plan = command === 'plan' ? buildPlan(findings) : []
+  const plan = command === 'plan' ? buildPlan(activeFindings) : []
   const meta = {
     version: VERSION,
     mode: command,
@@ -119,7 +167,9 @@ export function main(argv) {
     severity,
     rules: pack === 'app' ? ['A17', 'A21'] : ['A2', 'A11', 'A21'],
     files: result.files,
-    findings: findings.length,
+    findings: activeFindings.length,
+    ignored: filtered.ignored.length,
+    expired: filtered.expired.length,
     plan: plan.length,
     gates: gates.length,
   }
@@ -129,12 +179,16 @@ export function main(argv) {
       JSON.stringify(
         {
           ...meta,
-          findings,
+          findings: activeFindings,
+          ignored: filtered.ignored,
+          exceptions: filtered.exceptions,
           plan,
           gates,
           summary: {
             files: result.files,
-            findings: findings.length,
+            findings: activeFindings.length,
+            ignored: filtered.ignored.length,
+            expired: filtered.expired.length,
             plan: plan.length,
             gates: gates.length,
             gateFailures: gates.filter((gate) => gate.exitCode !== 0).length,
@@ -145,12 +199,14 @@ export function main(argv) {
       ),
     )
   } else if (command === 'plan') {
-    console.log(formatPlan(meta, findings, plan, gates))
+    console.log(formatPlan(meta, activeFindings, plan, gates))
   } else {
-    console.log(formatReport(meta, findings, gates))
+    console.log(formatReport(meta, activeFindings, filtered.ignored, filtered.expired, gates))
   }
 
-  const failed = findings.some((finding) => finding.severity === 'error') || gates.some((gate) => gate.exitCode !== 0)
+  const failed =
+    activeFindings.some((finding) => finding.severity === 'error') ||
+    gates.some((gate) => gate.exitCode !== 0)
   return failed ? 1 : 0
 }
 
@@ -180,6 +236,11 @@ function parseArgs(argv) {
     failFast: false,
     name: '',
     apply: false,
+    agent: 'auto',
+    global: false,
+    dest: '',
+    force: false,
+    dryRun: false,
     format: 'md',
     severity: 'warn',
     ci: false,
@@ -196,7 +257,12 @@ function parseArgs(argv) {
     else if (arg === '--with-gates') args.withGates = true
     else if (arg === '--fail-fast') args.failFast = true
     else if (arg === '--apply') args.apply = true
+    else if (arg === '--global') args.global = true
+    else if (arg === '--force') args.force = true
+    else if (arg === '--dry-run') args.dryRun = true
     else if (arg === '--name') args.name = argv[++i] ?? ''
+    else if (arg === '--agent') args.agent = argv[++i] ?? 'auto'
+    else if (arg === '--dest') args.dest = argv[++i] ?? ''
     else if (arg === '--root') args.root = argv[++i] ?? '.'
     else if (arg === '--pack') args.pack = argv[++i] ?? 'auto'
     else if (arg === '--config') args.config = argv[++i] ?? ''
@@ -227,7 +293,7 @@ function fail(message) {
   process.exit(2)
 }
 
-function formatReport(meta, findings, gates) {
+function formatReport(meta, findings, ignored, expired, gates) {
   const lines = header(meta)
 
   if (!findings.length) {
@@ -239,6 +305,35 @@ function formatReport(meta, findings, gates) {
     }
   }
 
+  if (ignored.length) {
+    lines.push(
+      '',
+      '## Ignored',
+      '',
+      '| Rule | File | Line | Reason | Expires |',
+      '|---|---|---|---|---|',
+    )
+    for (const finding of ignored) {
+      lines.push(
+        `| ${finding.rule} | ${finding.file} | ${finding.line} | ${escapeCell(finding.reason)} | ${finding.expires ?? '—'} |`,
+      )
+    }
+  }
+
+  if (expired.length) {
+    lines.push(
+      '',
+      '## Expired Exceptions',
+      '',
+      '| Rule | File | Expires | Reason |',
+      '|---|---|---|---|',
+    )
+    for (const exception of expired) {
+      lines.push(`| ${exception.rule} | ${exception.file} | ${exception.expires} | ${escapeCell(exception.reason)} |`)
+    }
+    lines.push('', '- Expired exceptions no longer suppress findings; renew the date or remove the entry.')
+  }
+
   lines.push(...gateLines(gates))
   return lines.join('\n')
 }
@@ -329,6 +424,49 @@ function formatInit(meta, plan, applied) {
   return lines.filter((line, index) => !(line === '' && lines[index - 1] === '')).join('\n')
 }
 
+function formatInstall(meta, plan, applied) {
+  const lines = [
+    '# Codecraft Install',
+    '',
+    `- Version: ${meta.version}`,
+    `- Mode: install`,
+    `- Scope: ${meta.scope}`,
+    `- Agent: ${meta.agent}`,
+    `- Root: ${meta.root}`,
+    `- Dest: ${meta.dest ?? '（auto）'}`,
+    `- Dry run: ${meta.dryRun}`,
+    `- Targets: ${meta.targets}`,
+  ]
+
+  if (applied) {
+    lines.push(
+      `- Created: ${meta.created}`,
+      `- Replaced: ${meta.replaced}`,
+      `- Skipped: ${meta.skipped}`,
+    )
+  }
+
+  if (!plan.length) {
+    lines.push('', '未找到可安装的目标；请用 `--agent` 指定，或先创建 agent 配置目录。')
+  } else {
+    lines.push('', '## Plan', '', '| Agent | Target | Action |', '|---|---|---|')
+    for (const entry of plan) {
+      lines.push(`| ${entry.agent} | ${entry.target} | ${entry.action} |`)
+    }
+  }
+
+  lines.push(
+    '',
+    '## Next',
+    '',
+    meta.dryRun
+      ? '- Re-run without `--dry-run` to write the skill.'
+      : '- Restart the agent or reload skills；然后说：`用 Codecraft 审计本项目，只读，不改文件。`',
+  )
+
+  return lines.join('\n')
+}
+
 function header(meta) {
   return [
     `# Codecraft ${title(meta.mode)}`,
@@ -342,6 +480,8 @@ function header(meta) {
     `- Severity: ${meta.severity}`,
     `- Files: ${meta.files}`,
     `- Findings: ${meta.findings}`,
+    `- Ignored: ${meta.ignored ?? 0}`,
+    `- Expired exceptions: ${meta.expired ?? 0}`,
     `- Gates: ${meta.gates}`,
     '',
   ]

package/src/gates.mjs

@@ -1,30 +1,33 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { validateIgnore } from './ignore.mjs'
 
 export function loadConfig(root, configPath) {
   const file = configPath ? path.resolve(root, configPath) : path.join(root, 'codecraft.config.json')
 
-  if (!fs.existsSync(file)) return { file: null, config: {} }
+  if (!fs.existsSync(file)) return { file: null, config: { ignore: [] } }
 
   let config
   try {
     config = JSON.parse(fs.readFileSync(file, 'utf8'))
   } catch (error) {
-    throw new Error(`invalid config ${file}: ${error.message}`)
+    throw new Error(
+      `invalid config ${file}: ${error.message} (fix the JSON syntax, or remove the file to use defaults)`,
+    )
   }
 
   if (config.gates != null && !Array.isArray(config.gates)) {
-    throw new Error(`invalid config ${file}: "gates" must be an array`)
+    throw new Error(`invalid config ${file}: "gates" must be an array (each item: { name?, run, timeoutMs? })`)
   }
 
   for (const gate of config.gates ?? []) {
     if (!gate || typeof gate.run !== 'string' || !gate.run.trim()) {
-      throw new Error(`invalid config ${file}: each gate needs a "run" string`)
+      throw new Error(`invalid config ${file}: each gate needs a "run" string (e.g. "pnpm test")`)
     }
   }
 
-  return { file, config }
+  return { file, config: { ...config, ignore: validateIgnore(config.ignore, file) } }
 }
 
 export function runGates(root, gates, options = {}) {

package/src/ignore.mjs

@@ -0,0 +1,145 @@
+const DATE = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * 校验并规范化 ignore 条目。
+ * 每条必须有 rule / file / reason；expires 可选（YYYY-MM-DD）。
+ */
+export function validateIgnore(entries, configFile = 'config') {
+  if (entries == null) return []
+  if (!Array.isArray(entries)) {
+    throw new Error(
+      `invalid config ${configFile}: "ignore" must be an array (each item: { rule, file, reason, expires? })`,
+    )
+  }
+
+  return entries.map((entry, index) => {
+    const at = `ignore[${index}]`
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new Error(`invalid config ${configFile}: ${at} must be an object`)
+    }
+
+    const rule = typeof entry.rule === 'string' ? entry.rule.trim() : ''
+    if (!/^A\d+$/.test(rule)) {
+      throw new Error(`invalid config ${configFile}: ${at}.rule must be a rule id like "A17"`)
+    }
+    if (rule === 'A21') {
+      throw new Error(
+        `invalid config ${configFile}: ${at}.rule A21 is a security rule and cannot be ignored (safety red line)`,
+      )
+    }
+
+    const file = typeof entry.file === 'string' ? entry.file.trim() : ''
+    if (!file) {
+      throw new Error(`invalid config ${configFile}: ${at}.file is required (path or glob, e.g. "src/pages/legacy/**")`)
+    }
+
+    const reason = typeof entry.reason === 'string' ? entry.reason.trim() : ''
+    if (!reason) {
+      throw new Error(`invalid config ${configFile}: ${at}.reason is required (A12: every exception needs a reason)`)
+    }
+
+    const expires = entry.expires == null || entry.expires === '' ? null : String(entry.expires).trim()
+    if (expires && !isDate(expires)) {
+      throw new Error(`invalid config ${configFile}: ${at}.expires must be YYYY-MM-DD`)
+    }
+
+    return { rule, file, reason, expires }
+  })
+}
+
+/**
+ * 把 ignore 应用到 findings 上。
+ * 过期条目不生效，单独返回，供报告提示续期或删除。
+ */
+export function applyIgnores(findings, exceptions, options = {}) {
+  const today = options.today ?? localDate()
+  const active = []
+  const expired = []
+
+  for (const exception of exceptions) {
+    if (exception.expires && exception.expires < today) expired.push(exception)
+    else active.push(exception)
+  }
+
+  const kept = []
+  const ignored = []
+
+  for (const finding of findings) {
+    const matched = active.find(
+      (exception) => exception.rule === finding.rule && matchPath(exception.file, finding.file),
+    )
+    if (matched) ignored.push({ ...finding, reason: matched.reason, expires: matched.expires })
+    else kept.push(finding)
+  }
+
+  return {
+    findings: kept,
+    ignored,
+    exceptions: [
+      ...active.map((exception) => ({ ...exception, status: 'active' })),
+      ...expired.map((exception) => ({ ...exception, status: 'expired' })),
+    ],
+    expired,
+  }
+}
+
+/** 支持 * / ** / ? 的路径匹配；不含通配符时按精确路径或目录前缀匹配。 */
+export function matchPath(pattern, file) {
+  const normalizedPattern = normalize(pattern)
+  const normalizedFile = normalize(file)
+
+  if (!/[*?]/.test(normalizedPattern)) {
+    return (
+      normalizedFile === normalizedPattern ||
+      (normalizedPattern.endsWith('/') && normalizedFile.startsWith(normalizedPattern))
+    )
+  }
+
+  return globToRegExp(normalizedPattern).test(normalizedFile)
+}
+
+function normalize(value) {
+  return String(value)
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+}
+
+function globToRegExp(pattern) {
+  let source = '^'
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index]
+    if (char === '*') {
+      if (pattern[index + 1] === '*') {
+        index += 1
+        if (pattern[index + 1] === '/') {
+          source += '(?:.*/)?'
+          index += 1
+        } else {
+          source += '.*'
+        }
+      } else {
+        source += '[^/]*'
+      }
+    } else if (char === '?') {
+      source += '[^/]'
+    } else if ('\\^$+?.()|{}[]'.includes(char)) {
+      source += `\\${char}`
+    } else {
+      source += char
+    }
+  }
+  return new RegExp(`${source}$`)
+}
+
+function isDate(value) {
+  if (!DATE.test(value)) return false
+  const parsed = new Date(`${value}T00:00:00Z`)
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value
+}
+
+function localDate() {
+  const now = new Date()
+  const month = String(now.getMonth() + 1).padStart(2, '0')
+  const day = String(now.getDate()).padStart(2, '0')
+  return `${now.getFullYear()}-${month}-${day}`
+}