@ultime/codecraft 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## 1.0.0 - 2026-10-26
+
+首个稳定版本。
+
+### 规则体系
+
+- 代码宪法：五条元判据（M1–M5）+ 二十一条不变量（A1–A21），每条含理由与验收。
+- 代码族卡：11 个代码族的职责、形状、命名、契约、状态与错误、测试、正反例、验收。
+- AI 生成契约：先读顺序、禁止项、模式边界与安全红线。
+- 风格总图：中性总览，用于跨项目复用。
+- 设计模式工具箱：按「力」选型，不按模式名字选型。
+- 架构设计方法：档位、七步法、C4 最小集、边界切分、依赖规则、ADR、反模式与评审清单。
+
+### CLI
+
+- 命令：`check` / `audit` / `plan` / `init` / `version`。
+- Rule Packs：`app` / `library` / `design-system` / `auto`。
+- 内置检查：A2（包依赖方向）、A11（生成物标记）、A17（内部不 import external / generated）、A21（密钥扫描与公开文档路径）。
+- `init` 默认 dry-run；`--apply --name <name>` 写入 app / library 骨架，已存在路径跳过、不覆盖。
+- 输出 Markdown（默认）或 JSON；报告带版本号与规则 ID。
+- 退出码：`0` 通过、`1` 有 error 或 gate 失败、`2` 用法 / 配置错误。
+- 选项：`--root`、`--pack`、`--config`、`--format`、`--severity`、`--ci`、`--fail-fast`、`--no-gates`、`--with-gates`。
+
+### 门禁
+
+- 两层模型：通用规则内置，业务门禁由项目实现、由 `codecraft.config.json` 编排。
+- Gate Contract：非交互、幂等、只读、有超时（默认 120s）、失败输出下一步。
+- `audit` 汇总内置规则与业务 gate；`plan` 默认只读，`--with-gates` 才执行门禁。
+- `--fail-fast` 在第一个 gate 失败时停止。
+
+### 适配器与脚手架
+
+- 适配器：generic（`AGENTS.md`）、Trae（`SKILL.md`）、Claude（`SKILL.md`）。
+- 场景：新项目、旧项目审计、只出报告、重构评审。
+- 统一输出格式：结论 / 证据 / 差距与风险 / 计划 / 验证 / 下一步。
+- 模板：`app` 与 `library` 的 README、package.json、CHANGELOG、compat。
+
+### 工程
+
+- MIT 许可；贡献流程与安全报告流程。
+- `node:test` 用例覆盖内置规则、gates、CLI 与脚手架。
+- golden tasks 用于人工回归。

