@yoyoboot/yoyo-admin-cli 10.5.5

package/dist/cli.js

@@ -0,0 +1,86 @@
+/**
+ * `yoyo-admin` CLI 入口。
+ *
+ * 退出码约定：
+ *   0 = 成功（含 `--help`）
+ *   2 = 预期失败（用户输入或仓库状态不允许执行）
+ *   1 = 未预期失败（程序缺陷）
+ */
+import { dispatch, YoyoAdminCliRegistry } from './kernel/command.js';
+import { isHelpPayload } from './kernel/help.js';
+import { renderCapabilities, renderFsPlan, renderJson, renderResult } from './kernel/render.js';
+import { failure, finding, hasError, YoyoAdminCliUsageError } from './kernel/result.js';
+import { isFsPlan } from './kernel/fs-plan.js';
+import { createCapabilitiesCommand } from './commands/capabilities.js';
+import { createCommand } from './commands/create.js';
+import { doctorCommand } from './commands/doctor.js';
+import { inspectCommand, isInspectPayload, renderInspectPayload } from './commands/inspect.js';
+import { createContractsCommand, isContractsStatusPayload, renderContractsStatus } from './commands/contracts.js';
+export const EXIT_OK = 0;
+export const EXIT_UNEXPECTED = 1;
+export const EXIT_USAGE = 2;
+export function createRegistry() {
+    const registry = new YoyoAdminCliRegistry();
+    registry.register(doctorCommand, createCommand, inspectCommand, createContractsCommand());
+    // capabilities 需要读取注册表自身，因此在其余命令注册完成后创建。
+    registry.register(createCapabilitiesCommand(registry));
+    return registry;
+}
+export function runCli(argv, options = {}) {
+    const write = options.write ?? ((text) => process.stdout.write(text));
+    // 失败路径拿不到解析结果；`--json` / `--dry-run` 是布尔 flag，永不接受取值，
+    // 因此直接用 argv 判定与解析结果一致。
+    const fallback = { json: argv.includes('--json'), dryRun: argv.includes('--dry-run') };
+    const registry = createRegistry();
+    try {
+        const outcome = dispatch(registry, argv, options.startDirectory === undefined ? {} : { startDirectory: options.startDirectory });
+        emit(outcome.result, { json: outcome.json, dryRun: outcome.dryRun, write });
+        return hasError(outcome.result) ? EXIT_USAGE : EXIT_OK;
+    }
+    catch (error) {
+        if (error instanceof YoyoAdminCliUsageError) {
+            const result = failure('cli', [finding(error.code, 'error', error.message)]);
+            emit(result, { ...fallback, write });
+            return EXIT_USAGE;
+        }
+        const result = failure('cli', [
+            finding('unexpected-error', 'error', 'CLI 遇到未预期错误。', error instanceof Error ? error.stack ?? error.message : String(error)),
+        ]);
+        emit(result, { ...fallback, write });
+        return EXIT_UNEXPECTED;
+    }
+}
+function emit(result, options) {
+    // help 永远输出人类可读文本（即使带 --json）——它本身就是给人看的投影。
+    if (isHelpPayload(result.data)) {
+        options.write(result.data.text);
+        return;
+    }
+    if (options.json) {
+        options.write(renderJson(result));
+        return;
+    }
+    const plan = result.data !== undefined && isFsPlan(result.data) ? result.data : undefined;
+    const inspect = result.data !== undefined && isInspectPayload(result.data) ? result.data : undefined;
+    const contracts = isContractsStatusPayload(result.data) ? result.data : undefined;
+    // 有专用渲染器的载荷不再重复 dump JSON。
+    options.write(renderResult(result, { omitData: plan !== undefined || inspect !== undefined || contracts !== undefined }));
+    if (contracts !== undefined) {
+        options.write(renderContractsStatus(contracts));
+        return;
+    }
+    if (plan !== undefined) {
+        options.write(renderFsPlan(plan, { dryRun: options.dryRun }));
+        return;
+    }
+    if (inspect !== undefined) {
+        options.write(renderInspectPayload(inspect));
+        return;
+    }
+    if (result.command === 'capabilities') {
+        const capabilities = result.data;
+        if (capabilities?.recipes) {
+            options.write(renderCapabilities(capabilities.recipes));
+        }
+    }
+}

