@james_sww/metaform-asset-distribution 0.1.3 → 0.1.4

package/README.md

@@ -2,14 +2,44 @@
 
 这个包提供源码资产 CLI，并携带独立 `@james_sww/metaform-codebase-template` 的版本快照。基础模板工程与外壳维护源是独立 `metaform-codebase/`；其中基础 UI、主题和语义骨架按明确来源派生，不建立第二份人工维护源。业务组件按需复制，源码归应用维护；生成工程不依赖 Metaform workspace 或该 CLI 才能运行。
 
-本版为 `0.1.3`，包含当前组件装配流程、模板区域边界、层级导航，模板不携带历史资产源码副本。资产源码及 CLI 已独立迁入 `metaform-asset-library`；本轮仅分发两个岗位任务组件、语义骨架及真实依赖，外壳随模板交付。
+本版为 `0.1.4`，包含当前组件装配流程、模板区域边界、层级导航，模板不携带历史资产源码副本。资产源码及 CLI 已独立迁入 `metaform-asset-library`。当前源码的 `prepare:release` 会将已验证的各来源资产统一登记到发行中；外壳仍随模板交付。CLI 发行与线上 MCP 分别更新；远程版本与验证结果以发行记录为准。
+
+## 统一 add 入口
+
+通过 `search` 和 `inspect` 确认组件后，统一使用 `add` 或 `plan add`，无需根据来源切换命令：
+
+```sh
+metaform-assets add shadcn.accordion
+metaform-assets add accordion
+metaform-assets add tremor.accordion
+metaform-assets add quality.inspection-evidence-workspace
+metaform-assets add npm.react-flow
+metaform-assets inspect shadcn.button#radix --json
+metaform-assets plan add shadcn.button --variant radix --json
+```
+
+短名称优先选择同名 shadcn 条目；其他来源请使用完整 ID。有多个实现时默认选择 `current`、`new-york-v4`、`raw` 或 `package`，可通过 `ID#variant` 或 `--variant` 明确指定；歧义、未知变体和不支持的条目会报错。
+
+`inspect` 的 `installation` 返回交付方式、实际入口、原始版本和适配要求：
+
+| mode | add 的结果 |
+| --- | --- |
+| `component` | 写入组件源码和依赖。Metaform 通用组件使用应用源码目录；shadcn 与 Tremor 使用 `src/components/vendor/` 下独立目录，改写本地导入，保留许可证。 |
+| `reference` | 业务源码写入 `references/metaform/`，保留原始内容，不注入其运行依赖或自动挂载。AI 根据当前应用本体取用、组合或改写。 |
+| `package` | 添加固定 npm 依赖并保留来源资料。运行时样式、容器和业务数据由应用接入。 |
+
+已有三个 Metaform 发行入口仍使用原路径。新增条目的来源与文件摘要记录于 `references/manifests/`、`assets.lock.json` 和原有基线目录。`installable=true` 表示此发行能按声明方式交付，不代表业务已接通或无需视觉适配。Tremor 需要旧版 API 时使用固定 npm 别名依赖，避免替换宿主已有日历或图表版本。
+
+源码缺失、未解析导入或需要上游专用转换器的条目保留在目录中，`installation.supported=false` 给出具体 `reason/details`；执行 `add` 时拒绝写入。`official add` 仅保留为兼容命令，仍调用独立官方工具；统一入口消费固定发行，不因某条目不支持而自动改用在线最新源码。
+
+资源刷新脚本会将同一发行的 `metadata.installation`、`installId`、摘要和安装资格同步到资源目录，保留原始 reference 字节与交付方式。MCP 消费固定快照，须另行刷新、验证并部署后才会显示新状态；本地 CLI 打包不会自动更新线上服务。
 
 ## npm 使用与沙箱接入
 
 发布版本使用 Node 24.18.0、pnpm 10.18.2。CLI 自带固定版本模板与源码 Registry，无需平台仓库或本机桌面目录。私有包需有下载权限；沙箱凭据由运行环境注入，不写入应用源码。
 
 ```sh
-npm install -g @james_sww/metaform-asset-distribution@0.1.3
+npm install -g @james_sww/metaform-asset-distribution@0.1.4
 metaform-assets init --project ./my-app
 cd my-app
 corepack pnpm install --frozen-lockfile
@@ -18,7 +48,7 @@ corepack pnpm install --frozen-lockfile
 不安装全局工具也可运行：
 
 ```sh
