@yss123/cage-cli 0.0.0-stage → 0.2.0

package/dist/static-check.js

@@ -0,0 +1,222 @@
+// 静态检查：导入之前先用 TypeScript 编译器 API 扫一遍源码，确保没有声明藏在函数、条件或循环里（那样抽取器就看不到它），
+// 并记下每个声明的位置（影响分析把 handler 文件的改动映射到它所属的命令）。
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import ts from 'typescript';
+export const PRIMITIVES = new Set([
+    'aggregate',
+    'states',
+    'command',
+    'event',
+    'reaction',
+    'query',
+    'approval',
+    'job',
+    'connector',
+    'outbound',
+    'inbound',
+    'route',
+]);
+const IO_MODULES = /^(node:)?(fs|fs\/promises|net|http|https|http2|child_process|dgram|tls|worker_threads|cluster)(\/|$)|^(pg|kysely|axios|undici|node-fetch|got|@yss123\/cage-http|@yss123\/cage-kernel\/db|@yss123\/cage-kernel\/worker)(\/|$)/;
+export function listTs(dir) {
+    const out = [];
+    const walk = (d) => {
+        for (const name of readdirSync(d)) {
+            if (name === 'node_modules' || name === 'dist' || name.startsWith('.'))
+                continue;
+            const p = join(d, name);
+            if (statSync(p).isDirectory())
+                walk(p);
+            else if (/\.(ts|tsx)$/.test(name) && !/\.(test|spec)\.tsx?$/.test(name) && !name.endsWith('.d.ts'))
+                out.push(p);
+        }
+    };
+    walk(dir);
+    return out.sort();
+}
+function isFunctionLike(n) {
+    return (ts.isFunctionDeclaration(n) ||
+        ts.isFunctionExpression(n) ||
+        ts.isArrowFunction(n) ||
+        ts.isMethodDeclaration(n) ||
+        ts.isConstructorDeclaration(n) ||
+        ts.isGetAccessor(n) ||
+        ts.isSetAccessor(n) ||
+        ts.isClassDeclaration(n));
+}
+function isControl(n) {
+    return (ts.isIfStatement(n) ||
+        ts.isForStatement(n) ||
+        ts.isForOfStatement(n) ||
+        ts.isForInStatement(n) ||
+        ts.isWhileStatement(n) ||
+        ts.isDoStatement(n) ||
+        ts.isSwitchStatement(n) ||
+        ts.isTryStatement(n) ||
+        ts.isConditionalExpression(n) ||
+        ts.isBlock(n));
+}
+function calleeName(call) {
+    return ts.isIdentifier(call.expression) ? call.expression.text : null;
+}
+export function staticCheck(cfg) {
+    const domainDir = dirname(join(cfg.root, cfg.domain));
+    const files = listTs(domainDir);
+    const sites = [];
+    const findings = [];
+    let unsafeCount = 0;
+    for (const file of files) {
+        const text = readFileSync(file, 'utf8');
+        const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+        const rel = relative(cfg.root, file).replace(/\\/g, '/');
+        const loc = (n) => `${rel}:${sf.getLineAndCharacterOfPosition(n.getStart()).line + 1}`;
+        // 别名和命名空间导入同样属于框架声明，不能因为换了写法就跳过检查。
+        const aliases = new Map();
+        const namespaces = new Set();
+        for (const statement of sf.statements) {
+            if (!ts.isImportDeclaration(statement) ||
+                !ts.isStringLiteral(statement.moduleSpecifier) ||
+                !statement.moduleSpecifier.text.startsWith('@yss123/cage-'))
+                continue;
+            const bindings = statement.importClause?.namedBindings;
+            if (bindings && ts.isNamedImports(bindings))
+                for (const item of bindings.elements)
+                    aliases.set(item.name.text, item.propertyName?.text ?? item.name.text);
+            if (bindings && ts.isNamespaceImport(bindings))
+                namespaces.add(bindings.name.text);
+        }
+        const primitiveName = (call) => {
+            const expression = call.expression;
+            if (ts.isIdentifier(expression))
+                return aliases.get(expression.text) ?? expression.text;
+            if (ts.isPropertyAccessExpression(expression) &&
+                ts.isIdentifier(expression.expression) &&
+                namespaces.has(expression.expression.text))
+                return expression.name.text;
+            return null;
+        };
+        const visit = (node) => {
+            // 依赖规则：声明和 handler 不能做 IO
+            if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+                const spec = node.moduleSpecifier.text;
+                if (IO_MODULES.test(spec)) {
+                    findings.push({
+                        code: 'CAGE-DEP-001',
+                        at: loc(node),
+                        reason: `声明文件导入了 IO 模块 ${spec}`,
+                        fix: '需要外部数据就声明 reads；需要通知外部系统就发事件，由连接器的出站映射处理',
+                    });
+                }
+            }
+            if (ts.isCallExpression(node)) {
+                const name = primitiveName(node);
+                if (name === 'fetch' || node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+                    findings.push({
+                        code: 'CAGE-DEP-004',
+                        at: loc(node),
+                        reason: name === 'fetch' ? 'handler 里直接发网络请求' : '声明文件里使用了动态 import',
+                        fix: '第三方调用改为连接器声明 + outbound 出站映射',
+                    });
+                }
+                if (name === 'unsafe')
+                    unsafeCount++;
+                if (name && PRIMITIVES.has(name)) {
+                    let cur = node;
+                    let bad = null;
+                    let topDecl = null;
+                    while (cur.parent) {
+                        const p = cur.parent;
+                        if (isFunctionLike(p) || isControl(p)) {
+                            bad = p;
+                            break;
+                        }
+                        if (ts.isVariableDeclaration(p) &&
+                            p.parent &&
+                            ts.isVariableDeclarationList(p.parent) &&
+                            p.parent.parent &&
+                            ts.isVariableStatement(p.parent.parent) &&
+                            p.parent.parent.parent === sf) {
+                            topDecl = p;
+                            break;
+                        }
+                        if (ts.isExpressionStatement(p) && p.parent === sf)
+                            break;
+                        cur = p;
+                    }
+                    if (bad) {
+                        findings.push({
+                            code: 'CAGE-DECL-001',
+                            at: loc(node),
+                            reason: `原语 ${name}() 写在函数、条件或循环里，抽取器看不到它`,
+                            fix: '原语必须在模块顶层用 export const 声明',
+                        });
+                    }
+                    else if (!topDecl) {
+                        findings.push({
+                            code: 'CAGE-DECL-001',
+                            at: loc(node),
+                            reason: `原语 ${name}() 没有赋值给顶层常量`,
+                            fix: '写成 export const 名字 = ' + name + '(...)',
+                        });
+                    }
+                    else {
+                        const stmt = topDecl.parent.parent;
+                        const exported = stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+                        const isConst = (topDecl.parent.flags & ts.NodeFlags.Const) !== 0;
+                        if (topDecl.initializer === node) {
+                            if (!exported || !isConst) {
+                                findings.push({
+                                    code: 'CAGE-DECL-003',
+                                    at: loc(node),
+                                    reason: `声明 ${topDecl.name.getText()} 没有用 export const 导出`,
+                                    fix: '加上 export const，并确认它从 domain 的 index.ts 导出',
+                                });
+                            }
+                            else if (ts.isIdentifier(topDecl.name)) {
+                                const t = node.getText();
+                                const codes = [...t.matchAll(/fail\(\s*['"`]([A-Z][A-Z0-9_]*)['"`]/g)].map((m) => m[1]);
+                                sites.push({
+                                    exportName: topDecl.name.text,
+                                    primitive: name,
+                                    file: rel,
+                                    line: sf.getLineAndCharacterOfPosition(node.getStart()).line + 1,
+                                    text: t,
+                                    domainCodes: [...new Set(codes)],
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sf);
+    }
+    // 同名导出：export * 遇到重名会悄悄把两个都丢掉
+    const byName = new Map();
+    for (const s of sites)
+        byName.set(s.exportName, [...(byName.get(s.exportName) ?? []), s]);
+    for (const [n, list] of byName) {
+        if (list.length > 1) {
+            findings.push({
+                code: 'CAGE-DECL-004',
+                at: `${list[0].file}:${list[0].line}`,
+                reason: `导出名 ${n} 在 ${list.map((s) => s.file).join('、')} 里重复，export * 会把它们都丢掉`,
+                fix: '改成不重复的导出名；命令可以用 command(X, { name: "原名" }) 保持能力点不变',
+            });
+        }
+    }
+    return { sites, findings, unsafeCount, files: files.map((f) => relative(cfg.root, f).replace(/\\/g, '/')) };
+}
+/** 有声明文件未被导出：静态扫到的声明必须出现在 domain 入口的导出里 */
+export function unexportedFindings(sites, exported) {
+    return sites
+        .filter((s) => !exported.has(s.exportName))
+        .map((s) => ({
+        code: 'CAGE-DECL-002',
+        at: `${s.file}:${s.line}`,
+        reason: `声明 ${s.exportName} 没有从 domain 入口导出，内核和抽取器都看不到它`,
+        fix: `从所属模块 index.ts 导出 ${s.exportName}，再由 domain 的统一入口转导出；源文件 ${s.file}`,
+    }));
+}
+//# sourceMappingURL=static-check.js.map

package/dist/static-check.js.map

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

package/dist/sync.d.ts

@@ -0,0 +1,5 @@
+import { type CageConfig } from './config.js';
+import type { Finding } from './findings.js';
+export declare const managedBlock: string;
+export declare function syncManagedBlock(current: string, latest?: string): string;
+export declare function sync(cfg: CageConfig, check?: boolean): Finding[];

package/dist/sync.js

@@ -0,0 +1,118 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { abs } from './config.js';
+import { VERSION } from './version.js';
+export const managedBlock = `<!-- cage:begin v${VERSION} -->
+## Cage 业务开发约定（框架托管）
+
+### 先读，再按需求改业务
+
+本项目由 create-cage-app 创建。框架来自 \`@yss123/cage-*\` 依赖，业务写在本项目；不需要克隆框架仓库，也不要复制框架内部实现。
+
+先读项目说明指定的学习资料，默认入口为 \`docs/ai/README.md\`。第一次读 \`architecture.md\`、\`project-structure.md\` 和 \`primitives.md\`；具体任务读 \`recipes.md\`，采购全链路读 \`purchase-example.md\`，错误查 \`docs/errors/README.md\` 和 \`docs/ai/troubleshooting.md\`。资料相对该学习目录，项目说明可指定源码仓库中的规范资料位置。
+
+### 业务代码放在哪里
+
+| 位置 | 职责 |
+| --- | --- |
+| \`packages/domain/src/modules/<业务>\` | 同业务聚合、状态、命令、事件、审批、查询、任务；模块 index.ts 公开导出 |
+| \`packages/domain/src/workflows\`、\`integrations\` | 跨模块反应 / 第三方协议与映射；不堆到全局 reactions.ts、queries.ts |
+| \`packages/domain/src/index.ts\` | 统一导出全部业务及组织模型；没导出的声明不会注册 |
+| \`packages/contracts/src/aggregates/<聚合>\`、\`queries\` | 生成协议；根 index.ts 提供 @app/contracts 公共入口，只用 cage gen 更新 |
+| \`apps/api/src\` | API/worker 薄启动入口，普通业务不手写 HTTP 路由 |
+| \`apps/web/src/app\` | 会话、导航、布局、模块组合；main.tsx 只挂载和装配 Provider |
+| \`apps/web/src/modules/<业务>\` | 页面、表单、专用 hooks/API/样式；从模块 index.ts 暴露页面 |
+| \`apps/web/src/shared\` | 跨模块复用且不绑定业务的 UI、hooks、纯辅助函数 |
+| \`db/migrations\` | 审查过的结构迁移，作用于已配置的数据库 |
+| \`cage.config.json\` | 项目路径、检查配置、graph.labels 中文图谱名称 |
+| \`.env\` | 本机真实连接和密钥；不提交、不输出完整内容 |
+
+新增业务不得继续平铺在 src 根目录。前端模块只依赖自己和 shared，由 app 通过公开入口组合；shared 不反向依赖业务。领域模块间确有读取依赖时走目标模块 index.ts；跨模块反应写 workflows。小模块不创建空层级，已有独立职责再拆文件。完整命名、目录树和示例见 \`docs/ai/project-structure.md\`。新模板启用 \`structure: modular\`，check/verify 检查目录和导入边界，遇到 CAGE-STRUCT 错误按职责修正。
+
+### 实现一项需求的顺序
+
+1. 先运行 \`pnpm exec cage context "需求关键词"\`；按需 \`graph search\` 查候选、\`graph inspect\` 查完整节点、\`graph path\` 看关系路径。确认中文匹配入口后按源码位置阅读实现；候选和子图不是全部依赖，具体条件不能凭连线推断。完整用法见 \`docs/ai/ontology-context.md\`。从用户需求确定字段、状态/动作、角色/范围、约束与后续动作；能由业务声明表达的不改框架。
+2. 已有业务含义变化时，修改前保存本体图基线：\`pnpm exec cage analyze\` 后将 \`.cage/ontology.json\` 另存为独立文件；或使用真实 Git 基线。
+3. 先声明 aggregate/states/command/constraints/event，再写 handler、reaction/query/approval/connector，最后接业务页面。声明使用模块顶层 \`export const\`，从 domain 入口导出，跨文件导出名保持唯一。
+4. 运行 \`pnpm exec cage check\` 和 \`pnpm gen\`，审查 contracts 和迁移草稿。按需运行 \`pnpm exec cage impact --base-file 旧图.json\`，补中文图谱名。
+5. 页面使用生成方法并处理 code/domainCode；新增能力由管理员授权。数据库结构变化审查后显式 \`pnpm migrate\`，dev 不代办迁移。
+6. 按改动运行必要验证，交付时说明体验步骤、授权配置、迁移，以及通过/跳过/未执行项。
+
+### 必守边界
+
+- 聚合定义对象字段、状态、范围字段与不变量；命令是业务写入口。handler 只计算业务变化和读取 reads 中的依赖，不直接操作数据库、网络或文件。
+- 对象关系统一放在 fields：ref 为外键，hasMany 为只读反查，manyToMany 自动生成中间表并随所属对象命令提交。前端用生成的 related 方法分页读取；不手写纯中间表聚合，不把单页结果当完整集合替换。完整例子见 docs/ai/relations.md。
+- command 的 input 使用 Zod；已有记录输入必须含 id。from/to 表达状态迁移；\`to: null\` 只适用于已有记录并保留状态，不能靠 handler 改 status 绕过状态机。
+- 写入、审计、版本、幂等和事务交给内核；不要在业务项目重建 repository、连接池或权限流水线。
+- 自定义查询声明 reads，二选一使用 sql/build，只读 \`safe.*\`；值参数化。不得拼接 SQL、查询基表绕过范围或硬编码密钥。
+- scope 描述范围字段，角色数据决定实际范围；\`scope.none()\` 不代表所有人可访问。\`can/useCan\` 只控制按钮，后端负责授权。
+- 前端从 \`@app/contracts\` 导入生成 API/类型，按需使用 \`@yss123/cage-client\`；不导入 domain、内核或数据库包。
+- 跨聚合写入通过 reaction 调用命令。\`tx: 'same'\` 共同提交/回滚，默认 outbox 异步执行。资源 acquires/releases 是图规则标签，实际占用/释放仍由命令完成；离开持有状态要检查每条释放路径。
+- 审批通过 approval + route 配置，结论是 process 命令；选中审批人不等于已具备能力、范围和额度。第三方 IO 通过连接器，回调验签后调用 external 命令。
+- job 的读取与调用必须列入 reads/calls。业务导入/导出放在需要的业务页面调用通用任务接口，202 只代表任务已接受；worker 必须运行。
+- 已部署事件只做兼容扩展；新增字段设为 optional，不兼容含义用新事件。已执行/已发布迁移不能改写，结构更新新增迁移。
+- 不手改生成物，不关闭门禁掩盖错误，不因方便自动授予生产角色新能力。unsafe 必须写明 reason/owner，不能替代普通业务声明。
+- 代码注释说明职责、关键流程和设计原因；避免无业务价值的防御分支和静默兜底。维护脚本用 TypeScript，不新增 .mjs。
+
+### 最小命令形状
+
+\`\`\`ts
+// 片段：Order 为已导出的聚合，OrderSubmitted 为事件，业务校验按需求添加。
+export const submitOrder = command(Order, {
+  name: 'submit',
+  from: 'draft',
+  to: 'pending_approval',
+  emits: [OrderSubmitted],
+  handler: (draft) => draft,
+});
+\`\`\`
+
+完整可添加的普通管理对象见 \`docs/ai/primitives.md\` 的 Note；采购模板的审批、资源、第三方示例在 \`packages/domain/src\`，空白模板的参考源码在 \`docs/examples/purchase-admin\`。先读本项目 AGENTS.md 中的模板说明，区分运行代码与参考资料。API 以当前包公开导出和生成契约为准，不发明不存在的配置和方法。
+
+### 启动、验证与排错
+
+在项目根目录执行：首次 \`pnpm install\`，复制并编辑 .env.example，仅提供已有库管理员连接后 \`pnpm exec cage init\`；再 \`pnpm build:app\`、\`pnpm gen\`，审查后 \`pnpm migrate\`，最后 \`pnpm dev\`。已有配置不能覆盖。
+
+init 只准备账号/schema/授权并填写三个连接，不创建数据库；APP/READ/MIGRATE 指向同一个库。已有集群账号复用原密码，日常启动不用管理员。普通项目不新增 Docker 生命周期命令。
+
+- \`pnpm exec cage graph\`：浏览器图谱，默认端口 15418，以终端为准。
+- \`pnpm exec cage context command:对象.命令 --format json --out .cage/context.json\`：按完整 key 取精简上下文；默认 Markdown，可用 --depth/--limit 调整范围。CLI 每次重新抽取；Web“复制 AI 上下文”使用当前页面快照，改代码后先刷新图谱。
+- \`graph inspect/path\` 有歧义时复制候选完整 key；path 默认沿箭头，--direction both 的逆向遍历不表示执行方向。报告中的测试/前端文件是候选，须核对；查询也会覆盖当前 .cage/ontology.json，旧基线务必另存。
+- \`pnpm exec cage gen --check\`：生成一致性；\`pnpm exec cage sync --check\`：本托管区一致性。
+- \`pnpm exec cage test --only project\`：业务测试；\`pnpm verify\`：类型、依赖、lint、图规则、生成、托管区、预算和测试。
+- \`pnpm exec cage verify --skip-tests\` 表示不完整门禁；派生测试跳过不能当作通过。测试连接只用独立测试集群。
+- 重要业务改动验证成功路径及有风险的反例；文档或可逆的小改动不反复跑全量数据库测试。
+- CLI 报错先看 code/at/reason/fix，再查错误码册；HTTP 错误查 runtime.md。异步失败先看 worker、同步记录和死信，修复后重放，不能直接 SQL 改状态。
+
+框架托管区由 cage sync 更新；项目独有的业务规则写在标记之外，避免升级覆盖。
+<!-- cage:end -->`;
+export function syncManagedBlock(current, latest = managedBlock) {
+    const starts = [...current.matchAll(/<!-- cage:begin[^\n]*-->/g)];
+    const ends = [...current.matchAll(/<!-- cage:end -->/g)];
+    if (!starts.length && !ends.length)
+        return latest + '\n\n' + current;
+    if (starts.length !== 1 || ends.length !== 1 || ends[0].index < starts[0].index) {
+        throw new Error('[CAGE-SYNC-001] 托管区标记不完整或重复，请修复 AGENTS.md 的 begin/end 标记');
+    }
+    return current.slice(0, starts[0].index) + latest + current.slice(ends[0].index + ends[0][0].length);
+}
+export function sync(cfg, check = false) {
+    const file = abs(cfg, 'AGENTS.md');
+    const before = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const after = syncManagedBlock(before);
+    if (after === before)
+        return [];
+    if (check)
+        return [
+            {
+                code: 'CAGE-SYNC-001',
+                at: 'AGENTS.md',
+                reason: '框架托管区需要同步',
+                fix: '运行 cage sync；项目自有内容会保留',
+            },
+        ];
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, after);
+    return [];
+}
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,GAAG,EAAmB,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAmFrC,CAAC;AAEnB,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,MAAM,GAAG,YAAY;IACrE,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAC,CAAC,CAAC;IAClE,MAAM,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAC,CAAC;IACzD,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACrE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,KAAM,EAAE,CAAC;QAClF,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxG,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,GAAe,EAAE,KAAK,GAAG,KAAK;IACjD,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClE,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,EAAE,CAAC;IAChC,IAAI,KAAK;QACP,OAAO;YACL;gBACE,IAAI,EAAE,eAAe;gBACrB,EAAE,EAAE,WAAW;gBACf,MAAM,EAAE,WAAW;gBACnB,GAAG,EAAE,wBAAwB;aAC9B;SACF,CAAC;IACJ,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/upgrade.d.ts

@@ -0,0 +1,10 @@
+import { type CageConfig } from './config.js';
+export { VERSION } from './version.js';
+export declare function projectManifests(root: string): string[];
+/** 0.1 接收早期样例里的 caller 写法，运行时规范名为 invokedBy。只改从 kernel 导入的 command。 */
+export declare function codemodSource(source: string): string;
+export declare function upgrade(cfg: CageConfig, opts?: {
+    to?: string;
+    dryRun?: boolean;
+    codemodsOnly?: boolean;
+}): string[];

package/dist/upgrade.js

@@ -0,0 +1,81 @@
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Project, SyntaxKind } from 'ts-morph';
+import { abs } from './config.js';
+import { sync } from './sync.js';
+import { listTs } from './static-check.js';
+import { VERSION } from './version.js';
+export { VERSION } from './version.js';
+export function projectManifests(root) {
+    const out = [];
+    const walk = (dir) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (e.name.startsWith('.') || ['node_modules', 'dist', 'generated'].includes(e.name))
+                continue;
+            const path = join(dir, e.name);
+            if (e.isDirectory())
+                walk(path);
+            else if (e.name === 'package.json')
+                out.push(path);
+        }
+    };
+    walk(root);
+    return out;
+}
+/** 0.1 接收早期样例里的 caller 写法，运行时规范名为 invokedBy。只改从 kernel 导入的 command。 */
+export function codemodSource(source) {
+    const project = new Project({ useInMemoryFileSystem: true });
+    const file = project.createSourceFile('domain.ts', source);
+    const names = new Set(file
+        .getImportDeclarations()
+        .filter((i) => i.getModuleSpecifierValue() === '@yss123/cage-kernel')
+        .flatMap((i) => i
+        .getNamedImports()
+        .filter((n) => n.getName() === 'command')
+        .map((n) => n.getAliasNode()?.getText() ?? n.getName())));
+    for (const call of file.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        if (!names.has(call.getExpression().getText()))
+            continue;
+        const obj = call.getArguments()[1]?.asKind(SyntaxKind.ObjectLiteralExpression);
+        const old = obj?.getProperty('caller')?.asKind(SyntaxKind.PropertyAssignment);
+        if (old && obj?.getProperty('invokedBy'))
+            throw new Error('[CAGE-UPGRADE-001] command 同时包含 caller 与 invokedBy，请手工消除歧义');
+        old?.rename('invokedBy');
+    }
+    return file.getFullText();
+}
+export function upgrade(cfg, opts = {}) {
+    const version = opts.to ?? VERSION;
+    if (version !== VERSION)
+        throw new Error(`[CAGE-UPGRADE-001] 当前 CLI 只包含 ${VERSION} 的迁移；请先安装目标版本的 @yss123/cage-cli 再执行 upgrade`);
+    const changes = new Map();
+    if (!opts.codemodsOnly)
+        for (const file of projectManifests(cfg.root)) {
+            const before = readFileSync(file, 'utf8');
+            const p = JSON.parse(before);
+            let changed = false;
+            for (const group of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+                for (const name of Object.keys(p[group] ?? {}))
+                    if (name.startsWith('@yss123/cage-') && p[group][name] !== version) {
+                        p[group][name] = version;
+                        changed = true;
+                    }
+            }
+            if (changed)
+                changes.set(file, JSON.stringify(p, null, 2) + '\n');
+        }
+    // 只重写业务声明目录，不扫描依赖包、生成契约或已经发布的 SQL。
+    for (const file of listTs(dirname(abs(cfg, cfg.domain)))) {
+        const before = readFileSync(file, 'utf8');
+        const after = codemodSource(before);
+        if (before !== after)
+            changes.set(file, after);
+    }
+    if (!opts.dryRun) {
+        for (const [file, content] of changes)
+            writeFileSync(file, content);
+        sync(cfg);
+    }
+    return [...changes.keys()];
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/upgrade.js.map

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

package/dist/verify.d.ts

@@ -0,0 +1,7 @@
+import { type CageConfig } from './config.js';
+import type { Ontology } from './ontology.js';
+export declare function testProject(cfg: CageConfig, graph: Ontology, only?: 'derived' | 'project'): Promise<number>;
+export declare function verify(cfg: CageConfig, opts?: {
+    base?: Ontology;
+    skipTests?: boolean;
+}): Promise<number>;

package/dist/verify.js

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { ESLint } from 'eslint';
+import cageLint from '@yss123/cage-lint';
+import { abs } from './config.js';
+import { analyze } from './analyze.js';
+import { errorsOnly, formatFindings } from './findings.js';
+import { generate } from './gen/index.js';
+import { deriveTests, vitestConfig, writeDerived } from './derive.js';
+import { binPath, run } from './process.js';
+import { budget } from './budget.js';
+import { sync } from './sync.js';
+export async function testProject(cfg, graph, only) {
+    const derived = deriveTests(cfg, graph);
+    writeDerived(cfg, derived.files);
+    mkdirSync(abs(cfg, '.cage'), { recursive: true });
+    const config = abs(cfg, '.cage/vitest.config.mts');
+    writeFileSync(config, vitestConfig(cfg, only));
+    console.log(`派生测试：${derived.tests.length} 个`);
+    // 保存机器可读报告，门禁同时检查测试结果和进程退出码。
+    // 报告先删除，避免异常退出时误读上一次成功结果；跳过用例会单独列出。
+    const report = abs(cfg, '.cage/test-results.json');
+    if (existsSync(report))
+        unlinkSync(report);
+    const code = await run(binPath('vitest'), ['run', '--config', config, '--reporter=default', '--reporter=json', '--outputFile', report, ...(only === 'project' ? ['--passWithNoTests'] : [])], cfg.root);
+    if (code !== 0)
+        return code;
+    if (!existsSync(report))
+        throw new Error('[CAGE-TEST-001] 测试进程未输出结果报告，不能判定通过');
+    const result = JSON.parse(readFileSync(report, 'utf8'));
+    if (result.numPendingTests)
+        console.log(`覆盖提示：${result.numPendingTests} 个用例跳过，请结合业务测试验收。`);
+    return result.success ? 0 : 1;
+}
+export async function verify(cfg, opts = {}) {
+    const gates = [];
+    const record = (name, findings = [], code = 0) => {
+        const ok = code === 0 && errorsOnly(findings).length === 0;
+        gates.push({ name, ok, findings });
+        console.log(`${ok ? '✓' : '✗'} ${name}`);
+        if (findings.length)
+            console.log(formatFindings(findings));
+        mkdirSync(abs(cfg, '.cage'), { recursive: true });
+        writeFileSync(abs(cfg, '.cage/verify.json'), JSON.stringify({ ok: gates.every((g) => g.ok), complete: false, gates }, null, 2));
+        return ok;
+    };
+    for (const dir of cfg.typecheck)
+        if (!record(`typecheck ${dir}`, [], await run(binPath('typescript', 'tsc'), ['--noEmit', '-p', abs(cfg, dir)], cfg.root)))
+            return 1;
+    const req = createRequire(import.meta.url);
+    if (!record('依赖规则', [], await run(binPath('dependency-cruiser', 'depcruise'), [
+        '--config',
+        req.resolve('@yss123/cage-lint/dependency-cruiser.cjs'),
+        '--output-type',
+        'err-long',
+        ...cfg.lint,
+    ], cfg.root)))
+        return 1;
+    const eslint = new ESLint({
+        cwd: cfg.root,
+        overrideConfigFile: true,
+        overrideConfig: cageLint.configs.recommended,
+    });
+    const lint = await eslint.lintFiles(cfg.lint.map((p) => `${p}/**/*.{ts,tsx,js,mjs}`));
+    const lintFindings = lint.flatMap((f) => f.messages.map((m) => ({
+        code: /\[(CAGE-[\w-]+)\]/.exec(m.message)?.[1] ?? 'CAGE-LINT-001',
+        at: `${f.filePath}:${m.line}`,
+        reason: m.message,
+        severity: m.severity === 1 ? 'warning' : 'error',
+    })));
+    if (!record('代码规则', lintFindings))
+        return 1;
+    const a = await analyze(cfg, { base: opts.base });
+    if (!record('声明与图规则', a.findings) || !a.graph || !a.registry)
+        return 1;
+    if (!record('生成物一致性', generate(cfg, a.registry, a.graph, a.source.sites, { check: true }).findings))
+        return 1;
+    if (!record('托管区一致性', sync(cfg, true)))
+        return 1;
+    if (!record('预算', budget(cfg, a.graph, opts.base).findings))
+        return 1;
+    if (!opts.skipTests && !record('派生与项目测试', [], await testProject(cfg, a.graph)))
+        return 1;
+    writeFileSync(abs(cfg, '.cage/verify.json'), JSON.stringify({ ok: true, complete: !opts.skipTests, gates }, null, 2));
+    console.log(opts.skipTests ? '静态门禁通过（未运行测试）' : '全部门禁通过');
+    return 0;
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

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

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+/** 源码和 dist 都紧邻包清单，直接读取已安装 CLI 的版本。
+ * 脚手架、upgrade 和 AGENTS 托管区共用它，避免升级只改了包版本却仍生成旧依赖。
+ */
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,6 @@
+import { readFileSync } from 'node:fs';
+/** 源码和 dist 都紧邻包清单，直接读取已安装 CLI 的版本。
+ * 脚手架、upgrade 和 AGENTS 托管区共用它，避免升级只改了包版本却仍生成旧依赖。
+ */
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAW,IAAI,CAAC,KAAK,CACvC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAClE,CAAC,OAAO,CAAC"}