package/dist/commands/capabilities.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `yoyo-admin capabilities`
+ *
+ * 实时机器可读的能力清单。
+ *
+ * 这是 Agent 选择 recipe 的**唯一事实源**：Skill 先调用本命令，
+ * 再决定用哪个 recipe，而不是从文档里记忆未来能力。
+ *
+ * create 的 recipes 直接从 create-registry 投影（含 kinds、必填参数与 flags），
+ * 与 dispatch/help 共用同一注册表，不存在多处漂移。
+ */
+import { type YoyoAdminCliRegistry } from '../kernel/command.js';
+export declare const CAPABILITIES_SCHEMA_VERSION = "1.3.0";
+export interface CapabilitiesPayload {
+    readonly schemaVersion: string;
+    readonly cli: {
+        readonly name: string;
+        readonly invocation: string;
+        readonly globalFlags: readonly {
+            readonly flag: string;
+            readonly description: string;
+        }[];
+    };
+    readonly commands: readonly {
+        readonly name: string;
+        readonly summary: string;
+        readonly usage: string;
+        readonly authoring: boolean;
+        readonly capability?: string;
+        readonly booleanFlags?: readonly string[];
+        readonly arguments: readonly {
+            readonly name: string;
+            readonly required: boolean;
+            readonly description: string;
+        }[];
+        readonly options: readonly {
+            readonly flag: string;
+            readonly description: string;
+            readonly values?: readonly string[];
+            readonly default?: string;
+        }[];
+    }[];
+    readonly create: {
+        readonly recipes: readonly {
+            readonly name: string;
+            readonly kinds: readonly string[];
+            readonly summary: string;
+            readonly usage: string;
+            readonly options: readonly {
+                readonly flag: string;
+                readonly required: boolean;
+                readonly description: string;
+                readonly values?: readonly string[];
+            }[];
+        }[];
+    };
+    readonly inspect: {
+        readonly subjects: readonly {
+            readonly name: string;
+            readonly summary: string;
+            readonly usage: string;
+            readonly arguments: readonly {
+                readonly name: string;
+                readonly required: boolean;
+                readonly description: string;
+            }[];
+            readonly options: readonly {
+                readonly flag: string;
+                readonly required: boolean;
+                readonly description: string;
+                readonly values?: readonly string[];
+            }[];
+        }[];
+    };
+}
+export declare function buildCapabilities(registry: YoyoAdminCliRegistry): CapabilitiesPayload;
+export declare function createCapabilitiesCommand(registry: YoyoAdminCliRegistry): import("../index.js").RegisteredCommand;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/commands/capabilities.d.ts.map

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

package/dist/commands/capabilities.js

