@yss123/cage-cli 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,6 @@
 # @yss123/cage-cli
 
-cage 命令行：gen、check、impact、test、verify、budget、sync、upgrade、dev、migrate
-
-Cage 是通过 TypeScript 声明业务、由框架统一执行权限和数据规则的中后台框架。此包是框架的一部分。
+Cage 的开发命令行：创建项目，抽取领域声明，生成契约与迁移草稿，检查图规则与目录边界，浏览业务图谱，查询能力和运行诊断，并管理开发进程及显式迁移。CLI 是开发与部署工具，不能代替业务命令或自动授予生产权限。
 
 ## 使用
 
@@ -12,6 +10,74 @@ pnpm add -D @yss123/cage-cli
 
 首次使用建议通过脚手架创建完整项目，所需依赖由模板统一配置。需要 Node.js 24 或更新版本。
 
+## 从零开始
+
+```powershell
+pnpm exec cage create my-app --template blank
+cd my-app
+pnpm install
+```
+
+在新项目中复制 `.env.example` 为 `.env`，只在本地填写已有 PostgreSQL 数据库的 `CAGE_ADMIN_DATABASE_URL`。然后执行：
+
+```powershell
+pnpm exec cage init
+pnpm build:app
+pnpm gen
+```
+
+审查 `db/migrations` 的变更后，再执行：
+
+```powershell
+pnpm migrate
+pnpm exec cage bootstrap --credentials-file .cage/admin-credentials.json
+pnpm dev
+```
+
+`init` 准备账号、schema 权限和本地连接配置，不创建数据库、不安装 PostgreSQL 或启动 Docker。`gen` 只生成文件，`migrate` 才变更数据库；bootstrap 显式交付初始凭据，不把它们输出到日志或提交源码。
+
+## 日常开发命令
+
+以下命令在应用根目录运行；`cage.config.json` 定位 domain、contracts、迁移和模块结构。
+
+| 命令 | 解决的问题 |
+| --- | --- |
+| `pnpm exec cage check` | 声明、目录、依赖与本体图规则检查 |
+| `pnpm exec cage gen` | 生成前端 contracts、SQL、状态图和迁移草稿，不手改生成物 |
+| `pnpm exec cage capabilities "文件" --format json` | 查当前已安装框架的公开 API 与签名 |
+| `pnpm exec cage context "需求关键词"` | 查本应用相关节点、源码和候选证据 |
+| `pnpm exec cage graph` | 打开可交互业务图谱 |
+| `pnpm exec cage doctor` | 区分注册、生成、迁移、授权和实际进程状态；unknown 不是通过 |
+| `pnpm exec cage verify` | 汇总项目门禁与测试；数据库测试需要独立测试配置 |
+| `pnpm exec cage sync` | 更新 AGENTS 框架托管区，保留标记外业务约定 |
+| `pnpm exec cage upgrade` | 框架升级辅助与检查，使用前阅读当前版本升级说明 |
+
+此外提供 `analyze/impact/test/budget` 等维护入口。可用 `pnpm exec cage --help` 查询参数；包根导出分析、生成、诊断等可组合函数，普通项目优先使用命令行，避免依赖内部文件路径。
+
+`pnpm exec cage create my-app` 交互选择空白业务项目或采购示例项目；也可显式指定 `--template blank` 或 `--template purchase`。省略目录时可交互输入，非交互终端必须同时提供目录与模板。`--framework-path F:/cage` 可链接已构建的本地框架。
+
+自 `0.2.0` 起，两种产物都包含根目录 `AGENTS.md`、`docs/ai` 业务开发教材和 `docs/errors` 离线错误码册。空白项目只运行组织模型，采购参考代码在 `docs/examples/purchase-admin`；采购项目运行完整演示链路。让 Codex 等编程工具先读 `AGENTS.md`，无需另行克隆框架源码。
+
+`cage sync` 更新 AGENTS 框架托管区，保留标记外的项目业务约定；它不自动覆盖业务代码或学习资料。
+
+## 用本体图开发业务
+
+`pnpm exec cage graph` 默认打开业务地图：业务板块 → 流程入口 → 流程图 → 实现代码。板块按模块目录收纳对象，未分模块的项目按对象展示；可通过 `graph.labels` 的 `module:模块目录名` 设置板块中文标题。流程图使用业务节点、审批菱形及方向箭头，保留同事务、异步、条件映射和审批分支。普通滚轮缩放，拖动空白处平移，拖动节点时连线跟随；提供抓手、缩放比例、适应、重排和展开画布，支持横向/纵向布局。点击节点查看同一次抽取的声明代码，保留当前视野与手动布局。地址支持分享、刷新与前进后退；“对象与字段”“完整本体”和复制 AI 上下文仍可使用。
+
+在应用根目录执行：
+
+```powershell
+pnpm exec cage context "修改采购单取消逻辑"
+pnpm exec cage graph search "取消" --kind command
+pnpm exec cage graph inspect command:PurchaseOrder.cancel
+pnpm exec cage graph path command:PurchaseOrder.cancel command:InventoryLock.release
+pnpm exec cage context command:PurchaseOrder.cancel --format json --out .cage/context.json
+```
+
+CLI 每次重新抽取，不需要数据库；报告包含中文候选与依据、业务关系解释、源码位置、契约/前端/测试候选、迁移和授权提示。默认 Markdown；查询支持 `--format json`、`--out`，context 可用 `--depth` / `--limit` 控制范围。图规则错误仍输出可用上下文并返回非零；无命中、精确节点歧义或深度内无路径也非零。Web 节点详情可复制同源 AI 上下文，修改代码后先重新抽取。
+
+名称、SQL 字段和测试匹配是线索；具体执行条件需阅读源码。上述命令自 `0.2.0` 提供，完整流程随新项目分发在 `docs/ai/ontology-context.md`。
+
 - [完整使用说明](https://github.com/shunshunyue/cage/blob/main/docs/使用说明.md)
 - [框架源码与范例](https://github.com/shunshunyue/cage)
 - [问题反馈](https://github.com/shunshunyue/cage/issues)

package/bin/cage.js

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+/**
+ * npm cage 可执行包装器，保留 shebang 并调用已构建 main。
+ * Promise 完成后设置退出码；异常只打印 message，具体受控诊断由命令模块负责。
+ * 不强制 process.exit，让开发服务等句柄按自己的生命周期退出；运行前必须已有 dist。
+ */
 import { main } from '../dist/main.js';
 main().then((code) => { process.exitCode = code; }).catch((error) => {
   console.error(error.message);

package/bin/create-cage-app.js

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+/**
+ * create-cage-app 的薄包装器，为同一 CLI main 前置 create 子命令。
+ * 透传用户参数并设置返回退出码，异常打印 message 后标记失败。
+ * 不复制第二套脚手架实现，模板选择、写盘和取消行为由 main/create 模块统一负责。
+ */
 import { main } from '../dist/main.js';
 main(['create', ...process.argv.slice(2)]).then((code) => { process.exitCode = code; }).catch((error) => {
   console.error(error.message);

package/dist/analyze.d.ts

@@ -2,17 +2,33 @@ import { type CageConfig } from './config.js';
 import { type Finding } from './findings.js';
 import { type Ontology } from './ontology.js';
 /** 静态检查先于模块求值；发现动态声明或 IO 时不执行模块。 */
+/**
+ * 执行当前应用的声明检查与语义抽取，不运行具体业务命令。
+ * 静态错误时返回已有 source/findings；可求值时继续附注册表、本体及可选导出链。
+ * @param cfg 应用目录和 domain 入口配置。
+ * @param opts base 用于事件兼容检查，write 才保存当前图，registration 强制收集完整导出证据。
+ * @returns 分阶段分析结果；模块导入、注册或文件 IO 异常直接抛出。
+ */
 export declare function analyze(cfg: CageConfig, opts?: {
     base?: Ontology;
     write?: boolean;
+    registration?: boolean;
 }): Promise<{
     source: import("./static-check.js").StaticResult;
     findings: Finding[];
     registry?: undefined;
     graph?: undefined;
+    registration?: undefined;
 } | {
     source: import("./static-check.js").StaticResult;
     registry: import("@yss123/cage-kernel").Registry;
     graph: Ontology;
     findings: Finding[];
+    registration: {
+        name: string;
+        file: string;
+        line: number;
+        exportedAs: string[];
+        chain: string[];
+    }[] | undefined;
 }>;

package/dist/analyze.js

@@ -1,3 +1,8 @@
+/**
+ * 声明分析总入口，供 check、gen、verify、doctor 与本体快照共同调用。
+ * 先检查目录、顶层声明及禁止的 IO，再导入领域入口构建注册表、抽取本体并运行图规则。
+ * 这里只求值声明，不执行命令；write 选项才会更新当前本体文件，静态错误会阻止模块求值。
+ */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { abs } from './config.js';
 import { errorsOnly } from './findings.js';
@@ -5,22 +10,35 @@ import { loadRegistry } from './load.js';
 import { extract } from './ontology.js';
 import { runRules } from './rules.js';
 import { staticCheck, unexportedFindings } from './static-check.js';
+import { checkProjectStructure } from './project-structure.js';
+import { registrationEvidence } from './registration.js';
 /** 静态检查先于模块求值；发现动态声明或 IO 时不执行模块。 */
+/**
+ * 执行当前应用的声明检查与语义抽取，不运行具体业务命令。
+ * 静态错误时返回已有 source/findings；可求值时继续附注册表、本体及可选导出链。
+ * @param cfg 应用目录和 domain 入口配置。
+ * @param opts base 用于事件兼容检查，write 才保存当前图，registration 强制收集完整导出证据。
+ * @returns 分阶段分析结果；模块导入、注册或文件 IO 异常直接抛出。
+ */
 export async function analyze(cfg, opts = {}) {
     const source = staticCheck(cfg);
+    source.findings.push(...checkProjectStructure(cfg));
     if (errorsOnly(source.findings).length)
         return { source, findings: source.findings };
     const { mod, registry } = await loadRegistry(abs(cfg, cfg.domain));
+    const exportedNames = new Set(Object.keys(mod));
+    // Common explicit exports need no second TS program. Resolve aliases only for apparent gaps or a full doctor report.
+    const registration = opts.registration || source.sites.some(site => !exportedNames.has(site.exportName)) ? registrationEvidence(cfg, source.sites) : undefined;
     const graph = extract(registry, source.sites, source.unsafeCount);
     const findings = [
         ...source.findings,
-        ...unexportedFindings(source.sites, new Set(Object.keys(mod))),
+        ...unexportedFindings(source.sites, registration ? new Set(registration.filter(entry => entry.exportedAs.length).map(entry => entry.name)) : exportedNames),
         ...runRules(graph, opts.base),
     ];
     if (opts.write) {
         mkdirSync(abs(cfg, '.cage'), { recursive: true });
         writeFileSync(abs(cfg, '.cage/ontology.json'), JSON.stringify(graph, null, 2) + '\n');
     }
-    return { source, registry, graph, findings };
+    return { source, registry, graph, findings, registration };
 }
 //# sourceMappingURL=analyze.js.map

package/dist/analyze.js.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,OAAO,EAAiB,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEpE,oCAAoC;AACpC,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,OAA6C,EAAE;IAC5F,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IACrF,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAc;QAC1B,GAAG,MAAM,CAAC,QAAQ;QAClB,GAAG,kBAAkB,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9D,GAAG,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;KAC9B,CAAC;IACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,qBAAqB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,UAAU,EAAgB,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,OAAO,EAAiB,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,oCAAoC;AACpC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,OAAqE,EAAE;IACpH,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,IAAI,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM;QAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IACrF,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,qHAAqH;IACrH,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC/J,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAClE,MAAM,QAAQ,GAAc;QAC1B,GAAG,MAAM,CAAC,QAAQ;QAClB,GAAG,kBAAkB,CAAC,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;QAC3J,GAAG,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;KAC9B,CAAC;IACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,qBAAqB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;AAC7D,CAAC"}

package/dist/baseline.d.ts

@@ -1,4 +1,12 @@
 import { type CageConfig } from './config.js';
+/**
+ * 选择显式文件或真实 Git 提交作为修改前的比较依据，baseFile 优先。
+ * Git 路径使用当前依赖解释旧声明，不能证明旧项目在原依赖版本下的行为。
+ * @param cfg 当前应用位置。
+ * @param opts base 为 Git ref，baseFile 为本体或命名快照路径；都省略则不启用基线。
+ * @returns 读取或重新抽取的本体，未指定基线时为 undefined。
+ * @throws ref 无效、抽取失败、读写或 worktree 清理失败时抛出。
+ */
 export declare function loadBaseline(cfg: CageConfig, opts: {
     base?: string;
     baseFile?: string;

package/dist/baseline.js

@@ -1,3 +1,8 @@
+/**
+ * 为影响分析加载显式 JSON 基线或 Git 提交中的领域声明。
+ * 文件基线直接读取；Git 基线在独立临时 worktree 中共享当前已安装依赖并由子进程抽取。
+ * 不切换当前分支、不安装基线依赖；结束时解除本次 junction 并清理临时工作树，错误向调用方传播。
+ */
 // 基线来自显式 JSON 文件，或 Git 提交里的业务声明。
 // Git 比较在独立临时工作树中抽取，不切换用户当前分支，也不安装/执行基线脚本。
 import { execFileSync } from 'node:child_process';
@@ -8,6 +13,14 @@ import { abs } from './config.js';
 import { readOntology } from './impact.js';
 import { run } from './process.js';
 import { projectManifests } from './upgrade.js';
+/**
+ * 选择显式文件或真实 Git 提交作为修改前的比较依据，baseFile 优先。
+ * Git 路径使用当前依赖解释旧声明，不能证明旧项目在原依赖版本下的行为。
+ * @param cfg 当前应用位置。
+ * @param opts base 为 Git ref，baseFile 为本体或命名快照路径；都省略则不启用基线。
+ * @returns 读取或重新抽取的本体，未指定基线时为 undefined。
+ * @throws ref 无效、抽取失败、读写或 worktree 清理失败时抛出。
+ */
 export async function loadBaseline(cfg, opts) {
     if (opts.baseFile)
         return readOntology(abs(cfg, opts.baseFile));

package/dist/baseline.js.map

@@ -1 +1 @@
-{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,2CAA2C;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC9F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAe,EAAE,IAA0C;IAC5F,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,IAAI,CAAC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,GAAG,GAAG,CAAC,IAAc,EAAE,EAAE,CAC7B,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3F,MAAM,UAAU,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACzD,wCAAwC;IACxC,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC;IACvE,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC7C,GAAG,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/D,iCAAiC;QACjC,kDAAkD;QAClD,KAAK,MAAM,QAAQ,IAAI,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACrG,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;YACnE,IAAI,UAAU,CAAC,WAAW,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;gBAC5H,WAAW,CACT,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,EAC9B,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EACjC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAClD,CAAC;gBACF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,GAAG,CACpB,aAAa,CAAC,IAAI,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EACzD,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,EAC9B,OAAO,CACR,CAAC;QACF,IAAI,IAAI,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACtF,OAAO,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAC5D,CAAC;YAAS,CAAC;QACT,sCAAsC;QACtC,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,UAAU,CAAC,IAAI,CAAC,CAAC;QAC3C,GAAG,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;QACjD,4CAA4C;QAC5C,MAAM,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,iCAAiC;AACjC,2CAA2C;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC9F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAe,EAAE,IAA0C;IAC5F,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAChE,IAAI,CAAC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,GAAG,GAAG,CAAC,IAAc,EAAE,EAAE,CAC7B,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3F,MAAM,UAAU,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACzD,wCAAwC;IACxC,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC;IACvE,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IAC7C,GAAG,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/D,iCAAiC;QACjC,kDAAkD;QAClD,KAAK,MAAM,QAAQ,IAAI,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACrG,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;YACnE,IAAI,UAAU,CAAC,WAAW,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;gBAC5H,WAAW,CACT,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,EAC9B,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EACjC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAClD,CAAC;gBACF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,GAAG,CACpB,aAAa,CAAC,IAAI,GAAG,CAAC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EACzD,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,EAC9B,OAAO,CACR,CAAC;QACF,IAAI,IAAI,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACtF,OAAO,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAC5D,CAAC;YAAS,CAAC;QACT,sCAAsC;QACtC,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,UAAU,CAAC,IAAI,CAAC,CAAC;QAC3C,GAAG,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;QACjD,4CAA4C;QAC5C,MAAM,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}

package/dist/bootstrap.d.ts

@@ -0,0 +1,20 @@
+import { type CageConfig } from './config.js';
+/**
+ * 独占创建新凭据文件，在任何密码写入前收紧可读写范围。
+ * POSIX 请求 0600；Windows 使用实际进程 SID 替换继承 ACL，不信任环境用户名。
+ * @param file 已解析的目标路径，父目录必须存在，目标不得已存在。
+ * @throws 创建或 ACL 限制失败时抛出 CAGE-INIT-005；已创建空文件可能保留，不能视为交付成功。
+ */
+export declare function protectCredentialFile(file: string): void;
+/**
+ * 显式初始化组织并把首次管理员凭据交给受限文件，供 main 的 bootstrap 分支调用。
+ * 只注册组织模型；已有用户时不重置账号，返回未创建结果。交付回调失败使初始化事务失败。
+ * @param cfg 应用配置，用于解析相对凭据路径。
+ * @param credentialsFile 必须指定的新文件路径。
+ * @returns created 和凭据文件绝对路径；函数完成后 kernel 已关闭。
+ * @throws 凭据准备或初始化失败时返回受控错误，避免 SQL 参数和密码进入日志。
+ */
+export declare function bootstrapOrganization(cfg: CageConfig, credentialsFile: string): Promise<{
+    created: boolean;
+    credentialsFile: string;
+}>;

package/dist/bootstrap.js

@@ -0,0 +1,75 @@
+/**
+ * CLI 的组织初始化与管理员凭据交付边界，由 bootstrap 子命令调用。
+ * 先独占创建并限制凭据文件权限，再仅注册组织领域执行 bootstrapOrg，凭据交付参与初始化事务。
+ * 不隐式授予业务能力、不打印密码；无论初始化成功与否均关闭临时 kernel，文件交付失败不能被当成成功。
+ */
+// Explicit organization initialization. Credentials are delivered only through a newly protected file.
+import { randomBytes } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { closeSync, openSync, writeFileSync } from 'node:fs';
+import { bootstrapOrg } from '@yss123/cage-admin';
+import * as organization from '@yss123/cage-admin/domain';
+import { createKernel, silentLogger, urlsFromEnv } from '@yss123/cage-kernel';
+import { abs } from './config.js';
+/**
+ * 独占创建新凭据文件，在任何密码写入前收紧可读写范围。
+ * POSIX 请求 0600；Windows 使用实际进程 SID 替换继承 ACL，不信任环境用户名。
+ * @param file 已解析的目标路径，父目录必须存在，目标不得已存在。
+ * @throws 创建或 ACL 限制失败时抛出 CAGE-INIT-005；已创建空文件可能保留，不能视为交付成功。
+ */
+export function protectCredentialFile(file) {
+    try {
+        closeSync(openSync(file, 'wx', 0o600));
+    }
+    catch {
+        throw new Error('[CAGE-INIT-005] 无法创建新的受限凭据文件；请使用不存在的文件，并检查父目录及其权限');
+    }
+    if (process.platform === 'win32') {
+        try {
+            // Shell/sandbox accounts may differ from USERNAME. Grant the actual process identity by SID.
+            const identity = execFileSync('whoami', ['/user', '/fo', 'csv', '/nh'], { encoding: 'utf8', windowsHide: true, stdio: 'pipe' });
+            const sid = identity.match(/\bS-\d+(?:-\d+)+\b/)?.[0];
+            if (!sid)
+                throw new Error('Current Windows SID unavailable');
+            execFileSync('icacls', [file, '/inheritance:r', '/grant:r', `*${sid}:(F)`], { windowsHide: true, stdio: 'pipe' });
+        }
+        catch {
+            throw new Error('[CAGE-INIT-005] 无法限制凭证文件权限；未生成或写入凭证，请修正文件 ACL 后重试');
+        }
+    }
+}
+/**
+ * 显式初始化组织并把首次管理员凭据交给受限文件，供 main 的 bootstrap 分支调用。
+ * 只注册组织模型；已有用户时不重置账号，返回未创建结果。交付回调失败使初始化事务失败。
+ * @param cfg 应用配置，用于解析相对凭据路径。
+ * @param credentialsFile 必须指定的新文件路径。
+ * @returns created 和凭据文件绝对路径；函数完成后 kernel 已关闭。
+ * @throws 凭据准备或初始化失败时返回受控错误，避免 SQL 参数和密码进入日志。
+ */
+export async function bootstrapOrganization(cfg, credentialsFile) {
+    if (!credentialsFile)
+        throw new Error('[CAGE-INIT-005] 指定 --credentials-file <新的受限文件>，初始化密码不会写入控制台');
+    const file = abs(cfg, credentialsFile);
+    protectCredentialFile(file);
+    // Only organization declarations are registered, so no business capabilities are granted implicitly.
+    const kernel = createKernel({ domain: organization, urls: urlsFromEnv(process.env), logger: silentLogger });
+    try {
+        const password = randomBytes(24).toString('base64url');
+        const result = await bootstrapOrg(kernel, {
+            adminPassword: password,
+            // Delivery is part of the initialization transaction: a failed write must not strand an administrator.
+            deliverCredentials: credentials => writeFileSync(file, JSON.stringify({ ...credentials, note: '仅初始化组织与系统管理能力。业务能力由管理员显式配置；妥善保管并在交付后移除此文件。' }, null, 2) + '\n'),
+        });
+        if (!result.created)
+            writeFileSync(file, JSON.stringify({ created: false, note: '组织已有用户，未修改账号或密码。' }, null, 2) + '\n');
+        return { created: result.created, credentialsFile: file };
+    }
+    catch {
+        // Do not surface SQL arguments or initialization inputs through a generic error formatter.
+        throw new Error('[CAGE-INIT-005] 组织初始化失败；检查迁移与数据库账号，凭证未输出到日志。');
+    }
+    finally {
+        await kernel.close();
+    }
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/budget.d.ts

@@ -1,6 +1,13 @@
 import { type CageConfig } from './config.js';
 import type { Ontology } from './ontology.js';
 import type { Finding } from './findings.js';
+/**
+ * 计算静态预算并给出超限诊断，不自动豁免或改写基线。
+ * @param cfg 用于查找本地 kernel 源码；普通安装项目可能没有这些文件。
+ * @param graph 当前本体，其中 unsafeCount 表示扫描到的逃生口数量。
+ * @param base 已审查本体，省略时 unsafe 允许量为零。
+ * @returns 体积/词汇/unsafe 指标和超限 Finding；缺源码的指标为 null。
+ */
 export declare function budget(cfg: CageConfig, graph: Ontology, base?: Ontology): {
     metrics: Record<string, number | null>;
     findings: Finding[];

package/dist/budget.js

@@ -1,13 +1,57 @@
+/**
+ * 面向框架维护和业务门禁计算内核规模、公共词汇与 unsafe 增量预算。
+ * 读取本地源码及本体元数据，返回 metrics 和 Finding，不修改源码、不连接数据库。
+ * 源码包不存在时对应体积指标为 null；体积按含语法 token 的物理行计数，排除注释和空白。
+ */
 import { existsSync, readFileSync } from 'node:fs';
+import ts from 'typescript';
 import { abs } from './config.js';
 import { listTs } from './static-check.js';
+/**
+ * 统计一份 TypeScript 源码实际占用的代码行，让中文 JSDoc 不消耗内核实现预算。
+ * 使用语法树的叶子 token 定位原始物理行，不重新格式化源码，也不把字符串、正则或模板内的注释符当注释。
+ * JSDoc 子树和 EOF 不代表实现；跨行 token 覆盖的全部行仍计入，因此模板文字中的空行属于代码内容。
+ * 同一行有多个 token 只计一次，行尾注释不增加行数；本函数不做类型检查或修改文件。
+ * @param file 文件名，交给 TypeScript 判断源码类型。
+ * @param sourceText 完整源码，保留原有换行。
+ * @returns 含至少一个语法 token 的物理行数。
+ */
+function codeLineCount(file, sourceText) {
+    const source = ts.createSourceFile(file, sourceText, ts.ScriptTarget.Latest, true);
+    const lines = new Set();
+    /** 遍历语法 token；必须跳过 JSDoc 整棵子树，避免其中的标识符和类型被当作实现。 */
+    const visit = (node) => {
+        if (node.kind >= ts.SyntaxKind.FirstJSDocNode && node.kind <= ts.SyntaxKind.LastJSDocNode)
+            return;
+        const children = node.getChildren(source);
+        if (children.length) {
+            children.forEach(visit);
+            return;
+        }
+        if (node.kind === ts.SyntaxKind.EndOfFileToken || node.kind === ts.SyntaxKind.SyntaxList)
+            return;
+        const start = node.getStart(source), end = node.getEnd();
+        if (end <= start)
+            return;
+        const first = source.getLineAndCharacterOfPosition(start).line;
+        const last = source.getLineAndCharacterOfPosition(end - 1).line;
+        for (let line = first; line <= last; line++)
+            lines.add(line);
+    };
+    visit(source);
+    return lines.size;
+}
+/**
+ * 计算静态预算并给出超限诊断，不自动豁免或改写基线。
+ * @param cfg 用于查找本地 kernel 源码；普通安装项目可能没有这些文件。
+ * @param graph 当前本体，其中 unsafeCount 表示扫描到的逃生口数量。
+ * @param base 已审查本体，省略时 unsafe 允许量为零。
+ * @returns 体积/词汇/unsafe 指标和超限 Finding；缺源码的指标为 null。
+ */
 export function budget(cfg, graph, base) {
     const kernel = abs(cfg, 'packages/kernel/src');
     const lines = existsSync(kernel)
-        ? listTs(kernel).reduce((n, f) => n +
-            readFileSync(f, 'utf8')
-                .split('\n')
-                .filter((l) => l.trim() && !l.trim().startsWith('//')).length, 0)
+        ? listTs(kernel).reduce((n, f) => n + codeLineCount(f, readFileSync(f, 'utf8')), 0)
         : null;
     const primitivesFile = abs(cfg, 'packages/kernel/src/brands.ts');
     // 使用公共词汇表计数；品牌还含内部扩展标记，不能把两者混算。
@@ -21,7 +65,7 @@ export function budget(cfg, graph, base) {
     const vocabulary = new Set(['field', 'capability', 'scope', 'constraint', 'invariant']);
     if (existsSync(primitivesFile)) {
         for (const match of readFileSync(primitivesFile, 'utf8').matchAll(/export const (\w+) = Symbol\.for\(/g)) {
-            if (['CONSUMERS', 'SYSTEM_DDL'].includes(match[1]))
+            if (['CONSUMERS', 'SYSTEM_DDL', 'RUNTIME', 'MIGRATIONS'].includes(match[1]))
                 continue;
             vocabulary.add(families[match[1]] ?? match[1].toLowerCase());
         }

package/dist/budget.js.map

@@ -1 +1 @@
-{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"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"}

package/dist/capabilities.d.ts

@@ -0,0 +1,38 @@
+import { type CageConfig } from './config.js';
+/**
+ * 读取安装版本的公开导出签名，按关键词筛选可用 API 的证据。
+ * 查询只做归一化后的连续文本包含判断，不进行同义词推理；无结果和未检查包都不能说明能力不存在。
+ * @param cfg 用于定位应用不同包的依赖解析边界。
+ * @param query 公开名称、JSDoc 或维护的业务词条；空字符串返回全部已发现符号。
+ * @returns 包检查状态、真实签名、声明位置和本地 guide；不加载运行时实现或修改文件。
+ */
+export declare function publicCapabilities(cfg: CageConfig, query?: string): {
+    schemaVersion: number;
+    cliVersion: string;
+    query: string;
+    packages: {
+        inspected: boolean;
+        name: string;
+        version: string | null;
+    }[];
+    capabilities: {
+        key: string;
+        package: string;
+        version: string | null;
+        name: string;
+        public: boolean;
+        description: string;
+        signatures: string[];
+        guide: string;
+        example: {
+            code: string;
+            context: string;
+        } | undefined;
+        limitations: string[];
+        source: {
+            file: string;
+            line: number;
+        };
+    }[];
+    limitations: string[];
+};