@yoyoboot/yoyo-admin-cli 10.5.5

package/dist/bin.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * `yoyo-admin` 可执行入口。
+ *
+ * 职责边界：只做「解析 argv → 分发 → 渲染 → 设置退出码」。
+ * 任何业务逻辑都不在此文件。
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * `yoyo-admin` 可执行入口。
+ *
+ * 职责边界：只做「解析 argv → 分发 → 渲染 → 设置退出码」。
+ * 任何业务逻辑都不在此文件。
+ */
+import { runCli } from './cli.js';
+const exitCode = runCli(process.argv.slice(2));
+process.exitCode = exitCode;

package/dist/catalogs/capability.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 生成的 capability catalog 读取层（**共享事实读取层**）。
+ *
+ * 权限事实源：`Yoyo.Admin.CapabilityExporter` 以最小 ABP boot 枚举权限后
+ * 写入 admin-core 生成边缘；admin-vue 的 `YoyoAdminPermissionKey` 类型化
+ * 字面量联合与 catalog 同源。
+ *
+ * 消费方：
+ *   - frontend-module generator 在 plan-time 校验权限前缀存在性；
+ *   - `inspect permissions` / `inspect permission` 把完整 descriptor
+ *     （displayName / parent / multiTenancySides / source）原样投影给 Agent。
+ *
+ * 因此本层返回**完整 descriptor**，不再退化成 `string[]`。
+ * catalog 缺失 / 为空 / 不可解析 / 条目残缺一律 fail-closed。
+ */
+import type { CatalogSource } from './source.js';
+/** 生成的 capability catalog 位置（随 admin-core 生成边缘更新）。 */
+export declare const CAPABILITY_CATALOG_RELATIVE = "packages/yoyo-admin/admin-core/src/contracts/generated/capability/capability-catalog.json";
+export interface CapabilityPermissionDescriptor {
+    readonly name: string;
+    readonly displayName: string;
+    /** 父权限名；根权限为 null。 */
+    readonly parent: string | null;
+    /** catalog 原样值，例如 `Host` / `Tenant` / `Host|Tenant`。 */
+    readonly multiTenancySides: string | null;
+    readonly source: string | null;
+}
+export interface CapabilityFeatureDescriptor {
+    readonly name: string;
+    readonly scope: string | null;
+    readonly defaultValue: string | null;
+    readonly displayName: string | null;
+    readonly description: string | null;
+    readonly source: string | null;
+}
+export interface CapabilityCatalogDocument {
+    readonly source: CatalogSource;
+    readonly permissions: readonly CapabilityPermissionDescriptor[];
+    readonly features: readonly CapabilityFeatureDescriptor[];
+}
+/** 读取完整 capability catalog 文档；缺失/为空/不可解析/条目残缺时 fail-closed。 */
+export declare function loadCapabilityCatalog(repoRoot: string): CapabilityCatalogDocument;
+/** 全部权限名（frontend-module 的 plan-time 前缀校验用）。 */
+export declare function loadKnownPermissionNames(repoRoot: string): readonly string[];
+/** 精确读取单条权限；不存在时 fail-closed。 */
+export declare function loadPermissionDescriptor(repoRoot: string, permissionName: string): CapabilityPermissionDescriptor;
+/**
+ * 前缀匹配：前缀本身（若存在）+ 其全部后代。
+ *
+ * 无任何匹配时返回空数组，由调用方决定 fail-closed（inspect 会报
+ * `permission-prefix-not-found`），避免 Agent 拼错前缀却拿到「成功的空列表」。
+ */
+export declare function matchPermissionPrefix(repoRoot: string, prefix: string): readonly CapabilityPermissionDescriptor[];
+//# sourceMappingURL=capability.d.ts.map

package/dist/catalogs/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/catalogs/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,8FACqD,CAAA;AAE7F,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAA;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS,8BAA8B,EAAE,CAAA;IAC/D,QAAQ,CAAC,QAAQ,EAAE,SAAS,2BAA2B,EAAE,CAAA;CAC1D;AAyCD,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,yBAAyB,CA2EjF;AAED,gDAAgD;AAChD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAE5E;AAED,iCAAiC;AACjC,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,8BAA8B,CAYhC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,SAAS,8BAA8B,EAAE,CAO3C"}

package/dist/catalogs/capability.js