@@ -0,0 +1,72 @@
+/**
+ * `yoyo-admin capabilities`
+ *
+ * 实时机器可读的能力清单。
+ *
+ * 这是 Agent 选择 recipe 的**唯一事实源**：Skill 先调用本命令，
+ * 再决定用哪个 recipe，而不是从文档里记忆未来能力。
+ *
+ * create 的 recipes 直接从 create-registry 投影（含 kinds、必填参数与 flags），
+ * 与 dispatch/help 共用同一注册表，不存在多处漂移。
+ */
+import { defineCommand } from '../kernel/command.js';
+import { ok } from '../kernel/result.js';
+import { listCreateRecipes } from './create-registry.js';
+import { listInspectSubjects } from './inspect.js';
+export const CAPABILITIES_SCHEMA_VERSION = '1.3.0';
+export function buildCapabilities(registry) {
+    return {
+        schemaVersion: CAPABILITIES_SCHEMA_VERSION,
+        cli: {
+            name: 'yoyo-admin',
+            invocation: 'yoyo-admin <command> [arguments] [options]',
+            globalFlags: [
+                { flag: '--json', description: '以 JSON 输出完整结果信封，供机器读取。' },
+                { flag: '--dry-run', description: '仅展示计划变更，不写入任何文件（仅作者命令）。' },
+                { flag: '--help', description: '展示帮助；`yoyo-admin --help` / `yoyo-admin create package --help`。' },
+                { flag: '--repo', description: '显式指定仓库查找起点；缺省从当前工作目录向上查找。' },
+            ],
+        },
+        commands: registry.describeCapabilities().map(command => ({
+            name: command.name,
+            summary: command.summary,
+            usage: command.usage,
+            authoring: command.authoring,
+            ...(command.capability === undefined ? {} : { capability: command.capability }),
+            arguments: command.arguments,
+            options: command.options,
+            ...(command.booleanFlags === undefined ? {} : { booleanFlags: command.booleanFlags }),
+        })),
+        create: {
+            recipes: listCreateRecipes().map(recipe => ({
+                name: recipe.name,
+                kinds: recipe.kinds,
+                summary: recipe.summary,
+                usage: recipe.usage,
+                options: recipe.options,
+            })),
+        },
+        inspect: {
+            subjects: listInspectSubjects().map(subject => ({
+                name: subject.name,
+                summary: subject.summary,
+                usage: subject.usage,
+                arguments: subject.arguments,
+                options: subject.options,
+            })),
+        },
+    };
+}
+export function createCapabilitiesCommand(registry) {
+    return defineCommand({
+        descriptor: {
+            name: 'capabilities',
+            summary: '列出 CLI 当前真实支持的命令与 recipe；Agent 应据此选择工作流。',
+            usage: 'yoyo-admin capabilities [--repo <path>] [--json]',
+            arguments: [],
+            options: [],
+            authoring: false,
+        },
+        run: () => ok('capabilities', [], buildCapabilities(registry)),
+    });
+}

package/dist/commands/contracts.d.ts

@@ -0,0 +1,16 @@
+import { type ProcessRunner } from '../kernel/process-runner.js';
+export type ContractStatus = 'current' | 'stale' | 'unavailable' | 'error';
+export interface ContractCheck {
+    readonly status: ContractStatus;
+    readonly owner: string;
+    readonly command: string;
+    readonly message: string;
+}
+export interface ContractsStatusPayload {
+    readonly kind: 'contracts-status';
+    readonly checks: Readonly<Record<'capability' | 'actionContracts' | 'apiGenerated' | 'validationLinkage' | 'liveOpenApi', ContractCheck>>;
+}
+export declare function createContractsCommand(runner?: ProcessRunner, environment?: NodeJS.ProcessEnv): import("../index.js").RegisteredCommand;
+export declare function isContractsStatusPayload(value: unknown): value is ContractsStatusPayload;
+export declare function renderContractsStatus(data: ContractsStatusPayload): string;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/commands/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/commands/contracts.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,aAAa,EAAuB,MAAM,6BAA6B,CAAA;AAGjG,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,GAAG,OAAO,CAAA;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AACD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,GAAG,iBAAiB,GAAG,cAAc,GAAG,mBAAmB,GAAG,aAAa,EAAE,aAAa,CAAC,CAAC,CAAA;CAC1I;AAID,wBAAgB,sBAAsB,CACpC,MAAM,GAAE,aAA0B,EAClC,WAAW,GAAE,MAAM,CAAC,UAAwB,2CAqE7C;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAExF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAI1E"}

package/dist/commands/contracts.js