package/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing（贡献指南）
+
+> 定位：给贡献者与 AI 的最短协作规则；规范正文在 `docs/`。
+> 状态：现行（2026-10）。
+> 关系：行为约束见 `docs/02-ai-contract.md`；门禁口径见 `docs/04-gates.md`。
+
+## 工作流
+
+1. 从 `main` 切分支：`feat/<主题>` / `fix/<主题>`。
+2. 开发完成后 `git rebase main`，再合并回 `main`；主分支不保留中间提交。
+3. 一次提交一件事；提交信息用 `type(scope): subject`，正文写「为什么」。
+
+## 改规则
+
+- 先改本地底稿，确认后再改 `docs/`；不在本仓保留调研来源。
+- 规则改动必须同时更新：规则正文、`evals/golden-tasks.md`、相关测试。
+- 契约类改动（档位 / 命名 / 单位 / 角色）整族刷新，不做零散小改。
+
+## 验证
+
+```bash
+node --test tests/*.test.mjs
+node bin/codecraft.mjs check --root <项目>
+```
+
+- 新增 / 修改规则必须补测试；没有反例的规则降级为「参考」。
+- 不提交密钥、客户名、内部路径；发现疑似凭据立即停止并提示轮换。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ultime contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# Codecraft（代码手艺）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 语言无关的代码规范，作为可安装的 skill 包。
+> 让 AI 和人在新项目、旧项目、评审中按同一套约束工作，并能按版本引入。
+
+- 版本：`1.0.0`（[VERSION](./VERSION)）
+- 许可：MIT（[LICENSE](./LICENSE)）
+- 环境：Node.js >= 20；零运行时依赖
+- 形态：规则文档 + 场景 + 适配器 + CLI + 脚手架
+
+## 这是什么
+
+| 是 | 不是 |
+|---|---|
+| 一套可执行的代码宪法（A1–A21）与代码族卡 | 业务组件库 |
+| 面向 AI 的固定入口与输出格式 | 某个框架的编码风格指南 |
+| 通用规则的静态检查 + 项目门禁编排 | 替代 typecheck / 单测 / e2e |
+
+规则正文只在 [`docs/`](./docs/)；其它位置只放入口与指针，避免第二份真源。
+
+## 快速开始
+
+### 1. 直接运行
+
+```bash
+# 在 codecraft 目录内
+node bin/codecraft.mjs check --root .
+
+# 检查任意项目
+node /path/to/codecraft/bin/codecraft.mjs check --root /path/to/project
+```
+
+### 2. 安装 / 运行
+
+包名 `@ultime/codecraft`，命令 `codecraft`。发布到 npm 后可直接运行：
+
+```bash
+npx @ultime/codecraft check --root .
+npx @ultime/codecraft@1.0.0 check --root .
+```
+
+安装为项目依赖：
+
+```bash
+npm i -D @ultime/codecraft
+npx codecraft check --root .
+```
+
+本地开发 / 未发布时用 tarball：
+
+```bash
+npm pack
+npm i -D /path/to/ultime-codecraft-1.0.0.tgz
+npx codecraft check --root .
+```
+
+也可以直接 `pnpm link --global /path/to/codecraft`，之后在任意目录使用 `codecraft`。
+
+### 3. 接入 agent（作为 skill）
+
+适配器只做入口，不复制规则：
+
+| 平台 | 入口文件 |
+|---|---|
+| 通用（读 `AGENTS.md`） | [`adapters/generic/AGENTS.md`](./adapters/generic/AGENTS.md) |
+| Trae | [`adapters/trae/SKILL.md`](./adapters/trae/SKILL.md) |
+| Claude | [`adapters/claude/SKILL.md`](./adapters/claude/SKILL.md) |
+
+推荐**指针式接入**——不复制规则，升级只需更新仓库：
+
+- Trae：在项目 `.trae/rules/codecraft.md` 写一行「代码任务先读 `<本仓库绝对路径>/adapters/trae/SKILL.md`」。
+- Claude：在 `~/.claude/CLAUDE.md` 或项目 `CLAUDE.md` 加同一行。
+- 其他 agent：在项目 `AGENTS.md` 加同一行。
+
+如果确实要把 `SKILL.md` 复制到 agent 的 skills 目录，必须让 `docs/`、`scenarios/`、`prompts/` 与该文件保持 `../../` 的相对位置（符号链接即可），否则入口里的路径会失效。
+
+## 三种模式
+
+| 模式 | 是否改文件 | 对应命令 |
+|---|---|---|
+| **Audit（审计）** | 否 | `check` / `audit` |
+| **Plan（计划）** | 否 | `plan` |
+| **Apply（执行）** | 是，需确认范围 | 人工按计划改；`init --apply` 只创建骨架 |
+
+## CLI
+
+```bash
+codecraft <command> [options]
+```
+
+| 命令 | 作用 |
+|---|---|
+| `check` | 只跑内置规则（默认命令） |
+| `audit` | 内置规则 + `codecraft.config.json` 里的 gates，出只读报告 |
+| `plan` | 把 findings 转成只读升级计划；默认不跑 gates |
+| `init` | 生成 app / library 骨架；默认 dry-run |
+| `version` | 输出版本号 |
+
+### 常用
+
+```bash
+codecraft check --root .
+codecraft check --pack library --root ../../packages/core
+codecraft check --pack design-system
+codecraft check --format json --ci
+codecraft audit --severity error
+codecraft audit --config codecraft.config.json --fail-fast
+codecraft plan --root . --with-gates
+codecraft init --root . --name demo              # dry-run
+codecraft init --root . --name demo --apply      # 写盘
+```
+
+### 参数
+
+| 参数 | 取值 | 默认 | 说明 |
+|---|---|---|---|
+| `--root <path>` | 目录 | `.` | 被检查的项目根 |
+| `--pack <name>` | `app` / `library` / `design-system` / `auto` | `auto` | 规则包；CLI 优先于 config |
+| `--config <path>` | 文件 | `codecraft.config.json` | 相对 `--root` |
+| `--format <fmt>` | `md` / `json` | `md` | 输出格式 |
+| `--severity <level>` | `warn` / `error` | `warn` | findings 的严重级别 |
+| `--ci` | — | 关 | 等价于 `--severity error` |
+| `--fail-fast` | — | 关 | gates 遇到第一个失败即停止 |
+| `--no-gates` | — | 关 | `audit` 跳过 gates |
+| `--with-gates` | — | 关 | `plan` 执行 gates |
+| `--name <name>` | 字符串 | — | `init` 的 app / package 名称；`--apply` 时必填 |
+| `--apply` | — | 关 | `init` 写盘；已存在路径跳过，不覆盖 |
+
+### 退出码
+
+| 码 | 含义 |
+|---|---|
+| `0` | 通过；warning 不阻断 |
+| `1` | 有 error findings，或有 gate 失败 |
+| `2` | 用法错误、root 不存在、配置非法 |
+
+### 输出
+
+- 默认 Markdown：头部元信息 + Findings 表 + Gates 表。
+- `--format json`：包含 `version` / `mode` / `pack` / `rules` / `findings` / `plan` / `gates` / `summary`，用于 CI、趋势和两次运行 diff。
+- 报告始终带版本号与规则 ID；`plan` 明确声明「No files were changed by this command.」。
+
+## Rule Packs
+
+| Pack | 内置规则 | 检查范围 |
+|---|---|---|
+| `app` | A17 / A21 | `pages / components / behavior` 不 import `external/` / `generated/`；密钥扫描 |
+| `library` | A2 / A11 / A21 | 包不 import app、相对路径不逃逸、workspace 依赖必须声明；生成物必须有“勿手改 / 派生”标记；密钥扫描 |
+| `design-system` | A2 / A11 / A21 | library 规则 + 包内公开文档不得引用内部 `docs/` |
+
+`--pack auto` 的判定顺序：
+
+1. 有 `apps/` 或 `src/pages` → `app`
+2. 有 `packages/` 或根 `package.json` → `library`
+3. 其余 → `app`
+
+`design-system` 不参与自动判定，必须显式指定。
+
+A4（单一收口）属于结构判断，由 review 与项目门禁负责，不由静态扫描替代。
+
+## 配置
+
+项目根放 `codecraft.config.json`（示例见 [`codecraft.config.example.json`](./codecraft.config.example.json)）：
+
+```json
+{
+  "pack": "auto",
+  "gates": [
+    { "name": "typecheck", "run": "pnpm typecheck", "timeoutMs": 120000 },
+    { "name": "kit", "run": "pnpm kit:check", "timeoutMs": 120000 }
+  ]
+}
+```
+
+- `pack`：`app` / `library` / `design-system` / `auto`。
+- `gates`：数组；每项必须有一个非空的 `run` 字符串，可选 `name`、`timeoutMs`（默认 `120000`）。
+- gate 在 `--root` 下通过 shell 执行，注入 `CI=1`；失败时报告尾部 40 行 / 4000 字符。
+- `check` 不跑 gates；`audit` 默认跑；`plan` 只在 `--with-gates` 时跑。
+- 通用规则内置，业务门禁只编排、不复制。构建指引见 [`docs/04-gates.md`](./docs/04-gates.md)。
+
+## 目录
+
+```text
+docs/         宪法、族卡、AI 契约、风格总图、模式、架构、门禁
+scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
+adapters/     generic / Trae / Claude 入口
+prompts/      输出格式
+src/ + bin/   CLI
+tests/        node:test 用例
+templates/    init --apply 的 app / library 骨架
+evals/        golden tasks（人工回归）
+```
+
+## 版本与稳定承诺
+
+- semver；当前 `1.0.0`。
+- 规则 ID `A1–A21` 稳定；增删规则属于 minor 以上的变更。
+- 报告始终携带版本号；跨版本对比以 JSON 为准。
+
+## 边界
+
+- 静态检查是文本级：能覆盖高置信模式，可能漏报或误报；最终以项目门禁与 review 为准。
+- 不内置任何业务规则、框架约定或公司内部门禁。
+- 不读取、不上传代码；所有检查在本地完成。
+
+## 贡献与安全
+
+- 贡献流程：[CONTRIBUTING.md](./CONTRIBUTING.md)
+- 漏洞与密钥报告：[SECURITY.md](./SECURITY.md)
+- 许可：MIT

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy（安全策略）
+
+> 定位：漏洞与凭据泄露的报告方式；不在这里披露细节。
+> 状态：现行（2026-10）。
+> 关系：文档安全边界见 `docs/00-constitution.md` §3.6；AI 约束见 `docs/02-ai-contract.md`。
+
+## 报告
+
+- 不要在公开 Issue 中粘贴密钥、令牌、客户数据或可利用细节。
+- 通过仓库的私有安全通道联系维护者；没有通道时先开一个不含敏感信息的 Issue，说明「需要私下同步」。
+- 报告请包含：受影响的版本、最小复现、影响面、建议修复方向。
+
+## 处理
+
+1. 维护者确认后先轮换已泄露的凭据，再修代码。
+2. 修复进入 `fix/<主题>` 分支，`rebase main` 后合并。
+3. 破坏性修复在 CHANGELOG 标注；需要时补回归测试。
+
+## 范围
+
+- 本包是静态规则与 CLI，不执行网络请求；主要风险是密钥 / 隐私被写进规则、示例或报告。
+- 依赖漏洞按 `npm audit` / 依赖升级处理，不在规则层重复实现。

