@yss123/cage-cli 0.2.0 → 0.3.1

package/README.md

@@ -1,8 +1,6 @@
 # @yss123/cage-cli
 
-cage 命令行：init、gen、check、graph、context、impact、test、verify、budget、sync、upgrade、dev、migrate
-
-Cage 是通过 TypeScript 声明业务、由框架统一执行权限和数据规则的中后台框架。此包是框架的一部分。
+Cage 的开发命令行：创建项目，抽取领域声明，生成契约与迁移草稿，检查图规则与目录边界，浏览业务图谱，查询能力和运行诊断，并管理开发进程及显式迁移。CLI 是开发与部署工具，不能代替业务命令或自动授予生产权限。
 
 ## 使用
 
@@ -12,6 +10,50 @@ 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`，无需另行克隆框架源码。
@@ -20,6 +62,8 @@ pnpm add -D @yss123/cage-cli
 
 ## 用本体图开发业务
 
+`pnpm exec cage graph` 默认打开业务地图：业务板块 → 流程入口 → 流程图 → 实现代码。板块按模块目录收纳对象，未分模块的项目按对象展示；可通过 `graph.labels` 的 `module:模块目录名` 设置板块中文标题。流程图使用业务节点、审批菱形及方向箭头，保留同事务、异步、条件映射和审批分支。普通滚轮缩放，拖动空白处平移，拖动节点时连线跟随；提供抓手、缩放比例、适应、重排和展开画布，支持横向/纵向布局。点击节点查看同一次抽取的声明代码，保留当前视野与手动布局。地址支持分享、刷新与前进后退；“对象与字段”“完整本体”和复制 AI 上下文仍可使用。
+
 在应用根目录执行：
 
 ```powershell

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';
@@ -6,23 +11,34 @@ 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;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,oCAAoC;AACpC,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAe,EAAE,OAA6C,EAAE;IAC5F,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,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/approval-tree.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 审批声明 JSON 的只读结构与遍历工具，供本体抽取、字段关系说明和静态流程图共同消费。
+ * 仅遍历 when、parallel 和 branch 保留的声明树，不执行条件、选人、审批引擎或实际实例状态。
+ * 浏览器可引用这些类型和纯函数，不引入 approval 运行时；标题和依赖始终来自抽取快照。
+ */
+/** 人工步骤的静态可解释元数据；未知扩展由抽取原始 JSON 保留，本投影不据此执行业务。 */
+export interface ApprovalRouteStep {
+    /** 人工步骤判别，不同于 parallel 的分支容器。 */
+    kind: 'step';
+    /** 提交政策中的标题和同节点原始审批票完成规则。 */
+    title: string;
+    mode: 'any' | 'all';
+    /** candidate 表示共享领取；不代表分支并行或多人会签。 */
+    assignment?: 'direct' | 'candidate';
+    /** 任务管理开关与自然分钟总时限，只作说明，不表示已经发生。 */
+    actions?: {
+        transfer?: boolean;
+        delegate?: boolean;
+        addSign?: boolean;
+    };
+    sla?: {
+        durationMinutes: number;
+        remindBeforeMinutes?: number;
+    };
+    /** 封闭选人策略；被选中不代表拥有业务命令能力。 */
+    approver: {
+        kind: 'deptLeader';
+        field: string;
+    } | {
+        kind: 'field';
+        field: string;
+    } | {
+        kind: 'role';
+        code: string;
+    } | {
+        kind: 'user';
+        userId: string;
+    };
+}
+/** AI 步骤只暴露绘图及取证依赖所需字段；提示词不由本遍历器加入公开图。 */
+export interface ApprovalAiRouteStep {
+    /** AI 节点判别；其人工接管仍归属于同一声明节点。 */
+    kind: 'ai';
+    /** 展示标题，不能作为实例节点的唯一身份或执行顺序。 */
+    title: string;
+    /** 转人工时的封闭选人策略，图谱只说明来源，不授予处理权限。 */
+    handoff: ApprovalRouteStep['approver'];
+    /** CLI 本体依据这些白名单画 uses/queries 关系，不实际读取数据。 */
+    context?: {
+        fields: readonly string[];
+        queries?: readonly string[];
+    };
+}
+/** 条件比较保留精确运算符与边界，不按展示顺序推断运行时是否满足。 */
+export interface ApprovalRouteCondition {
+    /** 提交快照中的条件字段，由注册表校验是否进入 routable。 */
+    field: string;
+    /** 已声明的封闭比较方式；静态图不调用条件求值。 */
+    op: 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'ne' | 'in';
+    /** 固定阈值或集合，沿用原声明的类型和数值，不根据中文标签重新推断。 */
+    value: string | number | boolean | (string | number)[];
+}
+/** AND 分支内部为顺序声明，可继续含有条件和嵌套并行。 */
+export interface ApprovalRouteBranch {
+    /** 分支容器判别；不能单独当作可分配任务。 */
+    kind: 'branch';
+    /** 所属并行组内唯一的名称，用于静态说明和分支定位。 */
+    title: string;
+    /** 分支内部的顺序子树；嵌套容器保留，不摊平成全流程顺序。 */
+    nodes: ApprovalRouteNode[];
+}
+/** 结构化路由树；parallel 必须等待全部活动分支，when 在实例启动时按快照求值。 */
+export type ApprovalRouteNode = ApprovalRouteStep | ApprovalAiRouteStep | {
+    kind: 'when';
+    cond: ApprovalRouteCondition;
+    steps: ApprovalRouteNode[];
+} | {
+    kind: 'parallel';
+    title: string;
+    branches: ApprovalRouteBranch[];
+};
+/**
+ * 按声明的深度优先次序遍历全部节点，保留容器供条件解释使用，分支本身不是可执行步骤。
+ * 本函数不排序或改写源树；声明深度/数量由注册器限制，序号只能作为静态定位，不能当执行先后。
+ */
+export declare function approvalRouteNodes(nodes: readonly ApprovalRouteNode[]): ApprovalRouteNode[];
+/** 收集全部人工/AI 叶节点，用于取证与选人依赖；并行结构仍需由调用方从原树单独保留。 */
+export declare function approvalRouteSteps(nodes: readonly ApprovalRouteNode[]): (ApprovalRouteStep | ApprovalAiRouteStep)[];