@@ -0,0 +1,83 @@
+import { join } from 'node:path';
+import { defineCommand, requireWorkspace } from '../kernel/command.js';
+import { runProcess } from '../kernel/process-runner.js';
+import { failure, finding, ok, warn, YoyoAdminCliUsageError } from '../kernel/result.js';
+const liveHint = '启动 Web.Host 并设置 YOYO_ADMIN_OPENAPI_URL，或使用 Run-FullStack.ps1 -RefreshApiClient。';
+export function createContractsCommand(runner = runProcess, environment = process.env) {
+    return defineCommand({
+        descriptor: {
+            name: 'contracts',
+            summary: '只读契约同步诊断；--check 要求全部 current，否则 exit 2。',
+            usage: 'yoyo-admin contracts status [--check] [--json]',
+            arguments: [{ name: 'status', required: true, description: '只读检查五类契约同步状态。' }],
+            options: [],
+            booleanFlags: ['--check'],
+            authoring: false,
+        },
+        run: context => {
+            const { positionals } = context.parsed;
+            if (positionals.length !== 1 || positionals[0] !== 'status') {
+                throw new YoyoAdminCliUsageError('unsupported-contracts-command', '仅支持 contracts status；未知或多余参数不受支持。');
+            }
+            if (context.dryRun) {
+                throw new YoyoAdminCliUsageError('contracts-dry-run-unsupported', 'contracts status 是只读诊断，不支持 --dry-run。');
+            }
+            const { repoRoot } = requireWorkspace(context);
+            const host = join(repoRoot, 'apps/yoyo-admin/admin-vue');
+            const check = (owner, request, live = false) => {
+                const command = [request.command, ...request.args].join(' ');
+                let status;
+                let message;
+                try {
+                    const result = runner(request);
+                    if (result.error) {
+                        status = ['ENOENT', 'EACCES', 'EPERM'].includes(result.error.code ?? '') ? 'unavailable' : 'error';
+                        message = `无法执行 owner check (${result.error.code ?? 'process-error'})。`;
+                    }
+                    else {
+                        status = result.status === 0 ? 'current' : result.status === 3 ? 'stale'
+                            : live && result.status === 4 ? 'unavailable' : 'error';
+                        message = status === 'current' ? 'Owner check 确认契约一致。'
+                            : status === 'stale' ? 'Owner check 检测到契约漂移，请使用正式 owner 生成入口刷新。'
+                                : status === 'unavailable' ? liveHint : `Owner check 执行失败 (exit ${result.status ?? 'signal'})；请单独执行所列命令查看诊断。`;
+                    }
+                }
+                catch (error) {
+                    const code = error?.code;
+                    status = ['ENOENT', 'EACCES', 'EPERM'].includes(code ?? '') ? 'unavailable' : 'error';
+                    message = `Owner runner 执行失败 (${code ?? 'unexpected-error'})。`;
+                }
+                return { status, owner, command, message };
+            };
+            const exporter = (name, output) => check(name, {
+                command: 'dotnet', cwd: repoRoot,
+                args: ['run', '--project', `apps/yoyo-admin/aspnet-core/tools/${name}/${name}.csproj`, '--', '--check', '--output', output],
+            });
+            const data = {
+                kind: 'contracts-status',
+                checks: {
+                    capability: exporter('CapabilityExporter', 'packages/yoyo-admin/admin-core/src/contracts/generated/capability/capability-catalog.json'),
+                    actionContracts: exporter('ActionContractExporter', 'packages/yoyo-admin/admin-schema/src/generated/action-contract/action-contract-catalog.json'),
+                    apiGenerated: check('admin-vue api:verify', { command: 'pnpm', args: ['run', 'api:verify'], cwd: host }),
+                    validationLinkage: check('admin-vue api:validation-linkage', { command: 'pnpm', args: ['run', 'api:validation-linkage'], cwd: host }),
+                    liveOpenApi: environment.YOYO_ADMIN_OPENAPI_URL?.trim()
+                        ? check('admin-vue api:live-drift', { command: 'pnpm', args: ['run', 'api:live-drift'], cwd: host }, true)
+                        : { status: 'unavailable', owner: 'admin-vue api:live-drift', command: 'pnpm run api:live-drift', message: liveHint },
+                },
+            };
+            const current = Object.values(data.checks).every(item => item.status === 'current');
+            if (current)
+                return ok('contracts status', [], data);
+            if (context.parsed.flags.has('--check')) {
+                return failure('contracts status', [finding('contracts-not-current', 'error', '契约未全部同步；查看各项状态。')], data);
+            }
+            return warn('contracts status', [], data);
+        },
+    });
+}
+export function isContractsStatusPayload(value) {
+    return typeof value === 'object' && value !== null && 'kind' in value && value.kind === 'contracts-status';
+}
+export function renderContractsStatus(data) {
+    return Object.entries(data.checks).map(([name, check]) => `  [${check.status}] ${name}\n    ${check.message}\n`).join('');
+}