package/VERSION

@@ -0,0 +1 @@
+1.0.0

package/adapters/README.md

@@ -0,0 +1,10 @@
+# Adapters（适配器）
+
+Core 是 `docs/` + `scenarios/` + `scripts/`；adapters 只做入口，不复制规则。
+
+- `generic/AGENTS.md`：任何读 `AGENTS.md` 的 agent
+- `trae/SKILL.md`：Trae skill
+- `claude/SKILL.md`：Claude skill
+- 未来：Cursor / Copilot / Gemini 等
+
+规则：adapter 只写“读什么、按什么流程、输出什么”，规则正文留在 `docs/`。

package/adapters/claude/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: codecraft
+description: Language-agnostic code standard for designing, auditing, reviewing, and refactoring code. Use when the user asks to design a project architecture, audit an existing project, produce a code review, or scaffold code under a project's code constitution.
+---
+
+# Codecraft（代码手艺）
+
+## 先读
+
+1. 项目 `AGENTS.md` / `rules/`
+2. `../../docs/00-constitution.md`
+3. 只读相关族卡：`../../docs/01-family-cards.md`
+4. 设计架构时：`../../docs/06-architecture.md`
+5. 需要选型时：`../../docs/05-patterns.md`
+6. 选场景：`../../scenarios/`
+
+## 模式
+
+- **Audit（审计）**：只读，出报告。
+- **Plan（计划）**：只读，出架构 / 升级计划。
+- **Apply（执行）**：改代码 + 跑门禁。
+
+## 工作流
+
+1. 判定任务属于哪个场景。
+2. 只读相关族卡，不要一次加载全部。
+3. 先出计划；Apply 前确认范围。
+4. 跑项目验证命令；不能跑要说明原因。
+5. 按 `../../prompts/output.md` 输出。
+
+## 禁止
+
+- Audit / Plan 模式改文件。
+- 把业务逻辑放进 Transport 或 Page。
+- 内部代码 import `external/` 或生成类型。
+- 手改生成物。
+- 写敏感信息；发现即停止、脱敏、提示轮换。
+- 安全红线登记例外。
+
+规则正文只在 `docs/`；本文件只做入口。