@@ -0,0 +1,129 @@
+/**
+ * 生成的 capability catalog 读取层（**共享事实读取层**）。
+ *
+ * 权限事实源：`Yoyo.Admin.CapabilityExporter` 以最小 ABP boot 枚举权限后
+ * 写入 admin-core 生成边缘；admin-vue 的 `YoyoAdminPermissionKey` 类型化
+ * 字面量联合与 catalog 同源。
+ *
+ * 消费方：
+ *   - frontend-module generator 在 plan-time 校验权限前缀存在性；
+ *   - `inspect permissions` / `inspect permission` 把完整 descriptor
+ *     （displayName / parent / multiTenancySides / source）原样投影给 Agent。
+ *
+ * 因此本层返回**完整 descriptor**，不再退化成 `string[]`。
+ * catalog 缺失 / 为空 / 不可解析 / 条目残缺一律 fail-closed。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { YoyoAdminCliUsageError } from '../kernel/result.js';
+/** 生成的 capability catalog 位置（随 admin-core 生成边缘更新）。 */
+export const CAPABILITY_CATALOG_RELATIVE = 'packages/yoyo-admin/admin-core/src/contracts/generated/capability/capability-catalog.json';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function readCatalogEntries(value, kind) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new YoyoAdminCliUsageError('capability-catalog-unreadable', `capability catalog 的 ${kind} 必须是数组。`);
+    }
+    const names = new Set();
+    return value.map((entry) => {
+        if (!isRecord(entry) || typeof entry.name !== 'string' || entry.name.trim().length === 0) {
+            throw new YoyoAdminCliUsageError('capability-catalog-unreadable', `capability catalog 的 ${kind} 中存在缺少有效 name 的条目；拒绝按残缺契约工作。`);
+        }
+        const name = entry.name;
+        if (names.has(name)) {
+            throw new YoyoAdminCliUsageError('capability-catalog-unreadable', `capability catalog 的 ${kind} 中存在重复 name：${name}。`);
+        }
+        names.add(name);
+        return { ...entry, name };
+    });
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/** 读取完整 capability catalog 文档；缺失/为空/不可解析/条目残缺时 fail-closed。 */
+export function loadCapabilityCatalog(repoRoot) {
+    const absolute = join(repoRoot, CAPABILITY_CATALOG_RELATIVE);
+    if (!existsSync(absolute)) {
+        throw new YoyoAdminCliUsageError('capability-catalog-missing', `未找到生成的 capability catalog：${CAPABILITY_CATALOG_RELATIVE}。` +
+            '请先在 aspnet-core 运行 CapabilityExporter 刷新 admin-core 生成边缘。');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(absolute, 'utf8'));
+    }
+    catch (error) {
+        throw new YoyoAdminCliUsageError('capability-catalog-unreadable', `capability catalog 解析失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new YoyoAdminCliUsageError('capability-catalog-unreadable', 'capability catalog 必须是 JSON 对象。');
+    }
+    const catalog = parsed;
+    const rawPermissions = readCatalogEntries(catalog.permissions, 'permissions');
+    const permissions = [];
+    for (const permission of rawPermissions) {
+        const name = permission.name;
+        permissions.push({
+            name,
+            displayName: readOptionalString(permission.displayName) ?? name,
+            parent: readOptionalString(permission.parent),
+            multiTenancySides: readOptionalString(permission.multiTenancySides),
+            source: readOptionalString(permission.source),
+        });
+    }
+    if (permissions.length === 0) {
+        throw new YoyoAdminCliUsageError('capability-catalog-empty', 'capability catalog 中没有任何权限；无法校验 --permission-prefix。');
+    }
+    const features = readCatalogEntries(catalog.features, 'features').map((feature) => ({
+        name: feature.name,
+        scope: readOptionalString(feature.scope),
+        defaultValue: readOptionalString(feature.defaultValue),
+        displayName: readOptionalString(feature.displayName),
+        description: readOptionalString(feature.description),
+        source: readOptionalString(feature.source),
+    }));
+    return {
+        source: {
+            path: CAPABILITY_CATALOG_RELATIVE,
+            ...(typeof catalog.schemaVersion === 'string'
+                ? { schemaVersion: catalog.schemaVersion }
+                : {}),
+            ...(typeof catalog.generator === 'string' ? { generator: catalog.generator } : {}),
+            ...(typeof catalog.generatorVersion === 'string'
+                ? { generatorVersion: catalog.generatorVersion }
+                : {}),
+            ...(typeof catalog.sourceHash === 'string' ? { sourceHash: catalog.sourceHash } : {}),
+        },
+        permissions,
+        features,
+    };
+}
+/** 全部权限名（frontend-module 的 plan-time 前缀校验用）。 */
+export function loadKnownPermissionNames(repoRoot) {
+    return loadCapabilityCatalog(repoRoot).permissions.map((permission) => permission.name);
+}
+/** 精确读取单条权限；不存在时 fail-closed。 */
+export function loadPermissionDescriptor(repoRoot, permissionName) {
+    const permissions = loadCapabilityCatalog(repoRoot).permissions;
+    const permission = permissions.find((candidate) => candidate.name === permissionName);
+    if (permission === undefined) {
+        throw new YoyoAdminCliUsageError('unknown-permission-key', `权限 "${permissionName}" 不在 capability catalog 中。` +
+            '请用 `yoyo-admin inspect permissions` 查看真实权限名；新权限先在 aspnet-core 的授权 Provider 定义，' +
+            '再运行 CapabilityExporter 刷新生成物。');
+    }
+    return permission;
+}
+/**
+ * 前缀匹配：前缀本身（若存在）+ 其全部后代。
+ *
+ * 无任何匹配时返回空数组，由调用方决定 fail-closed（inspect 会报
+ * `permission-prefix-not-found`），避免 Agent 拼错前缀却拿到「成功的空列表」。
+ */
+export function matchPermissionPrefix(repoRoot, prefix) {
+    const descendants = `${prefix}.`;
+    return loadCapabilityCatalog(repoRoot)
+        .permissions.filter((permission) => permission.name === prefix || permission.name.startsWith(descendants))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}

package/dist/catalogs/crud.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 生成的 CRUD resource catalog 读取层（**共享事实读取层**）。
+ *
+ * 位置：`src/catalogs/` 是「生成契约事实」的唯一读取层，`generators/`（recipe）
+ * 与 `commands/`（doctor / inspect）共同消费它 —— inspect 不 import generator，
+ * 也不复制第二套 JSON reader。
+ *
+ * 这是 frontend-module generator 与 `inspect resource` 的**契约事实源**：
+ * 读取完整 `crudResources[]` descriptor（operations / requestSchemas / binding），
+ * 由消费方按真实契约派生 actions、权限、最小表单字段与 compatibility 判定。
+ *
+ * catalog 缺失 / 为空 / 不可解析一律 fail-closed，不静默降级。
+ */
+import type { CatalogSource } from './source.js';
+/** 生成的 CRUD resource catalog 位置（随 api-client 生成边缘更新）。 */
+export declare const CRUD_CATALOG_RELATIVE = "apps/yoyo-admin/admin-vue/api-client/src/generated/api-contract-catalog.json";
+export interface CrudFieldMapping {
+    readonly source: string;
+    readonly target: readonly string[];
+}
+/** catalog 中单个 CRUD 资源的完整 descriptor（只取消费方关心的切片）。 */
+export interface CrudResourceDescriptor {
+    readonly resourceKey: string;
+    readonly serviceName: string;
+    /** operation 名 → OpenAPI operationId；key 集合即该资源真实具备的能力。 */
+    readonly operations: Readonly<Record<string, string>>;
+    /** operation 名 → 请求体 schema 引用。 */
+    readonly requestSchemas: Readonly<Record<string, string>>;
+    readonly binding?: {
+        readonly list?: {
+            /** 查询参数名（camelCase）→ 后端字段名。 */
+            readonly query?: Readonly<Record<string, string>>;
+            readonly itemsPath?: readonly string[];
+            readonly totalCountPath?: readonly string[];
+        };
+        readonly getForEdit?: {
+            readonly idParameter?: string;
+            readonly entityPath?: readonly string[];
+        };
+        readonly create?: {
+            readonly fieldMappings?: readonly CrudFieldMapping[];
+        };
+        readonly update?: {
+            readonly fieldMappings?: readonly CrudFieldMapping[];
+        };
+        readonly setEnabled?: {
+            readonly fieldMappings?: readonly CrudFieldMapping[];
+        };
+        readonly remove?: {
+            readonly idParameter?: string;
+        };
+    };
+}
+export interface CrudCatalogDocument {
+    readonly source: CatalogSource;
+    readonly resources: readonly CrudResourceDescriptor[];
+}
+/** 读取完整 catalog 文档（含生成元信息）；catalog 缺失/为空/不可解析时 fail-closed。 */
+export declare function loadCrudCatalog(repoRoot: string): CrudCatalogDocument;
+export declare function loadCrudResourceDescriptors(repoRoot: string): readonly CrudResourceDescriptor[];
+export declare function loadKnownResourceKeys(repoRoot: string): readonly string[];
+/** 按资源 key 读取单个 descriptor；不存在时 fail-closed。 */
+export declare function loadCrudResourceDescriptor(repoRoot: string, resourceKey: string): CrudResourceDescriptor;
+//# sourceMappingURL=crud.d.ts.map

package/dist/catalogs/crud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crud.d.ts","sourceRoot":"","sources":["../../src/catalogs/crud.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,iFAC8C,CAAA;AAEhF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,qDAAqD;AACrD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACrD,mCAAmC;IACnC,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE;QACjB,QAAQ,CAAC,IAAI,CAAC,EAAE;YACd,+BAA+B;YAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;YACjD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;YACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;SAC5C,CAAA;QACD,QAAQ,CAAC,UAAU,CAAC,EAAE;YAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;SAAE,CAAA;QAChG,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;SAAE,CAAA;QAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;SAAE,CAAA;QAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE;YAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;SAAE,CAAA;QAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE;YAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KACpD,CAAA;CACF;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAA;CACtD;AAeD,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CA+DrE;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,sBAAsB,EAAE,CAE/F;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEzE;AAED,gDAAgD;AAChD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,sBAAsB,CAYxB"}

package/dist/catalogs/crud.js

@@ -0,0 +1,83 @@
+/**
+ * 生成的 CRUD resource catalog 读取层（**共享事实读取层**）。
+ *
+ * 位置：`src/catalogs/` 是「生成契约事实」的唯一读取层，`generators/`（recipe）
+ * 与 `commands/`（doctor / inspect）共同消费它 —— inspect 不 import generator，
+ * 也不复制第二套 JSON reader。
+ *
+ * 这是 frontend-module generator 与 `inspect resource` 的**契约事实源**：
+ * 读取完整 `crudResources[]` descriptor（operations / requestSchemas / binding），
+ * 由消费方按真实契约派生 actions、权限、最小表单字段与 compatibility 判定。
+ *
+ * catalog 缺失 / 为空 / 不可解析一律 fail-closed，不静默降级。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { YoyoAdminCliUsageError } from '../kernel/result.js';
+/** 生成的 CRUD resource catalog 位置（随 api-client 生成边缘更新）。 */
+export const CRUD_CATALOG_RELATIVE = 'apps/yoyo-admin/admin-vue/api-client/src/generated/api-contract-catalog.json';
+/** 读取完整 catalog 文档（含生成元信息）；catalog 缺失/为空/不可解析时 fail-closed。 */
+export function loadCrudCatalog(repoRoot) {
+    const absolute = join(repoRoot, CRUD_CATALOG_RELATIVE);
+    if (!existsSync(absolute)) {
+        throw new YoyoAdminCliUsageError('crud-catalog-missing', `未找到生成的 CRUD resource catalog：${CRUD_CATALOG_RELATIVE}。` +
+            '请先在 admin-vue 执行 api:update 生成契约边缘。');
+    }
+    let catalog;
+    try {
+        catalog = JSON.parse(readFileSync(absolute, 'utf8'));
+    }
+    catch (error) {
+        throw new YoyoAdminCliUsageError('crud-catalog-unreadable', `CRUD resource catalog 解析失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        const resources = (catalog.crudResources ?? []).map((resource) => {
+            if (typeof resource.resourceKey !== 'string' || resource.resourceKey.length === 0) {
+                throw new YoyoAdminCliUsageError('crud-catalog-unreadable', 'CRUD resource catalog 中存在缺少 resourceKey 的资源条目；拒绝按残缺契约工作。');
+            }
+            return {
+                resourceKey: resource.resourceKey,
+                serviceName: typeof resource.serviceName === 'string' ? resource.serviceName : resource.resourceKey,
+                operations: resource.operations ?? {},
+                requestSchemas: resource.requestSchemas ?? {},
+                ...(resource.binding !== undefined ? { binding: resource.binding } : {}),
+            };
+        });
+        if (resources.length === 0) {
+            throw new YoyoAdminCliUsageError('crud-catalog-empty', 'CRUD resource catalog 中没有任何资源；无法校验 --resource。');
+        }
+        return {
+            source: {
+                path: CRUD_CATALOG_RELATIVE,
+                ...(typeof catalog.schemaVersion === 'string' ? { schemaVersion: catalog.schemaVersion } : {}),
+                ...(typeof catalog.generatorVersion === 'string'
+                    ? { generatorVersion: catalog.generatorVersion }
+                    : {}),
+                ...(typeof catalog.sourceHash === 'string' ? { sourceHash: catalog.sourceHash } : {}),
+            },
+            resources,
+        };
+    }
+    catch (error) {
+        if (error instanceof YoyoAdminCliUsageError)
+            throw error;
+        throw new YoyoAdminCliUsageError('crud-catalog-unreadable', `CRUD resource catalog 结构无法识别：${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function loadCrudResourceDescriptors(repoRoot) {
+    return loadCrudCatalog(repoRoot).resources;
+}
+export function loadKnownResourceKeys(repoRoot) {
+    return loadCrudResourceDescriptors(repoRoot).map(descriptor => descriptor.resourceKey);
+}
+/** 按资源 key 读取单个 descriptor；不存在时 fail-closed。 */
+export function loadCrudResourceDescriptor(repoRoot, resourceKey) {
+    const descriptors = loadCrudResourceDescriptors(repoRoot);
+    const descriptor = descriptors.find(candidate => candidate.resourceKey === resourceKey);
+    if (descriptor === undefined) {
+        throw new YoyoAdminCliUsageError('unknown-resource-key', `resourceKey "${resourceKey}" 不在生成的 CRUD resource catalog 中` +
+            `（当前可用：${descriptors.map(item => item.resourceKey).join(', ')}）。` +
+            '请先确认后端契约已生成；如属新资源，先走 api:update 刷新生成边缘。');
+    }
+    return descriptor;
+}

package/dist/catalogs/source.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 生成契约事实源的公共元信息。
+ *
+ * 每个 catalog 文档都带一份**生成元信息**（谁生成的、哪个 schema 版本、
+ * 基于哪个 sourceHash）。`inspect` 把它原样投影给 Agent —— 让 Agent 知道
+ * 自己读到的是不是当前边缘，而不是只看到一堆条目。
+ */
+export interface CatalogSource {
+    /** 仓库根相对路径。 */
+    readonly path: string;
+    readonly schemaVersion?: string;
+    readonly generator?: string;
+    readonly generatorVersion?: string;
+    readonly sourceHash?: string;
+}
+//# sourceMappingURL=source.d.ts.map

package/dist/catalogs/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/catalogs/source.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,eAAe;IACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B"}

package/dist/catalogs/source.js

@@ -0,0 +1,8 @@
+/**
+ * 生成契约事实源的公共元信息。
+ *
+ * 每个 catalog 文档都带一份**生成元信息**（谁生成的、哪个 schema 版本、
+ * 基于哪个 sourceHash）。`inspect` 把它原样投影给 Agent —— 让 Agent 知道
+ * 自己读到的是不是当前边缘，而不是只看到一堆条目。
+ */
+export {};

package/dist/catalogs/standard-crud.d.ts

@@ -0,0 +1,51 @@
+/**
+ * standard-crud 兼容性派生（**纯契约派生，generator 与 inspect 共用**）。
+ *
+ * 只有一处派生逻辑：`deriveStandardCrudCompatibility()` 读真实 descriptor，
+ * 返回**可观察结果**而不是抛错；两边的差异只在呈现方式：
+ *   - `generators/frontend-module.ts` 用 `deriveStandardCrudShape()` 把
+ *     `eligible: false` 转成 plan-time fail-closed（YoyoAdminCliUsageError）；
+ *   - `inspect resource` 把同一个结果原样投影给 Agent —— 「资源不是 standard-crud」
+ *     是**观察结果**，不是 inspect 命令失败。
+ *
+ * 契约事实：actions/权限/最小表单字段全部由 descriptor 派生，不猜业务事实：
+ *   - 资源没有 `remove` operation → 绝不生成 delete action / Delete 权限；
+ *   - form 字段取自 `binding.create.fieldMappings[].source`（排除系统字段），
+ *     生命周期按 `binding.update.fieldMappings` 派生（create∩update → both；
+ *     create-only → `editableOn: 'create'`），保证宿主 YVAL005 校验通过；
+ *   - rowKey 来自 `binding.getForEdit.idParameter`。
+ */
+import type { CrudResourceDescriptor } from './crud.js';
+/** 运行时供给的字段：出现在 update 契约但不属于表单（与 admin-schema compiler 对齐）。 */
+export declare const RUNTIME_SUPPLIED_FIELDS: ReadonlySet<string>;
+export interface StandardCrudShapeField {
+    readonly key: string;
+    /** 'both' = create+edit 均可编辑（缺省声明）；'create' = 仅 create 阶段可编辑。 */
+    readonly editableOn: 'create' | 'both';
+}
+export interface StandardCrudShape {
+    readonly rowKey: string;
+    readonly formFields: readonly StandardCrudShapeField[];
+    readonly canCreate: boolean;
+    readonly canUpdate: boolean;
+    readonly canSetEnabled: boolean;
+    readonly canRemove: boolean;
+}
+export type StandardCrudCompatibility = {
+    readonly eligible: true;
+    readonly shape: StandardCrudShape;
+} | {
+    readonly eligible: false;
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * 纯派生：从 descriptor 判定 standard-crud 兼容性。
+ *
+ * 不抛错、不做 IO —— 失败以 `{ eligible: false, code, message }` 表达，
+ * 让调用方自己决定是 fail-closed（generator）还是如实上报（inspect）。
+ */
+export declare function deriveStandardCrudCompatibility(descriptor: CrudResourceDescriptor): StandardCrudCompatibility;
+/** generator 视图：`eligible: false` 即 plan-time fail-closed。 */
+export declare function deriveStandardCrudShape(descriptor: CrudResourceDescriptor): StandardCrudShape;
+//# sourceMappingURL=standard-crud.d.ts.map

package/dist/catalogs/standard-crud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-crud.d.ts","sourceRoot":"","sources":["../../src/catalogs/standard-crud.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAEvD,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAItD,CAAA;AAEF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,QAAQ,GAAG,MAAM,CAAA;CACvC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,sBAAsB,EAAE,CAAA;IACtD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEjF;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,sBAAsB,GACjC,yBAAyB,CAkE3B;AAED,8DAA8D;AAC9D,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,sBAAsB,GAAG,iBAAiB,CAM7F"}

package/dist/catalogs/standard-crud.js

@@ -0,0 +1,100 @@
+/**
+ * standard-crud 兼容性派生（**纯契约派生，generator 与 inspect 共用**）。
+ *
+ * 只有一处派生逻辑：`deriveStandardCrudCompatibility()` 读真实 descriptor，
+ * 返回**可观察结果**而不是抛错；两边的差异只在呈现方式：
+ *   - `generators/frontend-module.ts` 用 `deriveStandardCrudShape()` 把
+ *     `eligible: false` 转成 plan-time fail-closed（YoyoAdminCliUsageError）；
+ *   - `inspect resource` 把同一个结果原样投影给 Agent —— 「资源不是 standard-crud」
+ *     是**观察结果**，不是 inspect 命令失败。
+ *
+ * 契约事实：actions/权限/最小表单字段全部由 descriptor 派生，不猜业务事实：
+ *   - 资源没有 `remove` operation → 绝不生成 delete action / Delete 权限；
+ *   - form 字段取自 `binding.create.fieldMappings[].source`（排除系统字段），
+ *     生命周期按 `binding.update.fieldMappings` 派生（create∩update → both；
+ *     create-only → `editableOn: 'create'`），保证宿主 YVAL005 校验通过；
+ *   - rowKey 来自 `binding.getForEdit.idParameter`。
+ */
+import { YoyoAdminCliUsageError } from '../kernel/result.js';
+/** 运行时供给的字段：出现在 update 契约但不属于表单（与 admin-schema compiler 对齐）。 */
+export const RUNTIME_SUPPLIED_FIELDS = new Set([
+    'id',
+    'concurrencyToken',
+    'concurrencyStamp',
+]);
+/**
+ * 纯派生：从 descriptor 判定 standard-crud 兼容性。
+ *
+ * 不抛错、不做 IO —— 失败以 `{ eligible: false, code, message }` 表达，
+ * 让调用方自己决定是 fail-closed（generator）还是如实上报（inspect）。
+ */
+export function deriveStandardCrudCompatibility(descriptor) {
+    const idParameter = descriptor.binding?.getForEdit?.idParameter;
+    if (idParameter === undefined || idParameter.length === 0) {
+        return {
+            eligible: false,
+            code: 'resource-binding-incomplete',
+            message: `资源 ${descriptor.resourceKey} 的 catalog binding 缺少 getForEdit.idParameter，` +
+                '无法确定 rowKey；standard-crud 不可用。',
+        };
+    }
+    const has = (operation) => Object.prototype.hasOwnProperty.call(descriptor.operations, operation);
+    // update 契约字段集合（去运行时供给字段）；资源声明 update 能力时必须提供，
+    // 否则无法确定字段生命周期（宿主 YVAL005 校验必然失败）。
+    const updateFieldKeys = new Set();
+    if (has('update')) {
+        const updateMappings = descriptor.binding?.update?.fieldMappings;
+        if (updateMappings === undefined) {
+            return {
+                eligible: false,
+                code: 'resource-binding-incomplete',
+                message: `资源 ${descriptor.resourceKey} 声明了 update operation，但 catalog binding 缺少 ` +
+                    'update.fieldMappings，无法确定表单字段生命周期（宿主 YVAL005 校验需要）；standard-crud 不可用。',
+            };
+        }
+        for (const mapping of updateMappings) {
+            if (!RUNTIME_SUPPLIED_FIELDS.has(mapping.source))
+                updateFieldKeys.add(mapping.source);
+        }
+    }
+    const createMappings = descriptor.binding?.create?.fieldMappings ?? [];
+    const formFields = [];
+    for (const mapping of createMappings) {
+        if (RUNTIME_SUPPLIED_FIELDS.has(mapping.source))
+            continue;
+        if (formFields.some(field => field.key === mapping.source))
+            continue;
+        formFields.push({
+            key: mapping.source,
+            editableOn: updateFieldKeys.has(mapping.source) ? 'both' : 'create',
+        });
+    }
+    if (formFields.length === 0) {
+        return {
+            eligible: false,
+            code: 'resource-has-no-creatable-fields',
+            message: `资源 ${descriptor.resourceKey} 的 create fieldMappings 未提供任何业务字段；` +
+                'standard-crud 无法构成最小表单。请先确认后端契约与 api:update 生成边缘，' +
+                '或按 typed extension 处理该资源。',
+        };
+    }
+    return {
+        eligible: true,
+        shape: {
+            rowKey: idParameter,
+            formFields,
+            canCreate: has('create'),
+            canUpdate: has('update'),
+            canSetEnabled: has('setEnabled'),
+            canRemove: has('remove'),
+        },
+    };
+}
+/** generator 视图：`eligible: false` 即 plan-time fail-closed。 */
+export function deriveStandardCrudShape(descriptor) {
+    const compatibility = deriveStandardCrudCompatibility(descriptor);
+    if (!compatibility.eligible) {
+        throw new YoyoAdminCliUsageError(compatibility.code, compatibility.message);
+    }
+    return compatibility.shape;
+}

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `yoyo-admin` CLI 入口。
+ *
+ * 退出码约定：
+ *   0 = 成功（含 `--help`）
+ *   2 = 预期失败（用户输入或仓库状态不允许执行）
+ *   1 = 未预期失败（程序缺陷）
+ */
+import { YoyoAdminCliRegistry } from './kernel/command.js';
+export declare const EXIT_OK = 0;
+export declare const EXIT_UNEXPECTED = 1;
+export declare const EXIT_USAGE = 2;
+export interface RunCliOptions {
+    readonly write?: (text: string) => void;
+    /** 仓库查找起点；被 `--repo <path>` 覆盖。缺省 `process.cwd()`。 */
+    readonly startDirectory?: string;
+}
+export declare function createRegistry(): YoyoAdminCliRegistry;
+export declare function runCli(argv: readonly string[], options?: RunCliOptions): number;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAY,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAWpE,eAAO,MAAM,OAAO,IAAI,CAAA;AACxB,eAAO,MAAM,eAAe,IAAI,CAAA;AAChC,eAAO,MAAM,UAAU,IAAI,CAAA;AAE3B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,wBAAgB,cAAc,IAAI,oBAAoB,CAMrD;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA4BnF"}