package/dist/commands/create-frontend-module.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `create frontend-module` recipe 注册。
+ *
+ * 解析命令行参数 → 构建 contract-driven FsPlan → dry-run / 事务化落盘。
+ */
+import type { RegisterCreateRecipe } from './create-registry.js';
+export declare function registerFrontendModuleRecipe(register: RegisterCreateRecipe): void;
+//# sourceMappingURL=create-frontend-module.d.ts.map

package/dist/commands/create-frontend-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-frontend-module.d.ts","sourceRoot":"","sources":["../../src/commands/create-frontend-module.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAEhE,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAoDjF"}

package/dist/commands/create-frontend-module.js

@@ -0,0 +1,90 @@
+/**
+ * `create frontend-module` recipe 注册。
+ *
+ * 解析命令行参数 → 构建 contract-driven FsPlan → dry-run / 事务化落盘。
+ */
+import { requireWorkspace } from '../kernel/command.js';
+import { planRunner } from '../kernel/plan-runner.js';
+import { finding, ok } from '../kernel/result.js';
+import { requireOption, optionalOption } from '../kernel/arguments.js';
+import { STANDARD_CRUD_KIND, planStandardCrudFrontendModule, } from '../generators/frontend-module.js';
+export function registerFrontendModuleRecipe(register) {
+    register({
+        name: 'frontend-module',
+        kinds: [STANDARD_CRUD_KIND],
+        summary: '生成 standard-crud 前端模块作者面（manifest.ts + schema.ts）并自动接线 app/manifests.ts。',
+        usage: 'yoyo-admin create frontend-module --module <kebab> --resource <camel> --route </path> --title <标题> --permission-prefix <前缀> [--description] [--order] [--group] [--kind] [--datasource] [--virtualization fixed]',
+        options: [
+            {
+                flag: '--kind',
+                required: false,
+                description: '配方种类，缺省 standard-crud。',
+                values: [STANDARD_CRUD_KIND],
+            },
+            {
+                flag: '--module',
+                required: true,
+                description: '模块 key（kebab-case），同时作为 app 下模块目录名。',
+            },
+            {
+                flag: '--resource',
+                required: true,
+                description: '资源 key（camelCase），必须存在于生成的 CRUD resource catalog，例如 measuringUnit。',
+            },
+            {
+                flag: '--datasource',
+                required: false,
+                description: '显式指定 datasourceId；缺省为 <camel(moduleKey)>.<resourceKey>，schema 与 manifest 共用同一推导。',
+            },
+            {
+                flag: '--virtualization',
+                required: false,
+                description: '显式开启固定行虚拟化；省略时关闭，像素预算由 Data 管理。',
+                values: ['fixed'],
+            },
+            { flag: '--route', required: true, description: '路由路径，以 / 开头。' },
+            { flag: '--title', required: true, description: '页面标题。' },
+            { flag: '--description', required: false, description: '描述，缺省沿用 title。' },
+            { flag: '--order', required: false, description: '菜单排序，缺省 60。' },
+            { flag: '--group', required: false, description: '菜单分组名，缺省「业务模块」。' },
+            {
+                flag: '--permission-prefix',
+                required: true,
+                description: '权限前缀，例如 Pages.Administration.BasicData.MeasuringUnits；派生权限必须已在 capability catalog。',
+            },
+        ],
+        run: runCreateFrontendModule,
+    });
+}
+function runCreateFrontendModule(context) {
+    const datasource = optionalOption(context.parsed, '--datasource');
+    const virtualization = optionalOption(context.parsed, '--virtualization');
+    const request = {
+        moduleKey: requireOption(context.parsed, '--module'),
+        resourceKey: requireOption(context.parsed, '--resource'),
+        routePath: requireOption(context.parsed, '--route'),
+        title: requireOption(context.parsed, '--title'),
+        description: optionalOption(context.parsed, '--description') ?? requireOption(context.parsed, '--title'),
+        order: Number.parseInt(optionalOption(context.parsed, '--order') ?? '60', 10),
+        group: optionalOption(context.parsed, '--group') ?? '业务模块',
+        permissionPrefix: requireOption(context.parsed, '--permission-prefix'),
+        kind: optionalOption(context.parsed, '--kind') ?? STANDARD_CRUD_KIND,
+        ...(datasource === undefined ? {} : { datasource }),
+        ...(virtualization === undefined ? {} : { virtualization }),
+    };
+    const workspace = requireWorkspace(context);
+    const plan = planStandardCrudFrontendModule(workspace, request);
+    if (context.dryRun) {
+        return ok('create frontend-module', [
+            finding('dry-run', 'ok', '未写入任何文件。', `计划 ${plan.summary.creates} 个新文件、${plan.summary.updates} 处更新。`),
+        ], plan);
+    }
+    const report = planRunner.preflight(workspace.repoRoot, plan);
+    const written = planRunner.apply(workspace.repoRoot, plan);
+    return ok('create frontend-module', [
+        finding('created', 'ok', `已生成 ${written.length} 个文件变更。`),
+        finding('next-step', 'ok', '请在 schema.ts 中补齐展示字段（列/表单控件/查询项）；standard-crud 模块由宿主自动发现' +
+            '（schema-project-check 从 module definition registry 派生，零测试登记），' +
+            '补齐后在 admin-vue 运行 `pnpm run verify` 验证接线。', report.targets.map((target) => target.path).join('\n')),
+    ], { ...plan, written });
+}