-npm exec --yes --package=@james_sww/metaform-asset-distribution@0.1.3 -- metaform-assets init --project ./my-app
+npm exec --yes --package=@james_sww/metaform-asset-distribution@0.1.4 -- metaform-assets init --project ./my-app
 ```
 
 Agent 根据应用本体和 skill 形成 `ApplicationDesign` JSON 后，在已初始化的应用目录执行：
@@ -53,7 +83,7 @@ pack 前从独立基础模板包生成 `codebase/` 快照，再生成 CLI 和资
 
 `registry/<digest>/registry.json`、`r/*.json` 遵守 shadcn Registry schema；`release.json` 是 Metaform 的原始字节和来源 sidecar。schema 校验 fixture 来自 [官方 registry-item schema](https://ui.shadcn.com/schema/registry-item.json)，2026-10-17 固定入库。Catalog 分开保留 component 与 asset 两种粒度，候选不会自动变成推荐。可发现但不在首批源码范围内的条目显示 `installable: false`。
 
-当前可安装资产：quality.role-task-overview、quality.role-task-groups、common.semantic-region-scaffold，以及真实传递依赖。外壳仅由 Code Base 提供，不作为业务资产安装。不猜测任意资产或 npm 版本。所有直接、重导出、字面量动态 import 使用 AST 改写为应用内相对路径；UI aliases 由应用自由配置。未枚举动态 import、未知 npm 依赖、越界路径、软链接、同目标所有权冲突均拒绝。标准 Registry 本轮只接收 UTF-8；二进制资源明确报错。
+`source-map.ts` 保留 quality.role-task-overview、quality.role-task-groups、common.semantic-region-scaffold 三个既有发行入口及其依赖；其余来源由资源适配层生成相同格式的安装条目，共享原有计划和事务写入器。外壳仅由 Code Base 提供，不作为业务资产安装。不猜测任意资产或 npm 版本。组件源码的直接、重导出、字面量动态 import 使用 AST 改写；参考资料保留原始字节。未枚举动态 import、未知 npm 依赖、越界路径、软链接、同目标所有权冲突均拒绝。标准 Registry 只接收 UTF-8；二进制资源明确报错。
 
 ## 独立应用使用
 
@@ -68,7 +98,7 @@ metaform-assets search 岗位任务 --json
 metaform-assets inspect quality.role-task-groups --json
 metaform-assets plan add quality.role-task-overview quality.role-task-groups --json > /tmp/metaform-assets-plan.json
 metaform-assets add --plan /tmp/metaform-assets-plan.json
-metaform-assets official add accordion
+metaform-assets add shadcn.accordion
 metaform-assets reconcile
 metaform-assets diff
 metaform-assets doctor --recover

package/dist/application-source.js

@@ -88,7 +88,7 @@ import { RoleWorkspaceShell } from '../../layouts/role-workspace-shell';
 import { RegionSlot } from '../../platform/region/region-slot';
 import { activeWorkspaceRoute, resolveWorkspacePage, workspaceRouteContract, type WorkspaceRouteMap } from '../../workspace/routes';
 ${regions.map((r, i) => `import { Region as Region${i}, contract as contract${i} } from './regions/${r.contract.id}';`).join("\n")}
-const pages = ${literal(pages)};
+const pages = ${literal(pages.map((page) => ({ ...page, menu: page.menu ?? true })))};
 const workspaceRoutes: WorkspaceRouteMap = ${literal(role.workspaceRoutes ?? {})};
 const mappedPages = new Set(Object.values(workspaceRoutes));
 const regions = { ${regions.map((r, i) => `${literal(r.contract.id)}: { View: Region${i}, contract: contract${i} }`).join(",")} };

package/dist/asset-selection.d.ts

@@ -0,0 +1,3 @@
+import { type CatalogRecord, type RegistryRelease } from './contracts.js';
+export declare function selectRecord(release: RegistryRelease, identity: string, variant?: string): CatalogRecord | undefined;
+export declare function selectInstallItem(release: RegistryRelease, identity: string, variant?: string): import("./contracts.js").SourceItem;

package/dist/asset-selection.js

@@ -0,0 +1,37 @@
+import { DistributionError } from './contracts.js';
+export function selectRecord(release, identity, variant) {
+    const [id, suffix, extra] = identity.split('#');
+    if (extra !== undefined || !id || suffix === '' || (suffix && variant && suffix !== variant))
+        throw new DistributionError('invalid_asset_identity', [identity]);
+    const selectedVariant = suffix ?? variant;
+    const all = [...release.catalog?.components ?? [], ...release.catalog?.assets ?? []];
+    let matches = all.filter(entry => entry.id === id && (!selectedVariant || entry.variant === selectedVariant));
+    if (!matches.length && !id.includes('.')) {
+        matches = all.filter(entry => (entry.name === id || entry.id === `shadcn.${id}`) && (!selectedVariant || entry.variant === selectedVariant));
+        const official = matches.filter(entry => entry.id === `shadcn.${id}`);
+        if (official.length)
+            matches = official;
+    }
+    const ids = new Set(matches.map(entry => entry.id));
+    if (ids.size > 1)
+        throw new DistributionError('ambiguous_asset', [...ids]);
+    if (!selectedVariant)
+        for (const preferred of ['current', 'new-york-v4', 'raw', 'package']) {
+            const entry = matches.find(entry => entry.variant === preferred);
+            if (entry)
+                return entry;
+        }
+    const variants = new Set(matches.map(entry => entry.variant));
+    if (variants.size > 1)
+        throw new DistributionError('ambiguous_variant', [identity]);
+    return matches[0];
+}
+export function selectInstallItem(release, identity, variant) {
+    const entry = selectRecord(release, identity, variant);
+    if (entry?.installation?.supported === false)
+        throw new DistributionError(entry.installation.reason ?? 'asset_not_installable', [identity, ...entry.installation.details ?? []]);
+    const item = release.items.find(item => item.assetId === (entry?.installId ?? identity));
+    if (!item || (variant && !entry))
+        throw new DistributionError('asset_not_installable', [identity]);
+    return item;
+}

package/dist/cli.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { applyPlan, recoverInstall, retainedInstallBackups } from './apply.js';
+import { selectInstallItem, selectRecord } from './asset-selection.js';
 import { installDependencies } from './commands.js';
 import { DistributionError } from './contracts.js';
 import { runOfficialAdd } from './official.js';
@@ -52,6 +53,7 @@ export async function runCLI(argv, io) {
             'plan',
             'expect-digest',
             'design',
+            'variant',
         ]);
         for (let i = 0; i < argv.length; i++) {
             const arg = argv[i];
@@ -90,6 +92,7 @@ export async function runCLI(argv, io) {
                     '--codebase <template-package-directory> (init)',
                     '--registry <release.json|https URL>',
                     '--json',
+                    '--variant <variant> (also accepts id#variant)',
                     '--no-install (source only; run pnpm install afterwards)',
                 ],
             };
@@ -154,28 +157,33 @@ export async function runCLI(argv, io) {
                         version: i.version,
                         name: i.exports?.join(',') ?? i.assetId,
                         description: i.description ?? i.assetId,
+                        sourceEntry: i.contractRef,
                         maturity: i.maturity,
                     }));
                 output = {
                     components: components.filter(match).map((c) => ({
                         ...c,
-                        installable: release.items.some((i) => i.assetId === c.id),
+                        installable: c.installation?.supported !== false && release.items.some((i) => i.assetId === (c.installId ?? c.id)),
                         matchedBy: query ? 'catalog-text' : 'all',
                     })),
                     assets: (release.catalog?.assets ?? []).filter(match).map((a) => ({
                         ...a,
-                        installable: release.items.some((i) => i.assetId === a.id),
+                        installable: a.installation?.supported !== false && release.items.some((i) => i.assetId === (a.installId ?? a.id)),
                         matchedBy: query ? 'catalog-text' : 'all',
                     })),
                 };
             }
             else if (cmd === 'inspect') {
-                const id = words[0], item = release.items.find((i) => i.assetId === id);
+                const selected = selectRecord(release, words[0], options.get('variant'));
+                if (!selected && (options.has('variant') || words[0]?.includes('#')))
+                    throw new DistributionError('unknown_asset_variant', [words[0]]);
+                const id = selected?.id ?? words[0], item = release.items.find((i) => i.assetId === (selected?.installId ?? id));
                 const components = release.catalog?.components.filter((c) => c.id === id) ?? [], assets = release.catalog?.assets.filter((a) => a.id === id) ?? [];
                 if (!item && !components.length && !assets.length)
                     throw new DistributionError('unknown_asset', [id]);
                 output = {
                     item,
+                    installation: selected?.installation ?? item?.installation,
                     components,
                     assets,
                     sources: item
@@ -203,8 +211,8 @@ export async function runCLI(argv, io) {
                     throw new DistributionError('assets_required');
                 const assets = words.map((word) => {
                     const [id, version] = word.split('@');
-                    const item = release.items.find((i) => i.assetId === id);
-                    return { id, version: version ?? item?.version ?? '' };
+                    const item = selectInstallItem(release, id, options.get('variant'));
+                    return { id: item.assetId, version: version ?? item.version };
                 });
                 const plan = await planAdd({ projectRoot: root, release, assets });
                 output =

package/dist/contracts.d.ts

@@ -29,6 +29,19 @@ export type SourceItem = {
     exports?: string[];
     events?: string[];
     states?: string[];
+    installation?: InstallationInfo;
+};
+export type InstallationInfo = {
+    supported: boolean;
+    mode?: 'component' | 'reference' | 'package';
+    source?: string;
+    variant?: string;
+    upstreamVersion?: string;
+    adaptation?: string[];
+    reason?: string;
+    details?: string[];
+    entry?: string;
+    declaredDependencies?: Record<string, string>;
 };
 export type RegistryRelease = {
     schemaVersion: 1;
@@ -57,6 +70,10 @@ export type CatalogRecord = {
     exports?: string[];
     events?: string[];
     states?: string[];
+    source?: string;
+    variant?: string;
+    installId?: string;
+    installation?: InstallationInfo;
 };
 export type CatalogSnapshot = {
     components: CatalogRecord[];
@@ -65,6 +82,7 @@ export type CatalogSnapshot = {
 export type InstalledAsset = AssetRef & {
     releaseDigest: string;
     files: Record<string, string>;
+    installation?: InstallationInfo;
 };
 export type AssetLock = {
     schemaVersion: 1;

package/dist/planner.js

@@ -31,6 +31,7 @@ export async function planAdd(input) {
             version: item.version,
             releaseDigest: release.digest,
             files: {},
+            ...(item.installation ? { installation: item.installation } : {}),
         };
         // 路径迁移也是升级：先验证全部旧基线，禁止静默丢弃旧文件所有权。
         for (const [path, hash] of Object.entries(installed?.files ?? {})) {

package/dist/validate.js

@@ -151,7 +151,7 @@ export function validateRelease(value) {
         for (const [name, version] of Object.entries(item.npmDependencies)) {
             if (!/^(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(name) ||
                 typeof version !== 'string' ||
-                !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(version))
+                !/^(?:npm:(?:@[a-z0-9._-]+\/)?[a-z0-9._-]+@)?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(version))
                 throw new DistributionError('unsafe_dependency', [name]);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@james_sww/metaform-asset-distribution",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "bin": {
     "metaform-assets": "./dist/bin.js"