package/adapters/generic/AGENTS.md

@@ -0,0 +1,15 @@
+# Codecraft Adapter（通用）
+
+当任务涉及写代码、重构、评审、审计或脚手架时：
+
+1. 读项目 `AGENTS.md` / `rules/`。
+2. 读 `../../docs/00-constitution.md`。
+3. 只读相关的族卡：`../../docs/01-family-cards.md`。
+4. 设计架构时读 `../../docs/06-architecture.md`。
+5. 需要选型时读 `../../docs/05-patterns.md`。
+6. 选一个场景：`../../scenarios/`。
+7. 按 `../../docs/02-ai-contract.md` 执行。
+8. 按 `../../prompts/output.md` 输出。
+9. Audit / Plan 模式禁止改文件；安全红线不可豁免。
+
+不要在这里复制规则；规则正文只在 `docs/`。

package/adapters/trae/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: codecraft
+description: Language-agnostic code standard for designing, auditing, reviewing, and refactoring code. Use when the user asks to design a project architecture, audit an existing project, produce a code review, or scaffold code under a project's code constitution.
+---
+
+# Codecraft（代码手艺）
+
+## 先读
+
+1. 项目 `AGENTS.md` / `rules/`
+2. `../../docs/00-constitution.md`
+3. 只读相关族卡：`../../docs/01-family-cards.md`
+4. 设计架构时：`../../docs/06-architecture.md`
+5. 需要选型时：`../../docs/05-patterns.md`
+6. 选场景：`../../scenarios/`
+
+## 模式
+
+- **Audit（审计）**：只读，出报告。
+- **Plan（计划）**：只读，出架构 / 升级计划。
+- **Apply（执行）**：改代码 + 跑门禁。
+
+## 工作流
+
+1. 判定任务属于哪个场景。
+2. 只读相关族卡，不要一次加载全部。
+3. 先出计划；Apply 前确认范围。
+4. 跑项目验证命令；不能跑要说明原因。
+5. 按 `../../prompts/output.md` 输出。
+
+## 禁止
+
+- Audit / Plan 模式改文件。
+- 把业务逻辑放进 Transport 或 Page。
+- 内部代码 import `external/` 或生成类型。
+- 手改生成物。
+- 写敏感信息；发现即停止、脱敏、提示轮换。
+- 安全红线登记例外。
+
+规则正文只在 `docs/`；本文件只做入口。

package/bin/codecraft.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs'
+
+process.exit(main(process.argv.slice(2)))

package/codecraft.config.example.json

@@ -0,0 +1,15 @@
+{
+  "pack": "auto",
+  "gates": [
+    {
+      "name": "typecheck",
+      "run": "pnpm typecheck",
+      "timeoutMs": 120000
+    },
+    {
+      "name": "kit",
+      "run": "pnpm kit:check",
+      "timeoutMs": 120000
+    }
+  ]
+}