package/dist/commands/create-package.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `create package` recipe 注册。
+ *
+ * 解析命令行参数 → 构建标准纯 TS 包骨架 FsPlan → dry-run / 事务化落盘 →
+ * 受控刷新 workspace lockfile。
+ *
+ * 闭环顺序（保证「生成后可直接干净安装」）：
+ *   1. plan 期 fail-closed（kind/目录/包名/冲突）
+ *   2. preflight 只读校验
+ *   3. 事务化落盘（返回可撤销句柄）
+ *   4. `pnpm install --lockfile-only` 补上新的 workspace importer
+ *      —— 第 4 步失败时撤销第 3 步并 fail-closed，绝不留下「文件已生成但
+ *      lockfile 没跟上」的半成品。
+ */
+import type { RegisterCreateRecipe } from './create-registry.js';
+export declare function registerPackageRecipe(register: RegisterCreateRecipe): void;
+//# sourceMappingURL=create-package.d.ts.map

package/dist/commands/create-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-package.d.ts","sourceRoot":"","sources":["../../src/commands/create-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAEhE,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAkB1E"}

package/dist/commands/create-package.js

@@ -0,0 +1,75 @@
+/**
+ * `create package` recipe 注册。
+ *
+ * 解析命令行参数 → 构建标准纯 TS 包骨架 FsPlan → dry-run / 事务化落盘 →
+ * 受控刷新 workspace lockfile。
+ *
+ * 闭环顺序（保证「生成后可直接干净安装」）：
+ *   1. plan 期 fail-closed（kind/目录/包名/冲突）
+ *   2. preflight 只读校验
+ *   3. 事务化落盘（返回可撤销句柄）
+ *   4. `pnpm install --lockfile-only` 补上新的 workspace importer
+ *      —— 第 4 步失败时撤销第 3 步并 fail-closed，绝不留下「文件已生成但
+ *      lockfile 没跟上」的半成品。
+ */
+import { requireWorkspace } from '../kernel/command.js';
+import { LOCKFILE_RELATIVE, refreshWorkspaceLockfile } from '../kernel/lockfile.js';
+import { planRunner } from '../kernel/plan-runner.js';
+import { finding, ok } from '../kernel/result.js';
+import { requireOption, optionalOption } from '../kernel/arguments.js';
+import { PACKAGE_KIND_TS, planAdminPackage } from '../generators/package.js';
+export function registerPackageRecipe(register) {
+    register({
+        name: 'package',
+        kinds: [PACKAGE_KIND_TS],
+        summary: '生成标准纯 TS 共享包骨架（package.json / tsconfig 对 / src 根入口 / smoke test / README），' +
+            `并把新包纳入 workspace 的 ${LOCKFILE_RELATIVE} importers。`,
+        usage: 'yoyo-admin create package --kind ts --name <kebab> --package-name @yoyoboot/<name> ' +
+            '[--description <text>] [--dry-run] [--json]',
+        options: [
+            { flag: '--kind', required: true, description: '配方 kind；当前仅支持标准纯 TS 包骨架。', values: [PACKAGE_KIND_TS] },
+            { flag: '--name', required: true, description: '包目录名（kebab-case），生成在 packages/yoyo-admin/ 下。' },
+            { flag: '--package-name', required: true, description: 'npm 包名，必须位于 @yoyoboot/ 作用域下。' },
+            { flag: '--description', required: false, description: '包描述，缺省「Yoyo Admin 共享包。」' },
+        ],
+        run: runCreatePackage,
+    });
+}
+function runCreatePackage(context) {
+    const request = {
+        kind: requireOption(context.parsed, '--kind'),
+        directory: requireOption(context.parsed, '--name'),
+        packageName: requireOption(context.parsed, '--package-name'),
+        description: optionalOption(context.parsed, '--description') ?? 'Yoyo Admin 共享包。',
+    };
+    const workspace = requireWorkspace(context);
+    const plan = planAdminPackage(workspace, request);
+    if (context.dryRun) {
+        return ok('create package', [
+            finding('dry-run', 'ok', '未写入任何文件。', `计划 ${plan.summary.creates} 个新文件：${plan.directory}/` +
+                `；真实执行会额外刷新 ${LOCKFILE_RELATIVE} 的 workspace importer。`),
+        ], plan);
+    }
+    planRunner.preflight(workspace.repoRoot, plan);
+    const transaction = planRunner.applyTransaction(workspace.repoRoot, plan);
+    let lockfileChanged;
+    try {
+        lockfileChanged = refreshWorkspaceLockfile(workspace.adminWorkspace, {
+            expectedImporter: request.directory,
+        }).changed;
+    }
+    catch (error) {
+        // lockfile 刷新失败 = 安装闭环不成立：撤销本次生成，保持工作树原状。
+        transaction.rollback();
+        throw error;
+    }
+    return ok('create package', [
+        finding('created', 'ok', `已生成 ${transaction.written.length} 个文件。`),
+        finding('lockfile', 'ok', lockfileChanged
+            ? `已刷新 ${LOCKFILE_RELATIVE}：新包已进入 workspace importers。`
+            : `${LOCKFILE_RELATIVE} 已包含该 importer，无需改动。`),
+        finding('next-step', 'ok', '请补齐 README 职责说明与首个真实导出，然后运行 ' +
+            `\`pnpm --dir .\\packages\\yoyo-admin install\` 链接依赖，` +
+            `再运行 \`pnpm --dir .\\packages\\yoyo-admin\\${request.directory} run package:verify\`。`),
+    ], { ...plan, written: transaction.written, lockfileChanged });
+}

