@yoyoboot/yoyo-admin-cli 10.5.5

package/dist/generators/frontend-module.js

@@ -0,0 +1,358 @@
+/**
+ * `yoyo-admin create frontend-module --kind standard-crud`
+ *
+ * **Contract-driven**：从生成的 CRUD resource catalog 读取该资源的完整
+ * descriptor（operations / binding），actions、权限与最小表单字段全部由
+ * 真实契约派生 —— 不猜业务事实：
+ *   - 资源没有 `remove` operation → 绝不生成 delete action / Delete 权限；
+ *   - 字段取自 `binding.create.fieldMappings[].source`（排除系统字段），
+ *     生命周期按 `binding.update.fieldMappings` 派生；
+ *     不再硬编码任何资源特定字段（v1 的 name/enabled/creationTime 已移除）；
+ *   - 表格列只含 rowKey（来自 `binding.getForEdit.idParameter`），
+ *     查询字段与展示列由作者补齐。
+ *
+ * 生成**当前正式作者面**，不多不少：
+ *   - 模块 `manifest.ts`（纯 standard-crud definition）
+ *   - feature `schema.ts`（唯一的页面契约作者面）
+ *   - 并接线 `app/manifests.ts`
+ *
+ * 明确不生成（治理裁决）：
+ *   `page-contract.ts`、通用 `service.ts`、通用 `validation.ts`、
+ *   空 `index.vue`、binding。这些属于 typed extension，
+ *   只在真实复杂业务需要时作为独立 recipe/option 增加。
+ *
+ * Plan-time fail-closed 校验：
+ *   - resourceKey 必须存在于生成的 CRUD resource catalog；
+ *   - 权限前缀派生的全部权限必须已存在于 capability catalog
+ *     （admin-vue 的 YoyoAdminPermissionKey 是类型化字面量联合，假前缀在
+ *     vue-tsc 下必然编译失败，提前到计划期 fail-closed）；
+ *   - moduleKey / pageKey / routePath 不得与既有模块重复。
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readRepoFile } from '../kernel/plan-runner.js';
+import { createFile, createFsPlan, updateFile, } from '../kernel/fs-plan.js';
+import { buildManifestsWiring, parseManifestsAnchors, renderWiredManifests, } from '../kernel/manifests-wiring.js';
+import { YoyoAdminCliUsageError } from '../kernel/result.js';
+import { loadCrudResourceDescriptor } from '../catalogs/crud.js';
+import { loadKnownPermissionNames } from '../catalogs/capability.js';
+import { deriveStandardCrudShape } from '../catalogs/standard-crud.js';
+import { ADMIN_VUE_APP_ROOT_RELATIVE, APP_MANIFESTS_RELATIVE, } from '../kernel/workspace.js';
+export const STANDARD_CRUD_KIND = 'standard-crud';
+// standard-crud 的形状派生活动在共享事实层（`catalogs/standard-crud.ts`）：
+// generator 与 `inspect resource` 用同一份逻辑，只是 generator 把
+// `eligible: false` 转成 plan-time fail-closed。这里原样再导出，保持既有消费面稳定。
+export { deriveStandardCrudShape, RUNTIME_SUPPLIED_FIELDS, } from '../catalogs/standard-crud.js';
+const KEBAB_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const CAMEL_PATTERN = /^[a-z][A-Za-z0-9]*$/;
+/** 生成合法的 TypeScript 单引号字符串字面量（转义 '/\/控制字符/行分隔符）。 */
+export function toTsStringLiteral(value) {
+    const escaped = value
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\r/g, '\\r')
+        .replace(/\n/g, '\\n')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029')
+        .replace(
+    // eslint-disable-next-line no-control-regex
+    /[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    return `'${escaped}'`;
+}
+export function validateFrontendModuleRequest(request) {
+    if (request.virtualization !== undefined && request.virtualization !== 'fixed') {
+        throw new YoyoAdminCliUsageError('unsupported-virtualization-mode', '--virtualization 仅支持 fixed；省略该参数以关闭虚拟化。');
+    }
+    if (request.kind !== STANDARD_CRUD_KIND) {
+        throw new YoyoAdminCliUsageError('unsupported-recipe-kind', `当前仅支持 --kind ${STANDARD_CRUD_KIND}；收到 ${request.kind}。` +
+            '如需 typed extension 等其他形态，请作为独立 recipe 提出，不要套用相近配方。');
+    }
+    if (!KEBAB_PATTERN.test(request.moduleKey)) {
+        throw new YoyoAdminCliUsageError('invalid-module-key', `--module 必须是 kebab-case，例如 basic-data；收到 ${request.moduleKey}。`);
+    }
+    if (!CAMEL_PATTERN.test(request.resourceKey)) {
+        throw new YoyoAdminCliUsageError('invalid-resource-key', `--resource 必须是 camelCase，与生成的 CRUD resource catalog 一致（例如 measuringUnit）；收到 ${request.resourceKey}。`);
+    }
+    if (!request.routePath.startsWith('/')) {
+        throw new YoyoAdminCliUsageError('invalid-route-path', `--route 必须以 / 开头；收到 ${request.routePath}。`);
+    }
+    if (!Number.isInteger(request.order)) {
+        throw new YoyoAdminCliUsageError('invalid-order', `--order 必须是整数；收到 ${request.order}。`);
+    }
+    if (request.permissionPrefix.length === 0) {
+        throw new YoyoAdminCliUsageError('invalid-permission-prefix', '--permission-prefix 不能为空字符串。');
+    }
+    if (request.datasource !== undefined && request.datasource.length === 0) {
+        throw new YoyoAdminCliUsageError('invalid-datasource', '--datasource 不能为空字符串。');
+    }
+}
+/** 既有的全部模块 manifest 文件（用于重复检测）。 */
+function collectExistingManifestSources(workspace) {
+    const appRoot = join(workspace.adminVueHost, 'src/app');
+    const results = [];
+    const walk = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const absolute = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                walk(absolute);
+                continue;
+            }
+            if (entry.name === 'manifest.ts') {
+                results.push({
+                    path: `${ADMIN_VUE_APP_ROOT_RELATIVE}${absolute.slice(appRoot.length).replace(/\\/g, '/')}`,
+                    content: readFileSync(absolute, 'utf8'),
+                });
+            }
+        }
+    };
+    walk(appRoot);
+    return results;
+}
+/** 对 moduleKey / pageKey / routePath 做既有清单重复检测（fail-closed）。 */
+export function assertNoDuplicates(workspace, request, pageKey) {
+    const routePattern = new RegExp(`(?:routePath|path):\\s*['"\`]${escapeRegExp(request.routePath)}['"\`]`);
+    const moduleKeyPattern = new RegExp(`moduleKey:\\s*['"\`]${escapeRegExp(request.moduleKey)}['"\`]`);
+    const pageKeyPattern = new RegExp(`['"\`]${escapeRegExp(pageKey)}['"\`]`);
+    for (const manifest of collectExistingManifestSources(workspace)) {
+        if (manifest.path === APP_MANIFESTS_RELATIVE)
+            continue;
+        if (moduleKeyPattern.test(manifest.content)) {
+            throw new YoyoAdminCliUsageError('duplicate-module-key', `moduleKey "${request.moduleKey}" 已被 ${manifest.path} 使用；拒绝生成。`);
+        }
+        if (routePattern.test(manifest.content)) {
+            throw new YoyoAdminCliUsageError('duplicate-route', `路由 "${request.routePath}" 已被 ${manifest.path} 使用；拒绝生成。`);
+        }
+        if (pageKeyPattern.test(manifest.content)) {
+            throw new YoyoAdminCliUsageError('duplicate-page-key', `pageKey "${pageKey}" 已被 ${manifest.path} 使用；拒绝生成。`);
+        }
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function camelCase(value) {
+    return value.replace(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
+}
+export function kebabCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .toLowerCase();
+}
+/** datasourceId 的唯一推导点：schema 与 manifest 共用，不可能漂移。 */
+export function datasourceIdFor(request) {
+    return request.datasource ?? `${camelCase(request.moduleKey)}.${request.resourceKey}`;
+}
+export function pageKeyFor(request) {
+    return `${request.moduleKey}-${kebabCase(request.resourceKey)}`;
+}
+export function deriveStandardCrudPermissions(permissionPrefix, shape) {
+    return {
+        page: [`${permissionPrefix}.Query`],
+        ...(shape.canCreate ? { create: `${permissionPrefix}.Create` } : {}),
+        ...(shape.canUpdate ? { update: `${permissionPrefix}.Edit` } : {}),
+        ...(shape.canSetEnabled ? { setEnabled: `${permissionPrefix}.Edit` } : {}),
+        ...(shape.canRemove ? { remove: `${permissionPrefix}.Delete` } : {}),
+    };
+}
+/** 平铺权限集合（plan-time capability catalog 校验用）。 */
+export function permissionNamesOf(permissions) {
+    return [
+        ...permissions.page,
+        ...(permissions.create === undefined ? [] : [permissions.create]),
+        ...(permissions.update === undefined ? [] : [permissions.update]),
+        ...(permissions.setEnabled === undefined ? [] : [permissions.setEnabled]),
+        ...(permissions.remove === undefined ? [] : [permissions.remove]),
+    ];
+}
+export function planStandardCrudFrontendModule(workspace, request) {
+    validateFrontendModuleRequest(request);
+    const descriptor = loadCrudResourceDescriptor(workspace.repoRoot, request.resourceKey);
+    const shape = deriveStandardCrudShape(descriptor);
+    const permissions = deriveStandardCrudPermissions(request.permissionPrefix, shape);
+    const knownPermissions = loadKnownPermissionNames(workspace.repoRoot);
+    const missingPermissions = permissionNamesOf(permissions).filter((permission) => !knownPermissions.includes(permission));
+    if (missingPermissions.length > 0) {
+        throw new YoyoAdminCliUsageError('unknown-permission-key', `权限前缀 "${request.permissionPrefix}" 派生的权限不在 capability catalog 中：` +
+            `${missingPermissions.join(', ')}。` +
+            'YoyoAdminPermissionKey 是类型化字面量联合，假前缀会导致 admin-vue vue-tsc 编译失败。' +
+            '请先在 aspnet-core 的授权 Provider 中定义这些权限，再运行 CapabilityExporter 刷新生成物。');
+    }
+    const resourceVariable = request.resourceKey.charAt(0).toLowerCase() + request.resourceKey.slice(1);
+    const featureDirectory = kebabCase(request.resourceKey);
+    const pageKey = pageKeyFor(request);
+    const datasourceId = datasourceIdFor(request);
+    assertNoDuplicates(workspace, request, pageKey);
+    const moduleDirectory = `${ADMIN_VUE_APP_ROOT_RELATIVE}/${request.moduleKey}`;
+    const manifestPath = `${moduleDirectory}/manifest.ts`;
+    const schemaPath = `${moduleDirectory}/${featureDirectory}/schema.ts`;
+    // 导出名按 moduleKey 推导：manifests.ts 显式收集纯 definition，
+    // moduleKey 唯一性已由 assertNoDuplicates 保证，标识符冲突在构造上不可能发生。
+    const manifestExportName = `${camelCase(request.moduleKey)}Definition`;
+    const schemaFactoryName = `create${request.resourceKey.charAt(0).toUpperCase()}${request.resourceKey.slice(1)}PageSchema`;
+    const changes = [
+        createFile(manifestPath, renderModuleManifest({
+            request,
+            pageKey,
+            datasourceId,
+            manifestExportName,
+            schemaFactoryName,
+            resourceVariable,
+            featureDirectory,
+            permissions,
+        }), 'frontend-module/manifest'),
+        createFile(schemaPath, renderFeatureSchema({ request, datasourceId, schemaFactoryName, shape }), 'frontend-module/schema'),
+    ];
+    const manifestsSource = readRepoFile(workspace.repoRoot, APP_MANIFESTS_RELATIVE);
+    const anchors = parseManifestsAnchors(manifestsSource, 'yCrudDefinitions');
+    const wiring = buildManifestsWiring({
+        manifestExportName,
+        importPath: `./${request.moduleKey}/manifest`,
+    });
+    const wired = renderWiredManifests(manifestsSource, anchors, wiring);
+    changes.push(updateFile(APP_MANIFESTS_RELATIVE, wired, 'frontend-module/wiring', `import ${manifestExportName} 并注册进 yCrudDefinitions`));
+    return {
+        ...createFsPlan(changes),
+        moduleKey: request.moduleKey,
+        directory: moduleDirectory,
+        pageKey,
+        datasourceId,
+        shape,
+        permissions,
+    };
+}
+function renderFeatureSchema(options) {
+    const { request, datasourceId, schemaFactoryName, shape } = options;
+    const actions = [
+        "      { key: 'refresh', kind: 'refresh', label: '刷新' },",
+        "      { key: 'reset', kind: 'reset', label: '重置' },",
+    ];
+    if (shape.canCreate)
+        actions.push("      { key: 'create', kind: 'create', label: '新增' },");
+    if (shape.canUpdate)
+        actions.push("      { key: 'edit', kind: 'edit', label: '编辑' },");
+    if (shape.canSetEnabled)
+        actions.push("      { key: 'disable', kind: 'disable', label: '切换启用状态' },");
+    if (shape.canRemove) {
+        actions.push("      { key: 'delete', kind: 'delete', label: '删除', confirmation: { intent: 'destructive' } },");
+    }
+    const formFields = shape.formFields
+        .map((field) => field.editableOn === 'both'
+        ? `        { key: ${toTsStringLiteral(field.key)}, kind: 'text', label: ${toTsStringLiteral(field.key)} },`
+        : `        { key: ${toTsStringLiteral(field.key)}, kind: 'text', label: ${toTsStringLiteral(field.key)}, lifecycle: { editableOn: 'create' } },`)
+        .join('\n');
+    return `import { defineYoyoQueryPage } from '@yoyoboot/yoyo-admin-schema'
+
+/**
+ * 页面契约的唯一作者面。
+ *
+ * 本模块由 yoyo-admin CLI 按 CRUD resource catalog 的真实契约生成：
+ * - actions 与资源 operations 一一对应（无对应 operation 的动作不会出现）；
+ * - form 字段取自 create fieldMappings（排除系统字段），生命周期按 update 契约
+ *   派生（create∩update → both；create-only → editableOn: 'create'）；
+ * - structural-ready ≠ product-content-ready：rowKey 仅是稳定记录 key；
+ *   作者必须补真实业务 identity/headline、查询项和展示列语义，CLI 不猜业务展示。
+ */
+export function ${schemaFactoryName}(pageKey: string) {
+  return defineYoyoQueryPage({
+    schemaVersion: 1,
+    pageKind: 'crud',
+    pageKey,
+    title: ${toTsStringLiteral(request.title)},
+    query: {
+      datasource: ${toTsStringLiteral(datasourceId)},
+      presentation: {
+        pageSize: 20,
+        allowedUrlParams: ['page', 'pageSize', 'sort'],
+      },
+    },
+    table: {
+      rowKey: ${toTsStringLiteral(shape.rowKey)},
+      columns: [
+        {
+          key: ${toTsStringLiteral(shape.rowKey)},
+          title: ${toTsStringLiteral(shape.rowKey)},
+          renderer: 'text',
+          sortable: false,
+          role: 'key',
+          priority: 'high',
+          mobilePlacement: 'supporting',
+        },
+      ],
+${request.virtualization === 'fixed' ? "      virtualization: { mode: 'fixed' },\n" : ''}    },
+    actions: [
+${actions.join('\n')}
+    ],
+    form: {
+      fields: [
+${formFields}
+      ],
+    },
+  })
+}
+`;
+}
+function renderModuleManifest(options) {
+    const { request, pageKey, datasourceId, manifestExportName, schemaFactoryName, resourceVariable, featureDirectory, permissions, } = options;
+    const permissionEntries = [
+        `    page: [${permissions.page.map((permission) => toTsStringLiteral(permission)).join(', ')}],`,
+    ];
+    if (permissions.create !== undefined)
+        permissionEntries.push(`    create: ${toTsStringLiteral(permissions.create)},`);
+    if (permissions.update !== undefined)
+        permissionEntries.push(`    update: ${toTsStringLiteral(permissions.update)},`);
+    if (permissions.setEnabled !== undefined)
+        permissionEntries.push(`    setEnabled: ${toTsStringLiteral(permissions.setEnabled)},`);
+    if (permissions.remove !== undefined)
+        permissionEntries.push(`    remove: ${toTsStringLiteral(permissions.remove)},`);
+    // icon 选择约束：必须同时存在于 @lucide/vue 与 admin-vue 的 vitest lucide
+    // mock 集合（tests/unit/setup/vitest.setup.ts 的 lucideIconNames），
+    // 否则接入 app 后宿主测试会因 mock 缺导出整体失败。Boxes 满足两者。
+    return `import { Boxes } from '@lucide/vue'
+import type { YCrudDefinition } from '@/shared/standard-management/definition'
+import { ${schemaFactoryName} } from './${featureDirectory}/schema'
+
+const ${resourceVariable}PageKey = ${toTsStringLiteral(pageKey)}
+
+export const ${manifestExportName} = {
+  moduleKey: ${toTsStringLiteral(request.moduleKey)},
+  schemaSourcePath: ${toTsStringLiteral(`app/${request.moduleKey}/${featureDirectory}/schema.ts`)},
+  pageKey: ${resourceVariable}PageKey,
+  resourceKey: ${toTsStringLiteral(request.resourceKey)},
+  datasourceId: ${toTsStringLiteral(datasourceId)},
+  routePath: ${toTsStringLiteral(request.routePath)},
+  title: ${toTsStringLiteral(request.title)},
+  description: ${toTsStringLiteral(request.description)},
+  order: ${request.order},
+  schema: ${schemaFactoryName}(${resourceVariable}PageKey),
+  menu: {
+    group: ${toTsStringLiteral(request.group)},
+    description: ${toTsStringLiteral(request.description)},
+    icon: Boxes,
+    badge: 'standard',
+  },
+  page: {
+    description: ${toTsStringLiteral(request.description)},
+  },
+  permissions: {
+${permissionEntries.join('\n')}
+  },
+  presentation: {
+    eyebrow: ${toTsStringLiteral(request.group)},
+    description: ${toTsStringLiteral(request.description)},
+    editorDescription: ${toTsStringLiteral(request.description)},
+    loadErrorMessage: ${toTsStringLiteral(`${request.title}加载失败，请重试。`)},
+    headerStatusTestId: \`\${${resourceVariable}PageKey}__header-status\`,
+    feedbackMessage: (event) => event.outcome === 'success'
+      ? event.operation === 'softDelete'
+        ? ${toTsStringLiteral(`${request.title}已删除。`)}
+        : event.operation === 'setEnabled'
+          ? ${toTsStringLiteral(`${request.title}状态已更新。`)}
+          : ${toTsStringLiteral(`${request.title}已保存。`)}
+      : event.message,
+    // 中性删除文案：不引用行业务字段（字段名由各资源的 schema 作者决定）。
+    deleteDescription: () => ${toTsStringLiteral('确认删除该条目吗？删除后该条目将不再出现在正常列表中。')},
+  },
+} satisfies YCrudDefinition
+`;
+}

package/dist/generators/package.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `yoyo-admin create package --kind ts`
+ *
+ * 在 `packages/yoyo-admin/` 下生成一个**标准纯 TypeScript 私有包骨架**。
+ *
+ * 只承诺骨架本身：package.json / tsconfig 对 / src 根入口 / 一个真实可跑的
+ * smoke test / README。**不声称与 admin-core / admin-schema / admin-kit
+ * 「完全同构」**——这三个包的职责、边界与验证项由各自 README/AGENTS 拥有，
+ * 骨架不复制也不暗示它们。
+ *
+ * 生成物必须 fresh-create 后**直接通过自己的 `package:verify`**，因此
+ * `tests/` 里会落一个真实的最小 smoke test（`vitest run` 无测试文件会失败，
+ * 不能用降低 test gate 的方式绕过）。
+ *
+ * Plan-time fail-closed：kind / 目录名 / 包名 / 描述 / 目录冲突 / 包名冲突
+ * 全部在计划期拒绝，重复执行必然 exit 2。
+ */
+import { type FsPlan } from '../kernel/fs-plan.js';
+import { type YoyoAdminWorkspace } from '../kernel/workspace.js';
+/** 当前唯一支持的 package profile。 */
+export declare const PACKAGE_KIND_TS = "ts";
+export interface PackageRequest {
+    /** 配方 kind；当前仅支持 `ts`。 */
+    readonly kind: string;
+    /** 包目录名，例如 admin-runtime。 */
+    readonly directory: string;
+    /** npm 包名，例如 @yoyoboot/yoyo-admin-runtime。 */
+    readonly packageName: string;
+    readonly description: string;
+}
+export declare function validatePackageRequest(request: PackageRequest): void;
+/**
+ * 目录与包名冲突检测：两者都在 plan 期 fail-closed，重复执行必然被拒绝。
+ *
+ * 包名冲突的作用域 = workspace 的全部 importer（根 + 直接子目录），
+ * 因为 `pnpm-workspace.yaml` 把 `'.'` 与 `'./*'` 都算作 workspace 成员。
+ */
+export declare function assertNoPackageConflicts(workspace: YoyoAdminWorkspace, request: PackageRequest): void;
+export interface PackagePlan extends FsPlan {
+    readonly kind: typeof PACKAGE_KIND_TS;
+    /** 仓库根相对目录，例如 packages/yoyo-admin/admin-runtime。 */
+    readonly directory: string;
+    readonly packageName: string;
+}
+export declare function planAdminPackage(workspace: YoyoAdminWorkspace, request: PackageRequest): PackagePlan;
+//# sourceMappingURL=package.d.ts.map

package/dist/generators/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/generators/package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EAA4B,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAE5E,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAE1F,+BAA+B;AAC/B,eAAO,MAAM,eAAe,OAAO,CAAA;AAKnC,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6BAA6B;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAkCpE;AAwDD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,kBAAkB,EAC7B,OAAO,EAAE,cAAc,GACtB,IAAI,CAiBN;AAED,MAAM,WAAW,WAAY,SAAQ,MAAM;IACzC,QAAQ,CAAC,IAAI,EAAE,OAAO,eAAe,CAAA;IACrC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,kBAAkB,EAC7B,OAAO,EAAE,cAAc,GACtB,WAAW,CA2Bb"}

package/dist/generators/package.js

@@ -0,0 +1,230 @@
+/**
+ * `yoyo-admin create package --kind ts`
+ *
+ * 在 `packages/yoyo-admin/` 下生成一个**标准纯 TypeScript 私有包骨架**。
+ *
+ * 只承诺骨架本身：package.json / tsconfig 对 / src 根入口 / 一个真实可跑的
+ * smoke test / README。**不声称与 admin-core / admin-schema / admin-kit
+ * 「完全同构」**——这三个包的职责、边界与验证项由各自 README/AGENTS 拥有，
+ * 骨架不复制也不暗示它们。
+ *
+ * 生成物必须 fresh-create 后**直接通过自己的 `package:verify`**，因此
+ * `tests/` 里会落一个真实的最小 smoke test（`vitest run` 无测试文件会失败，
+ * 不能用降低 test gate 的方式绕过）。
+ *
+ * Plan-time fail-closed：kind / 目录名 / 包名 / 描述 / 目录冲突 / 包名冲突
+ * 全部在计划期拒绝，重复执行必然 exit 2。
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createFile, createFsPlan } from '../kernel/fs-plan.js';
+import { YoyoAdminCliUsageError } from '../kernel/result.js';
+import { ADMIN_WORKSPACE_RELATIVE } from '../kernel/workspace.js';
+/** 当前唯一支持的 package profile。 */
+export const PACKAGE_KIND_TS = 'ts';
+const PACKAGE_DIRECTORY_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const PACKAGE_NAME_PATTERN = /^@yoyoboot\/[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+export function validatePackageRequest(request) {
+    if (request.kind !== PACKAGE_KIND_TS) {
+        throw new YoyoAdminCliUsageError('unsupported-recipe-kind', `create package 目前仅支持 --kind ${PACKAGE_KIND_TS}（标准纯 TS 包骨架）；收到 ${request.kind}。` +
+            '其他包形态请作为独立 recipe 提出，不要套用相近配方。');
+    }
+    if (!PACKAGE_DIRECTORY_PATTERN.test(request.directory)) {
+        throw new YoyoAdminCliUsageError('invalid-package-directory', `包目录名必须是 kebab-case（例如 admin-runtime）；收到 ${request.directory}。`);
+    }
+    if (!PACKAGE_NAME_PATTERN.test(request.packageName)) {
+        throw new YoyoAdminCliUsageError('invalid-package-name', `包名必须是 @yoyoboot/<kebab-case>（例如 @yoyoboot/yoyo-admin-runtime）；收到 ${request.packageName}。`);
+    }
+    if (request.description.trim().length === 0) {
+        throw new YoyoAdminCliUsageError('invalid-package-description', '--description 不能是空字符串。');
+    }
+    // 描述会同时进入 package.json 与 README：控制字符/换行会破坏生成物结构，plan 期拒绝。
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001F\u007F]/.test(request.description)) {
+        throw new YoyoAdminCliUsageError('invalid-package-description', '--description 不能包含换行或控制字符。');
+    }
+}
+/**
+ * 读取 workspace 内既有的 importer 包名：`packages/yoyo-admin/package.json` 本身
+ * （`pnpm-workspace.yaml` 明确包含 `'.'`）以及它的每一个直接子目录。
+ * manifest 不可解析/缺 name 一律 fail-closed —— 无法确认无冲突就不许生成。
+ */
+function collectExistingPackages(workspace) {
+    const candidates = [
+        {
+            manifestPath: join(workspace.adminWorkspace, 'package.json'),
+            location: `${ADMIN_WORKSPACE_RELATIVE}（workspace 根）`,
+        },
+        ...readdirSync(workspace.adminWorkspace, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => ({
+            manifestPath: join(workspace.adminWorkspace, entry.name, 'package.json'),
+            location: `${ADMIN_WORKSPACE_RELATIVE}/${entry.name}`,
+        })),
+    ];
+    const results = [];
+    for (const candidate of candidates) {
+        if (!existsSync(candidate.manifestPath))
+            continue;
+        let manifest;
+        try {
+            manifest = JSON.parse(readFileSync(candidate.manifestPath, 'utf8'));
+        }
+        catch (error) {
+            throw new YoyoAdminCliUsageError('package-manifest-unreadable', `${candidate.location}/package.json 无法解析，` +
+                `无法确认包名是否冲突；请先修复该 manifest。（${error instanceof Error ? error.message : String(error)}）`);
+        }
+        if (typeof manifest.name !== 'string' || manifest.name.length === 0) {
+            throw new YoyoAdminCliUsageError('package-manifest-unreadable', `${candidate.location}/package.json 缺少 name，无法确认包名是否冲突。`);
+        }
+        results.push({ location: candidate.location, packageName: manifest.name });
+    }
+    return results;
+}
+/**
+ * 目录与包名冲突检测：两者都在 plan 期 fail-closed，重复执行必然被拒绝。
+ *
+ * 包名冲突的作用域 = workspace 的全部 importer（根 + 直接子目录），
+ * 因为 `pnpm-workspace.yaml` 把 `'.'` 与 `'./*'` 都算作 workspace 成员。
+ */
+export function assertNoPackageConflicts(workspace, request) {
+    if (existsSync(join(workspace.adminWorkspace, request.directory))) {
+        throw new YoyoAdminCliUsageError('package-directory-exists', `目录已存在，拒绝覆盖：${ADMIN_WORKSPACE_RELATIVE}/${request.directory}。`);
+    }
+    const conflict = collectExistingPackages(workspace).find((existing) => existing.packageName === request.packageName);
+    if (conflict !== undefined) {
+        throw new YoyoAdminCliUsageError('duplicate-package-name', `包名 ${request.packageName} 已被 ${conflict.location} 使用；拒绝生成。`);
+    }
+}
+export function planAdminPackage(workspace, request) {
+    validatePackageRequest(request);
+    assertNoPackageConflicts(workspace, request);
+    const base = `${ADMIN_WORKSPACE_RELATIVE}/${request.directory}`;
+    return {
+        ...createFsPlan([
+            createFile(`${base}/package.json`, renderPackageJson(request), 'package/package.json'),
+            createFile(`${base}/tsconfig.json`, renderTsconfig(), 'package/tsconfig.json'),
+            createFile(`${base}/tsconfig.build.json`, renderTsconfigBuild(), 'package/tsconfig.build.json'),
+            createFile(`${base}/src/index.ts`, renderIndex(request), 'package/src/index.ts'),
+            createFile(`${base}/tests/index.spec.ts`, renderSmokeTest(request), 'package/tests/index.spec.ts'),
+            createFile(`${base}/README.md`, renderReadme(request), 'package/README.md'),
+        ]),
+        kind: PACKAGE_KIND_TS,
+        directory: base,
+        packageName: request.packageName,
+    };
+}
+function renderPackageJson(request) {
+    return `${JSON.stringify({
+        name: request.packageName,
+        private: true,
+        version: '0.0.0-private',
+        type: 'module',
+        description: request.description,
+        files: ['dist'],
+        exports: {
+            '.': {
+                types: './dist/index.d.ts',
+                import: './dist/index.js',
+            },
+        },
+        types: './dist/index.d.ts',
+        scripts: {
+            build: 'tsc -p ./tsconfig.build.json',
+            typecheck: 'tsc -p ./tsconfig.json --noEmit',
+            'test:run': 'vitest run',
+            'package:verify': 'pnpm run typecheck && pnpm run test:run && pnpm run build',
+        },
+        devDependencies: {
+            '@types/node': '^24.13.2',
+            typescript: '^6.0.2',
+            vitest: '^4.1.10',
+        },
+        packageManager: 'pnpm@11.28.0',
+    }, null, 2)}\n`;
+}
+function renderTsconfig() {
+    return `${JSON.stringify({
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'ESNext',
+            moduleResolution: 'Bundler',
+            strict: true,
+            exactOptionalPropertyTypes: true,
+            noUncheckedIndexedAccess: true,
+            noEmit: true,
+            skipLibCheck: true,
+            ignoreDeprecations: '6.0',
+            lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+            baseUrl: '.',
+            types: ['vitest/globals', 'node'],
+        },
+        include: ['src/**/*.ts', 'tests/**/*.ts'],
+    }, null, 2)}\n`;
+}
+function renderTsconfigBuild() {
+    return `${JSON.stringify({
+        extends: './tsconfig.json',
+        compilerOptions: {
+            noEmit: false,
+            declaration: true,
+            declarationMap: true,
+            emitDeclarationOnly: false,
+            outDir: 'dist',
+            rootDir: 'src',
+        },
+        include: ['src/**/*.ts'],
+    }, null, 2)}\n`;
+}
+function renderIndex(request) {
+    return `/**
+ * 包根入口。
+ *
+ * 只从根入口导出稳定 API；内部实现不构成契约。
+ * 不要在此处使用 \`export *\` 泄漏内部目录。
+ */
+
+/**
+ * 包身份。
+ *
+ * 这是骨架里唯一的真实导出：它让 \`tests/index.spec.ts\` 成为可执行的真实断言
+ * （而不是空占位），保证 fresh-create 后 \`package:verify\` 直接通过。
+ * 首个业务导出落地后，可以连同 smoke test 一起替换成真正的契约断言。
+ */
+export const packageName = '${request.packageName}'
+`;
+}
+function renderSmokeTest(request) {
+    return `import { describe, expect, it } from 'vitest'
+
+import { packageName } from '../src/index.js'
+
+describe('${request.packageName} skeleton', () => {
+  it('exposes its package identity through the root entry', () => {
+    expect(packageName).toBe('${request.packageName}')
+  })
+})
+`;
+}
+function renderReadme(request) {
+    return `# ${request.packageName}
+
+${request.description}
+
+## 职责
+
+（待补充：本包拥有什么、不拥有什么。）
+
+## 边界
+
+本骨架是标准的纯 TypeScript 私有包：\`src/\` 只通过包根入口导出稳定 API，
+\`tests/\` 由 vitest 执行。它不声称与 \`admin-core\` / \`admin-schema\` /
+\`admin-kit\` 同构——职责、依赖边界与验证项由作者按真实需要补齐。
+
+## 验证
+
+\`\`\`powershell
+pnpm --dir .\\${ADMIN_WORKSPACE_RELATIVE.replace(/\//g, '\\')}\\${request.directory} run package:verify
+\`\`\`
+`;
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@yoyoboot/yoyo-admin-cli` 包根入口。
+ *
+ * 对外暴露 CLI kernel 的稳定面，供测试与工具复用。
+ * 可执行入口是 `dist/bin.js`（见 package.json 的 bin 字段）。
+ */
+export { runCli, createRegistry, EXIT_OK, EXIT_UNEXPECTED, EXIT_USAGE, type RunCliOptions } from './cli.js';
+export { defineCommand, dispatch, requireWorkspace, YoyoAdminCliRegistry, createCommandContext, type CommandContext, type DispatchOptions, type DispatchOutcome, type RegisteredCommand, } from './kernel/command.js';
+export { GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_OPTIONS, globalArgumentSpec, hasFlag, mergeArgumentSpecs, optionalOption, parseArguments, requireOption, requirePositional, type ArgumentSpec, type ParsedArguments, } from './kernel/arguments.js';
+export { helpPayload, isHelpPayload, renderCommandHelp, renderRecipeHelp, renderRecipeListHelp, renderRootHelp, type HelpPayload, type HelpRecipeDescriptor, type RecipeHelpSurface, } from './kernel/help.js';
+export { assertConfinedRelativePath, createFile, createFsPlan, isFsPlan, normalizePath, updateFile, type CreateFileChange, type FsChange, type FsPlan, type UpdateFileChange, } from './kernel/fs-plan.js';
+export { applyFsPlan, applyFsPlanTransaction, confineRepoPath, planRunner, preflightFsPlan, readRepoFile, type AppliedFsPlan, type PlanPreflightReport, } from './kernel/plan-runner.js';
+export { LOCKFILE_REFRESH_ARGS, LOCKFILE_RELATIVE, lockfileHasImporter, refreshWorkspaceLockfile, type LockfileRefreshOptions, type LockfileRefreshOutcome, type PnpmRunResult, type PnpmRunner, } from './kernel/lockfile.js';
+export { assertWiringIsSafe, buildManifestsWiring, parseManifestsAnchors, renderWiredManifests, type ManifestsFileAnchors, type ManifestsWiringRequest, } from './kernel/manifests-wiring.js';
+export { finding, failure, hasError, ok, warn, YoyoAdminCliUsageError, type YoyoAdminCliCommandDescriptor, type YoyoAdminCliFinding, type YoyoAdminCliResult, type YoyoAdminCliStatus, } from './kernel/result.js';
+export { ADMIN_VUE_APP_ROOT_RELATIVE, ADMIN_VUE_HOST_RELATIVE, ADMIN_WORKSPACE_RELATIVE, APP_MANIFESTS_RELATIVE, REQUIRED_REPO_MARKERS, findRepoRoot, resolveWorkspace, type YoyoAdminWorkspace, } from './kernel/workspace.js';
+export { runDoctor, MINIMUM_NODE_MAJOR } from './commands/doctor.js';
+export { buildCapabilities, CAPABILITIES_SCHEMA_VERSION, type CapabilitiesPayload } from './commands/capabilities.js';
+export { inspectCommand, isInspectPayload, listInspectSubjects, renderInspectPayload, resolveInspectSubject, runInspect, type InspectPayload, type InspectPermissionPayload, type InspectPermissionsPayload, type InspectResourcePayload, type InspectResourcesPayload, type InspectSubject, } from './commands/inspect.js';
+export { CRUD_CATALOG_RELATIVE, loadCrudCatalog, loadCrudResourceDescriptor, loadCrudResourceDescriptors, loadKnownResourceKeys, type CrudCatalogDocument, type CrudFieldMapping, type CrudResourceDescriptor, } from './catalogs/crud.js';
+export { CAPABILITY_CATALOG_RELATIVE, loadCapabilityCatalog, loadKnownPermissionNames, loadPermissionDescriptor, matchPermissionPrefix, type CapabilityCatalogDocument, type CapabilityFeatureDescriptor, type CapabilityPermissionDescriptor, } from './catalogs/capability.js';
+export { deriveStandardCrudCompatibility, deriveStandardCrudShape, RUNTIME_SUPPLIED_FIELDS, type StandardCrudCompatibility, type StandardCrudShape, type StandardCrudShapeField, } from './catalogs/standard-crud.js';
+export { type CatalogSource } from './catalogs/source.js';
+export { planStandardCrudFrontendModule, validateFrontendModuleRequest, STANDARD_CRUD_KIND, type FrontendModulePlan, type FrontendModuleRequest, } from './generators/frontend-module.js';
+export { assertNoPackageConflicts, planAdminPackage, validatePackageRequest, PACKAGE_KIND_TS, type PackagePlan, type PackageRequest, } from './generators/package.js';
+//# sourceMappingURL=index.d.ts.map