package/dist/approval-tree.js

@@ -0,0 +1,18 @@
+/**
+ * 审批声明 JSON 的只读结构与遍历工具，供本体抽取、字段关系说明和静态流程图共同消费。
+ * 仅遍历 when、parallel 和 branch 保留的声明树，不执行条件、选人、审批引擎或实际实例状态。
+ * 浏览器可引用这些类型和纯函数，不引入 approval 运行时；标题和依赖始终来自抽取快照。
+ */
+/**
+ * 按声明的深度优先次序遍历全部节点，保留容器供条件解释使用，分支本身不是可执行步骤。
+ * 本函数不排序或改写源树；声明深度/数量由注册器限制，序号只能作为静态定位，不能当执行先后。
+ */
+export function approvalRouteNodes(nodes) {
+    return nodes.flatMap(node => [node, ...(node.kind === 'when' ? approvalRouteNodes(node.steps) :
+            node.kind === 'parallel' ? node.branches.flatMap(branch => approvalRouteNodes(branch.nodes)) : [])]);
+}
+/** 收集全部人工/AI 叶节点，用于取证与选人依赖；并行结构仍需由调用方从原树单独保留。 */
+export function approvalRouteSteps(nodes) {
+    return approvalRouteNodes(nodes).filter((node) => node.kind === 'step' || node.kind === 'ai');
+}
+//# sourceMappingURL=approval-tree.js.map

package/dist/approval-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-tree.js","sourceRoot":"","sources":["../src/approval-tree.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwDH;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAmC;IACpE,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YAC7F,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACzG,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,kBAAkB,CAAC,KAAmC;IACpE,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAmD,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACjJ,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":"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"}
+{"version":3,"file":"baseline.js","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"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"}

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[];
+};