package/dist/commands/create-registry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `create` 的 recipe registry。
+ *
+ * 这是 create 子命令的**单一能力事实源**：dispatch（按名分发）、
+ * capabilities（JSON 投影）、help（usage 渲染）全部从本表读取。
+ * 新增 recipe 只改本文件一处，不会出现多处漂移。
+ */
+import type { CommandContext } from '../kernel/command.js';
+import type { YoyoAdminCliResult } from '../kernel/result.js';
+export interface CreateRecipeOption {
+    readonly flag: string;
+    readonly required: boolean;
+    readonly description: string;
+    /** 取值选项的候选值（例如 `--kind` 的 profile 列表）；help 与 capabilities 共用。 */
+    readonly values?: readonly string[];
+}
+export interface CreateRecipeDefinition {
+    readonly name: string;
+    readonly kinds: readonly string[];
+    readonly summary: string;
+    readonly usage: string;
+    readonly options: readonly CreateRecipeOption[];
+    /** recipe 额外声明的布尔 flag（`options` 中的 flag 一律是取值选项）。 */
+    readonly booleanFlags?: readonly string[];
+    readonly run: (context: CommandContext) => YoyoAdminCliResult;
+}
+/** 注册函数签名；recipe 文件通过它向 registry 注册，避免直接依赖可变单例。 */
+export type RegisterCreateRecipe = (recipe: CreateRecipeDefinition) => void;
+export declare function registerCreateRecipe(recipe: CreateRecipeDefinition): void;
+export declare function resolveCreateRecipe(name: string): CreateRecipeDefinition | undefined;
+export declare function listCreateRecipes(): readonly CreateRecipeDefinition[];
+//# sourceMappingURL=create-registry.d.ts.map

