@tbox.cn/app-toolkit 0.1.0

package/src/assembly/walk-manifests.ts

@@ -0,0 +1,461 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { FileCache } from '../core/file-cache.js';
+import { parseModuleDescriptor, type ModuleDescriptor, type ProviderSlotContrib } from '../core/module-schema.js';
+import { readAppManifestFull, type NpmModuleEntry, type AppManifestFull } from './app-manifest.js';
+
+/**
+ * walkManifests(appDir)——单次遍历四产物（D24/D26；ai-build C3-1）。
+ *
+ * manifest 候选路径探测（packages/<id>/tbox.module.json 优先 → node_modules/<pkg>/tbox.module.json；
+ * tbox-app dev 真身经 .tbox-dev.local/dev-manifest.json redirects 独立 catalog 通道直达）一次遍历同时产出：
+ *   1. modules：已装模块清单（declared；demand meta title/description 透传）
+ *   2. catalog（富形态）：providers 嵌套（vendor→impl→entry，per-service {implementation, credentialType}
+ *      保真——同厂商异构/多实现合法，D25/H1）+ 需求侧聚合
+ *   3. serviceSchemas：per-service schema 复合键表——键 `${provider}\u0000${service}`（H2，同一服务
+ *      多厂商供给各自 schema 零碰撞）；多 impl 同 (provider, service) 异 schema → 声明序首个
+ *   4. vocabulary：所有携带 service-slots.json 的已装契约包该文件 `.slots` 键并集（fs 直读、
+ *      `$comment` 忽略；探测链 = readdir(<候选>/node_modules/@tbox.cn) 过滤携带该文件的包——
+ *      零缓存枚举，与 manifest 探测同机制；多行业 contracts-* 天然扩展 F8）；缺席 → []（退化 demanded ∪ configured）
+ *   5. domainKeyIssues：跨模块域键冲突 issue（两模块派生同一 domains 键——P13）
+ *
+ * **约束（D26；FX-3/F7 边界）**：目录枚举零缓存——readdir / node_modules 候选探测 / `.tbox/app.json` 读取 /
+ * dev-manifest 读取每次执行（枚举输入保持 fresh——agent 装卸模块下一笔即见）；manifest/service-slots
+ * **文件内容**经 file-cache（`cache` 可选参——工厂/写内核传本实例 cache（stat 指纹自愈 + 写后失效）；
+ * CLI 传 undefined 即全 fresh）。
+ * 宽松解析语义（坏文件静默 + 重复键首声明保留）零改动。
+ */
+
+export interface WalkManifestsResult {
+  /** declared 产物（install id + descriptor；demand meta 透传） */
+  modules: WalkModuleInfo[];
+  /** 富形态 catalog（providers 嵌套保真 + 需求聚合 + credentialTypes） */
+  catalog: WalkCatalog;
+  /** per-service schema 复合键表：`${provider}\u0000${service}` → schema 引用 + 包根 */
+  serviceSchemas: Record<string, { configSchema?: string; credentialSchema?: string; packageDir: string }>;
+  /** 服务词汇 = 所有携带 service-slots.json 的已装契约包 `.slots` 键并集（缺席 → []） */
+  vocabulary: string[];
+  /** 跨模块域键冲突（P13——两模块的 service 集派生同一 domains 键） */
+  domainKeyIssues: Array<{ severity: 'warning'; code: 'DOMAIN_KEY_CONFLICT'; message: string; module?: string }>;
+}
+
+export interface WalkModuleInfo {
+  /** install id（packages/ 目录名 / npmModules entry.id） */
+  id: string;
+  /** 模块目录（本地 packages/<id> 优先；sdk 包 = node_modules 解析位） */
+  dir: string;
+  /** 发布源包名 */
+  pkg: string;
+  descriptor: ModuleDescriptor;
+}
+
+/** 富形态供给条目：per-service {implementation, credentialType} 恒数组保真（H1） */
+export interface WalkProviderEntry {
+  provider: string;
+  implementation: string;
+  credentialType: string;
+  owner: string;
+  local?: boolean;
+  configSchema?: string;
+  credentialSchema?: string;
+  services: string[];
+}
+
+export interface WalkCatalog {
+  providers: Record<string, Record<string, WalkProviderEntry>>;
+  services: Record<
+    string,
+    {
+      optional: boolean;
+      defaults: Array<{ provider: string; implementation: string }>;
+      /** demand meta（title/description 首声明保留——模块 manifest demand 侧 additive） */
+      title?: string;
+      description?: string;
+      owners: string[];
+    }
+  >;
+  credentialTypes: Record<string, { owner: string; credentialSchema?: string }>;
+}
+
+/** loose 允许的 contributes 局部结构（本地声明——解跨模块类型身份耦合，TS2719 防线） */
+interface LooseContributes {
+  providers?: { slots?: ProviderSlotContrib[] };
+  services?: Array<{
+    service: string;
+    optional?: boolean;
+    defaults?: Array<{ provider: string; implementation: string }>;
+    title?: string;
+    description?: string;
+  }>;
+}
+
+/** manifest 读取结果（判别联合——strict = 完整 descriptor；loose = 部分形态宽容提取） */
+type ReadManifestResult =
+  | { kind: 'strict'; name: string; version: string; descriptor: ModuleDescriptor; contributes: ModuleDescriptor['contributes'] }
+  | { kind: 'loose'; name?: string; contributes: LooseContributes };
+
+/** 读单文件 manifest（坏文件 → null；宽松——strict 解析失败但有 contributes → loose 兜底，
+ *  保留旧 SDK loadProviderCatalog 对部分形态 manifest 的容忍语义，C3-5 桥等价性）。
+ *  FX-3（F7 边界）：**文件内容**经 file-cache（stat 指纹——外部写下一笔自愈）；目录枚举仍零缓存。 */
+function readManifestFile(file: string, cache?: FileCache): ReadManifestResult | null {
+  const parse = (raw: string): ReadManifestResult | null => {
+    try {
+      const parsedRaw: unknown = JSON.parse(raw);
+      const parsed = parseModuleDescriptor(parsedRaw);
+      if (parsed.ok) {
+        return { kind: 'strict', name: parsed.value.name, version: parsed.value.version, descriptor: parsed.value, contributes: parsed.value.contributes };
+      }
+      // loose 兜底：strict 拒（部分形态 manifest——如仅 contributes）但有 contributes → 宽松提取
+      if (parsedRaw && typeof parsedRaw === 'object' && 'contributes' in parsedRaw) {
+        const obj = parsedRaw as { name?: unknown; contributes?: ModuleDescriptor['contributes'] };
+        return {
+          kind: 'loose',
+          ...(typeof obj.name === 'string' ? { name: obj.name } : {}),
+          contributes: {
+            providers: (obj.contributes as LooseContributes | undefined)?.providers,
+            services: (obj.contributes as LooseContributes | undefined)?.services,
+          },
+        };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  };
+  if (cache) return cache.read(file, parse) ?? null;
+  if (!existsSync(file)) return null;
+  try {
+    return parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** npmModules 清单读取（纯 .tbox/app.json——dev-manifest 独立通道见 readDevManifestRedirects；
+ *  宽松语义：不要求 templateVersion——严格读取归 readAppManifest（CLI 装配）；空/坏文件 → 空） */
+function readNpmModules(appDir: string): NpmModuleEntry[] {
+  const file = join(appDir, '.tbox', 'app.json');
+  if (!existsSync(file)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as { npmModules?: unknown };
+    if (!Array.isArray(parsed.npmModules)) return [];
+    return parsed.npmModules.filter(
+      (e): e is NpmModuleEntry =>
+        !!e && typeof e === 'object' && typeof (e as NpmModuleEntry).id === 'string' && typeof (e as NpmModuleEntry).package === 'string',
+    );
+  } catch {
+    return [];
+  }
+}
+
+/** dev-manifest 通道输入：{pkg, 真身目录} 对——redirect 相对 stageDir 直达（join 型消费方
+ *  不吃 symlink，数据面喂食（架构定律 B）；免疫 pnpm 中层剪链（R-7））。
+ *  仅 catalog 聚合消费（聚合宽/声明窄不变量）——modules 声明集永不含 dev 真身（防 dev 会话
+ *  残留期 module sync 污染受跟踪装配文件）。非 dev 环境 marker 永不在场 → 零影响；坏文件静默空。 */
+interface DevManifestRedirect {
+  pkg: string;
+  dir: string;
+}
+
+function readDevManifestRedirects(appDir: string): DevManifestRedirect[] {
+  const stageDir = join(appDir, '.tbox-dev.local');
+  const devManifest = join(stageDir, 'dev-manifest.json');
+  if (!existsSync(devManifest)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync(devManifest, 'utf8')) as { redirects?: Record<string, unknown> };
+    const out: DevManifestRedirect[] = [];
+    for (const [pkg, rel] of Object.entries(parsed.redirects ?? {})) {
+      if (typeof rel !== 'string' || !pkg.startsWith('@tbox.cn/app-')) continue;
+      out.push({ pkg, dir: join(stageDir, rel) });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+/** 契约包发现链：readdir(node_modules/@tbox.cn) 过滤携带 service-slots.json 的包（目录枚举零缓存，F8；
+ *  FX-3：slots 文件**内容**经 file-cache） */
+function discoverContractPackages(appDir: string, cache?: FileCache): Array<{ dir: string; slots: string[] }> {
+  const found: Array<{ dir: string; slots: string[] }> = [];
+  const candidates: Array<string> = [appDir];
+  for (const sub of ['apps', 'packages']) {
+    const parent = join(appDir, sub);
+    if (!existsSync(parent)) continue;
+    try {
+      for (const d of readdirSync(parent, { withFileTypes: true })) {
+        if (d.isDirectory()) candidates.push(join(parent, d.name));
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  const seenRoots = new Set<string>();
+  for (const dir of candidates) {
+    const scopeDir = join(dir, 'node_modules', '@tbox.cn');
+    if (!existsSync(scopeDir)) continue;
+    let names: string[] = [];
+    try {
+      names = readdirSync(scopeDir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      const pkgDir = join(scopeDir, name);
+      if (seenRoots.has(pkgDir)) continue;
+      seenRoots.add(pkgDir);
+      const slotsFile = join(pkgDir, 'service-slots.json');
+      if (!existsSync(slotsFile)) continue;
+      const parseSlots = (raw: string): string[] | null => {
+        try {
+          const parsed = JSON.parse(raw) as { slots?: unknown };
+          if (Array.isArray(parsed.slots)) return parsed.slots.filter((s): s is string => typeof s === 'string');
+        } catch {
+          /* 宽松：坏文件跳过 */
+        }
+        return null;
+      };
+      const slots = cache ? cache.read(slotsFile, parseSlots) : parseSlots(readFileSync(slotsFile, 'utf8'));
+      if (slots !== null && slots !== undefined) found.push({ dir: pkgDir, slots });
+    }
+  }
+  return found;
+}
+
+/** walkManifests 主体（单次遍历四产物；目录枚举零缓存——每次调用执行） */
+export function walkManifests(appDir: string, cache?: FileCache): WalkManifestsResult {
+  const modules: WalkModuleInfo[] = [];
+  const catalog: WalkCatalog = { providers: {}, services: {}, credentialTypes: {} };
+  const serviceSchemas: WalkManifestsResult['serviceSchemas'] = {};
+  const domainKeyIssues: WalkManifestsResult['domainKeyIssues'] = [];
+  const seen = new Set<string>();
+  /** 域键 → 首个声明模块（P13 冲突检测） */
+  const domainOwners = new Map<string, string>();
+
+  const addSlots = (slots: readonly ProviderSlotContrib[], owner: string, packageDir: string): void => {
+    for (const slot of slots) {
+      // 富形态：per-service {implementation, credentialType} 保真（同厂商多 impl 合法——声明序）
+      const vendorSlots = (catalog.providers[slot.provider] ??= {});
+      const existing = vendorSlots[slot.implementation];
+      if (existing) {
+        if (!existing.services.includes(slot.service)) existing.services.push(slot.service);
+      } else {
+        vendorSlots[slot.implementation] = {
+          provider: slot.provider,
+          implementation: slot.implementation,
+          credentialType: slot.credentialType,
+          owner,
+          ...(slot.local ? { local: true } : {}),
+          ...(slot.configSchema ? { configSchema: slot.configSchema } : {}),
+          ...(slot.credentialSchema ? { credentialSchema: slot.credentialSchema } : {}),
+          services: [slot.service],
+        };
+        catalog.credentialTypes[slot.credentialType] ??= {
+          owner,
+          ...(slot.credentialSchema ? { credentialSchema: slot.credentialSchema } : {}),
+        };
+      }
+      // per-service schema 复合键（H2）：同 (provider, service) 异 schema → 声明序首个
+      const schemaKey = `${slot.provider}\u0000${slot.service}`;
+      if (!serviceSchemas[schemaKey]) {
+        serviceSchemas[schemaKey] = {
+          ...(slot.configSchema ? { configSchema: slot.configSchema } : {}),
+          ...(slot.credentialSchema ? { credentialSchema: slot.credentialSchema } : {}),
+          packageDir,
+        };
+      }
+    }
+  };
+
+  const addServiceNeed = (
+    need: { service: string; optional?: boolean; defaults?: Array<{ provider: string; implementation: string }>; title?: string; description?: string },
+    owner: string,
+  ): void => {
+    const optional = need.optional !== false;
+    const defaults = need.defaults ?? [];
+    const existing = catalog.services[need.service];
+    if (existing) {
+      existing.optional = existing.optional && optional;
+      const seenDefaults = new Set(existing.defaults.map((d) => `${d.provider}\u0000${d.implementation}`));
+      for (const d of defaults) {
+        const k = `${d.provider}\u0000${d.implementation}`;
+        if (!seenDefaults.has(k)) {
+          existing.defaults.push(d);
+          seenDefaults.add(k);
+        }
+      }
+      if (!existing.owners.includes(owner)) existing.owners.push(owner);
+      return;
+    }
+    catalog.services[need.service] = {
+      optional,
+      defaults: [...defaults],
+      ...(need.title ? { title: need.title } : {}),
+      ...(need.description ? { description: need.description } : {}),
+      owners: [owner],
+    };
+    // P13 域键冲突检测（首声明占用；跨模块冲突 → issue）
+    const domain = need.service.includes('.') ? need.service.slice(0, need.service.indexOf('.')) : need.service;
+    const firstOwner = domainOwners.get(domain);
+    if (firstOwner === undefined) domainOwners.set(domain, owner);
+    else if (firstOwner !== owner) {
+      domainKeyIssues.push({
+        severity: 'warning',
+        code: 'DOMAIN_KEY_CONFLICT',
+        module: owner,
+        message: `域键 ${domain} 被多模块声明（${firstOwner} 与 ${owner}）——domains 换算歧义（P13）`,
+      });
+    }
+  };
+
+  // 通道 1：npmModules 登记（packages/<id> 本地优先 → node_modules/<pkg>）
+  for (const entry of readNpmModules(appDir)) {
+    if (seen.has(entry.id)) continue;
+    const local = join(appDir, 'packages', entry.id);
+    const nm = join(appDir, 'node_modules', ...entry.package.split('/'));
+    const manifest = readManifestFile(join(local, 'tbox.module.json'), cache) ?? readManifestFile(join(nm, 'tbox.module.json'), cache);
+    if (!manifest) continue;
+    seen.add(entry.id);
+    const dir = existsSync(join(local, 'tbox.module.json')) ? local : nm;
+    const contributes = manifest.contributes;
+    // loose 形态（部分 manifest）不进 modules 清单（descriptor 缺名不可装配化）——仅 catalog 聚合（旧语义等价）
+    if (manifest.kind === 'strict') {
+      modules.push({ id: entry.id, dir, pkg: entry.mode === 'sdk' ? entry.package : `@app/${entry.id}`, descriptor: manifest.descriptor });
+    }
+    const slots = contributes.providers?.slots ?? [];
+    if (slots.length) addSlots(slots, entry.package, dir);
+    const needs = contributes.services ?? [];
+    if (needs.length) {
+      for (const need of needs) {
+        addServiceNeed(need, entry.package);
+      }
+    }
+  }
+
+  // 通道 1.5：tbox-app dev manifest 真身（catalog-only——聚合宽/声明窄不变量：dev 模块
+  // 永不进 modules 清单，防 sync 污染受跟踪装配文件；登记真源优先（seen 按模块名去重））
+  for (const { pkg, dir } of readDevManifestRedirects(appDir)) {
+    const manifest = readManifestFile(join(dir, 'tbox.module.json'), cache);
+    if (!manifest?.name || seen.has(manifest.name)) continue;
+    seen.add(manifest.name);
+    const slots = manifest.contributes.providers?.slots ?? [];
+    if (slots.length) addSlots(slots, pkg, dir);
+    const needs = manifest.contributes.services ?? [];
+    if (needs.length) {
+      for (const need of needs) addServiceNeed(need, pkg);
+    }
+  }
+
+  // 通道 2：packages/* 约定发现（本地模块——npmModules 未登记形态，如模板天气模块）
+  const packagesDir = join(appDir, 'packages');
+  if (existsSync(packagesDir)) {
+    let entries: string[] = [];
+    try {
+      entries = readdirSync(packagesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+    } catch {
+      /* ignore */
+    }
+    for (const name of entries) {
+      if (seen.has(name)) continue;
+      const dir = join(packagesDir, name);
+      const manifest = readManifestFile(join(dir, 'tbox.module.json'), cache);
+      if (!manifest) continue;
+      const modName = manifest.name ?? name;
+      if (seen.has(modName)) continue;
+      seen.add(modName);
+      const contributes = manifest.contributes;
+      if (manifest.kind === 'strict') {
+        modules.push({ id: modName, dir, pkg: `@app/${modName}`, descriptor: manifest.descriptor });
+      }
+      const slots = contributes.providers?.slots ?? [];
+      if (slots.length) addSlots(slots, `@app/${modName}`, dir);
+      const needs = contributes.services ?? [];
+      if (needs.length) {
+        for (const need of needs) {
+          addServiceNeed(need, `@app/${modName}`);
+        }
+      }
+    }
+  }
+
+  // 产物 4：服务词汇（契约包 service-slots.json 并集——零缓存枚举）
+  const vocabulary = new Set<string>();
+  for (const pkg of discoverContractPackages(appDir, cache)) {
+    for (const s of pkg.slots) vocabulary.add(s);
+  }
+
+  return { modules, catalog, serviceSchemas, vocabulary: [...vocabulary].sort(), domainKeyIssues };
+}
+
+// ── CLI collectDeclared 迁入（C5——声明集合 + 双端入口探测 + declaration.moduleId 提取）──
+
+export interface DeclaredModuleInfo {
+  id: string;
+  /** 装配包名（codegen/local = @app/<id>；sdk = 发布包名） */
+  pkg: string;
+  mode: 'local' | 'sdk' | 'codegen';
+  hasServerEntry: boolean;
+  hasClientEntry: boolean;
+  hasCards: boolean;
+  /** declaration.moduleId（deployment 对账真源；老模块无 declaration → undefined） */
+  moduleId?: string;
+}
+
+/** 探测模块双端描述对象入口（src/{server,client}/index.ts export const serverModule/clientModule） */
+function probeModuleObjectExport(dir: string, sub: 'server' | 'client', symbol: string): boolean {
+  const file = join(dir, 'src', sub, 'index.ts');
+  if (!existsSync(file)) return false;
+  try {
+    const src = readFileSync(file, 'utf8');
+    return new RegExp(`export\\s+const\\s+${symbol}\\b`).test(src);
+  } catch {
+    return false;
+  }
+}
+
+/** 读模块 server 入口源码（无入口 → ''） */
+function readServerSource(dir: string): string {
+  const file = join(dir, 'src', 'server', 'index.ts');
+  if (!existsSync(file)) return '';
+  try {
+    return readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** 提取 declaration.moduleId（宽松正则——容忍任意嵌套/注释；未声明 → undefined） */
+export function extractModuleIdFromSource(source: string): string | undefined {
+  const match = source.match(/declaration\s*:\s*\{[\s\S]*?moduleId\s*:\s*['"]([^'"]+)['"]/);
+  return match?.[1];
+}
+
+/**
+ * 计算声明集合（含 npm 清单 + 本地模块约定发现）。
+ * hasServerEntry/hasClientEntry 决定模块参与哪些装配文件（入口探测，非 post-hoc 修复）。
+ * 单源 = walkManifests（npmModules 登记 + packages/* 约定发现双通道；strict 形态进清单）。
+ */
+export function collectDeclaredModules(appDir: string): DeclaredModuleInfo[] {
+  const declared: DeclaredModuleInfo[] = [];
+  const walk = walkManifests(appDir);
+  const manifest: AppManifestFull | null = readAppManifestFull(appDir);
+  const modeById = new Map<string, 'local' | 'sdk' | 'codegen'>();
+  for (const entry of manifest?.npmModules ?? []) {
+    modeById.set(entry.id, entry.mode);
+  }
+  for (const mod of walk.modules) {
+    const mode = modeById.get(mod.id) ?? 'local';
+    const hasServerEntry = probeModuleObjectExport(mod.dir, 'server', 'serverModule');
+    const c = mod.descriptor.contributes;
+    declared.push({
+      id: mod.id,
+      pkg: mode === 'sdk' ? mod.pkg : `@app/${mod.id}`,
+      mode,
+      hasServerEntry,
+      hasClientEntry: probeModuleObjectExport(mod.dir, 'client', 'clientModule'),
+      hasCards: (c.cards?.length ?? 0) > 0,
+      ...(hasServerEntry ? { moduleId: extractModuleIdFromSource(readServerSource(mod.dir)) } : {}),
+    });
+  }
+  return declared.sort((a, b) => a.id.localeCompare(b.id));
+}

package/src/core/contracts-expected.ts

@@ -0,0 +1,31 @@
+import type {
+  buildSupplyLookup,
+  moduleDomainOf,
+  normalizeInstances,
+  resolveEffectiveService,
+  IntegrationsConfig,
+} from '@tbox.cn/app-contracts';
+
+/**
+ * contracts 期望面编译期锁（satisfies 语义防接口漂移——contracts 加名/改签名即编译红）。
+ * resolver 运行时产物按本接口逐命名导出存在性检查（evaluation/strictValidation 按在场降级）。
+ * contracts 恒 devDep 且限 import type——运行时全经 resolver 动态 import（版本解耦，D3）。
+ */
+
+export interface EvaluationExports {
+  /** 求值单源（TIER0；v3 显式激活 vs v4 通配语义随应用版本） */
+  resolveEffectiveService: typeof resolveEffectiveService;
+  /** 供给查表派生（谓词 #12 与视图供给轴共用输入） */
+  buildSupplyLookup: typeof buildSupplyLookup;
+  /** service → 首点段域前缀（谓词 #14 域键匹配） */
+  moduleDomainOf: typeof moduleDomainOf;
+  /** 部署实例注册表归一（默认实例委托——null → '*' 通配口径） */
+  normalizeInstances: typeof normalizeInstances;
+  /** 模块资源类型词汇表（v5；descriptor type 校验经 resolver 取词表） */
+  RESOURCE_TYPE_IDS: readonly string[];
+  /** 严格 zod 面（0.9+ 可选）——strictValidation 门控判据；缺席 = 求值/写 503 */
+  parseIntegrationsConfig?: (raw: unknown) => IntegrationsConfig;
+}
+
+/** resolver 运行时产物类型（动态 import 的命名导出子集） */
+export type ResolvedModule = Partial<EvaluationExports>;