@tbox.cn/app-toolkit 0.5.0 → 0.7.0

package/tests/dev-manifest-catalog.test.ts

@@ -119,7 +119,7 @@ describe('walkManifests · dev-manifest catalog 通道（聚合宽/声明窄）'
  * （local/codegen 全量副本——mall 生成应用主形态，不依赖 install）。
  * 修复前探测只扫包根 → 三形态全 miss（vocabulary 恒空）。
  */
-describe('walkManifests · 词汇探测三跳 + slotMeta（B0）', () => {
+describe('walkManifests · 词汇探测四跳 + slotMeta（B0；v7 += 跳⓪ config override 层）', () => {
   it('P1: nm 包根布局（跳①）→ vocabulary 命中；slotMeta 透传', () => {
     app = createTempApp('tbox-probe-');
     const store = join(app.appDir, '_store-a');
@@ -185,6 +185,44 @@ describe('walkManifests · 词汇探测三跳 + slotMeta（B0）', () => {
     expect(walk.slotMeta).toEqual({ 'e.f': { name: '甲' } }); // 空串 description 不入表（与 title 守卫对称）
   });
 
+  it('P6: 跳⓪ config override 层——meta per-service 覆盖真源 + 无键键穿透真源（首声明 = config 最前）', () => {
+    app = createTempApp('tbox-probe-');
+    const store = join(app.appDir, '_store-truth');
+    writeFakeContractsPackage(store, {
+      slots: ['a.b', 'c.d'],
+      meta: { 'a.b': { name: '真源甲' }, 'c.d': { name: '真源丙' } },
+    });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    // 用户 override：只改名 a.b；c.d 不写（穿透真源）；e.f 仅快照声明（幻影语义由 doctor 报告）
+    writeFileSync(
+      join(app.appDir, 'config', 'service-slots.json'),
+      JSON.stringify({ $comment: { seededAt: 'x' }, slots: ['a.b', 'e.f'], meta: { 'a.b': { name: '用户改名甲' } } }),
+    );
+
+    const walk = walkManifests(app.appDir);
+    // 词汇并集：config ∪ 真源（config 不遮蔽真源新增）
+    expect(walk.vocabulary).toEqual(['a.b', 'c.d', 'e.f']);
+    // meta 覆盖：config 先声明胜出；未覆盖键穿透真源
+    expect(walk.slotMeta['a.b']).toEqual({ name: '用户改名甲' });
+    expect(walk.slotMeta['c.d']).toEqual({ name: '真源丙' });
+  });
+
+  it('P7: 跳⓪ 快照 meta 恒空（seed 形态）→ 真源 meta 恒穿透；$comment 键零解析影响', () => {
+    app = createTempApp('tbox-probe-');
+    const store = join(app.appDir, '_store-seed');
+    writeFakeContractsPackage(store, { slots: ['a.b'], meta: { 'a.b': { name: '真源甲' } } });
+    linkContracts(app.appDir, store, { subdir: 'apps/server' });
+    // seed-once 产物形态：slots 全量 + meta 空对象
+    writeFileSync(
+      join(app.appDir, 'config', 'service-slots.json'),
+      JSON.stringify({ $comment: { seededAt: '2026-09-21', slots: 1 }, slots: ['a.b'], meta: {} }),
+    );
+
+    const walk = walkManifests(app.appDir);
+    expect(walk.vocabulary).toEqual(['a.b']);
+    expect(walk.slotMeta['a.b']).toEqual({ name: '真源甲' }); // 空 meta 不夺覆盖权
+  });
+
   it('P6: 无契约包（退化态）→ vocabulary 空 + slotMeta 空（P9 退化路径语义锁）', () => {
     app = createTempApp('tbox-probe-');
     const walk = walkManifests(app.appDir);

package/tests/module-resources.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { createAppToolkit, type AppToolkit } from '../src/factory.js';
+import { invalidateContractsResolver } from '../src/core/contracts-resolver.js';
+import { MODULE_INTEGRATION_NODE_KEYS } from '../src/dto.js';
+import type { ModuleDetailView } from '../src/dto.js';
+import { createTempApp, writeFakeContractsPackage, linkContracts, writeAppFile, type TempApp } from './demo-app.js';
+
+/**
+ * 模块资源只读投影矩阵（N2 读半边）：GET /modules/:m `resources` 四态（直填 datasetId /
+ * ref 命中台账 / ref 未命中（台账缺失·坏文件·键 miss 同归 null）/ 无 modules 节 = null）
+ * + 写侧保全不变量（MODULE_INTEGRATION_NODE_KEYS 白名单不变——resources 不进写位）。
+ * 展开语义镜像 SDK resolveKnowledge：datasetId 直填优先、ref 台账命中/miss-warn 降级。
+ */
+
+interface Harness {
+  app: TempApp;
+  tk: AppToolkit;
+}
+
+/** 自足基座：module-cs（declare.resources 声明对齐真实客服 manifest）+ integrations + 可选台账 */
+function resourcesHarness(integrations: object, knowledge: object | null): Harness {
+  const app = createTempApp('tbox-res-');
+  invalidateContractsResolver();
+  const store = join(app.appDir, 'contracts');
+  writeFakeContractsPackage(store, { version: '0.9.0' });
+  linkContracts(app.appDir, store, { subdir: 'apps/server' });
+  mkdirSync(join(app.appDir, 'packages', 'module-cs'), { recursive: true });
+  writeAppFile(
+    app.appDir,
+    'packages/module-cs/tbox.module.json',
+    JSON.stringify({
+      schemaVersion: 1,
+      id: 'module-cs',
+      version: '0.1.0',
+      kind: 'business',
+      declare: {
+        owns: [],
+        consumes: [],
+        resources: [
+          { id: 'customer-service-faq-kb', type: 'knowledge' },
+          { id: 'knowledge-assistance-kb', type: 'knowledge' },
+        ],
+      },
+      dependencies: { modules: [] },
+      env: [],
+    }),
+  );
+  writeAppFile(app.appDir, 'config/integrations.json', JSON.stringify(integrations));
+  if (knowledge !== null) {
+    writeAppFile(app.appDir, 'config/knowledge.json', JSON.stringify(knowledge));
+  }
+  const tk = createAppToolkit(app.appDir);
+  return { app, tk };
+}
+
+const FAQ_DIRECT = {
+  provider: 'mock',
+  modules: {
+    'module-cs': {
+      resources: { 'customer-service-faq-kb': { type: 'knowledge', datasetId: '20260101direct00000000000001', topK: 5, scoreThreshold: 0.5 } },
+    },
+  },
+};
+
+const FAQ_REF = {
+  provider: 'mock',
+  modules: {
+    'module-cs': {
+      resources: { 'customer-service-faq-kb': { type: 'knowledge', ref: 'customer-service-faq-generic' } },
+    },
+  },
+};
+
+const KB_REGISTRY = {
+  version: '1.0',
+  knowledge_bases: {
+    'customer-service-faq-generic': { datasetId: '20260921999def645305kQj02050918', retrieve_config: { topK: 5, scoreThreshold: 0.5 } },
+  },
+};
+
+async function detailOf(h: Harness): Promise<ModuleDetailView> {
+  return h.tk.loadModule('module-cs');
+}
+
+describe('module resources 只读投影（N2 读半边）', () => {
+  it('T1 直填 datasetId：resolvedDatasetId = 原值（无台账读取依赖）', async () => {
+    const h = resourcesHarness(FAQ_DIRECT, null); // 台账缺失——直填态不受影响
+    const v = await detailOf(h);
+    expect(v.resources).not.toBeNull();
+    expect(v.resources!['customer-service-faq-kb']).toEqual({
+      type: 'knowledge',
+      datasetId: '20260101direct00000000000001',
+      resolvedDatasetId: '20260101direct00000000000001',
+      topK: 5,
+      scoreThreshold: 0.5,
+    });
+    h.app.dispose();
+  });
+
+  it('T2 ref 命中台账：resolvedDatasetId = 台账 datasetId；文件原值 ref 保留', async () => {
+    const h = resourcesHarness(FAQ_REF, KB_REGISTRY);
+    const v = await detailOf(h);
+    expect(v.resources!['customer-service-faq-kb']).toEqual({
+      type: 'knowledge',
+      ref: 'customer-service-faq-generic',
+      resolvedDatasetId: '20260921999def645305kQj02050918',
+    });
+    h.app.dispose();
+  });
+
+  it('T3 ref 未命中键：resolvedDatasetId = null（原值 ref 保留）', async () => {
+    const h = resourcesHarness(FAQ_REF, { knowledge_bases: { 'other-kb': { datasetId: 'x' } } });
+    const v = await detailOf(h);
+    expect(v.resources!['customer-service-faq-kb']).toEqual({
+      type: 'knowledge',
+      ref: 'customer-service-faq-generic',
+      resolvedDatasetId: null,
+    });
+    h.app.dispose();
+  });
+
+  it('T3b 台账文件缺失 / 坏 JSON：同归 resolvedDatasetId = null（fail-soft 镜像 SDK）', async () => {
+    const missing = resourcesHarness(FAQ_REF, null);
+    expect((await detailOf(missing)).resources!['customer-service-faq-kb']?.resolvedDatasetId).toBeNull();
+    missing.app.dispose();
+
+    const broken = resourcesHarness(FAQ_REF, KB_REGISTRY);
+    writeAppFile(broken.app.appDir, 'config/knowledge.json', '{not-json');
+    expect((await detailOf(broken)).resources!['customer-service-faq-kb']?.resolvedDatasetId).toBeNull();
+    broken.app.dispose();
+  });
+
+  it('T4 无 modules 节 / 模块键无 resources：resources = null（null 语义：无资源 ≠ 空表）', async () => {
+    const noModules = resourcesHarness({ provider: 'mock' }, null);
+    expect((await detailOf(noModules)).resources).toBeNull();
+    noModules.app.dispose();
+
+    const noResourcesKey = resourcesHarness({ provider: 'mock', modules: { 'module-cs': { config: { k: 1 } } } }, KB_REGISTRY);
+    expect((await detailOf(noResourcesKey)).resources).toBeNull();
+    noResourcesKey.app.dispose();
+  });
+
+  it('T5 写侧保全不变量：MODULE_INTEGRATION_NODE_KEYS 白名单恒不含 resources（N2 写半边不变）', () => {
+    expect(MODULE_INTEGRATION_NODE_KEYS).toEqual(['provider', 'config']);
+  });
+});

package/tests/module-schema.test.ts

@@ -128,6 +128,20 @@ describe('module-schema（descriptor zod 单源）', () => {
     }
   });
 
+  it('hidden 展示元数据：boolean 可选（true/false 通过、缺席合法、非 boolean 拒——清单过滤语义归视图层）', () => {
+    const hidden = parseModuleDescriptor({ ...BASE_MANIFEST, hidden: true });
+    expect(hidden.ok).toBe(true);
+    if (hidden.ok) expect(hidden.value.hidden).toBe(true);
+    const unhidden = parseModuleDescriptor({ ...BASE_MANIFEST, hidden: false });
+    expect(unhidden.ok).toBe(true);
+    if (unhidden.ok) expect(unhidden.value.hidden).toBe(false);
+    const absent = moduleDescriptorSchema.safeParse(BASE_MANIFEST);
+    expect(absent.success).toBe(true);
+    if (absent.success) expect(absent.data.hidden).toBeUndefined();
+    const bad = parseModuleDescriptor({ ...BASE_MANIFEST, hidden: 'yes' });
+    expect(bad.ok).toBe(false);
+  });
+
   // ── v7 词汇统一：legacy 四象限矩阵（旧态/半迁移定向拒；v7 两形态放行）──
 
   it('v7 legacy ①：v6 旧态（name 标识 + title 展示、无 id）→ 定向拒 + legacy 标志 + 双键指引', () => {