package/dist/commands/create-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-registry.d.ts","sourceRoot":"","sources":["../../src/commands/create-registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAE7D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,kBAAkB,CAAA;CAC9D;AAID,mDAAmD;AACnD,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAA;AAE3E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAKzE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAEpF;AAED,wBAAgB,iBAAiB,IAAI,SAAS,sBAAsB,EAAE,CAErE"}

package/dist/commands/create-registry.js

@@ -0,0 +1,20 @@
+/**
+ * `create` 的 recipe registry。
+ *
+ * 这是 create 子命令的**单一能力事实源**：dispatch（按名分发）、
+ * capabilities（JSON 投影）、help（usage 渲染）全部从本表读取。
+ * 新增 recipe 只改本文件一处，不会出现多处漂移。
+ */
+const recipes = new Map();
+export function registerCreateRecipe(recipe) {
+    if (recipes.has(recipe.name)) {
+        throw new Error(`Create recipe '${recipe.name}' is already registered.`);
+    }
+    recipes.set(recipe.name, recipe);
+}
+export function resolveCreateRecipe(name) {
+    return recipes.get(name);
+}
+export function listCreateRecipes() {
+    return [...recipes.values()].sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/commands/create.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `yoyo-admin create <recipe>`
+ *
+ * 作者操作的统一入口。
+ *
+ * 生命周期（保证零部分写入）：
+ *   1. 构建完整 FsPlan（含新文件、接线更新）
+ *   2. preflight 只读校验全部目标
+ *   3. 全部通过后事务化落盘（失败自动回滚）
+ *
+ * `--dry-run` 在第 1 步后停止，只渲染计划。
+ *
+ * recipe 的注册表见 `create-registry.ts`：dispatch、capabilities、help、
+ * 参数校验共用，本文件不再维护手工 recipe 列表。
+ */
+import { type CommandContext } from '../kernel/command.js';
+import { type RecipeHelpSurface } from '../kernel/help.js';
+import { type YoyoAdminCliResult } from '../kernel/result.js';
+export declare function runCreate(context: CommandContext): YoyoAdminCliResult;
+/** `create` 的 help 投影面：与 inspect 共用同一套渲染器，只有"面"不同。 */
+export declare const CREATE_HELP_SURFACE: RecipeHelpSurface;
+export declare const createCommand: import("../index.js").RegisteredCommand;
+//# sourceMappingURL=create.d.ts.map

package/dist/commands/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/commands/create.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACzE,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAA0B,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAgBrF,wBAAgB,SAAS,CAAC,OAAO,EAAE,cAAc,GAAG,kBAAkB,CAYrE;AAaD,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,EAAE,iBAMjC,CAAA;AAyDD,eAAO,MAAM,aAAa,yCAaxB,CAAA"}