@tbox.cn/app-toolkit 0.8.1 → 0.8.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -3
- package/dist/chunk-K5FIGT5A.js +1 -0
- package/dist/contracts-resolver-2COLDT6T.js +1 -0
- package/dist/index.d.ts +18 -10
- package/dist/index.js +9 -9
- package/package.json +1 -1
- package/src/core/contracts-resolver.ts +20 -1
- package/src/core/errors.ts +2 -2
- package/src/dto.ts +12 -0
- package/src/factory.ts +39 -27
- package/src/integrations/read.ts +1 -1
- package/src/integrations/write.ts +59 -27
- package/src/views/service-resolutions.ts +4 -2
- package/tests/contracts-resolver.test.ts +16 -1
- package/tests/demo-app.ts +1 -1
- package/tests/keyset-lockstep.test.ts +95 -0
- package/tests/views.test.ts +7 -2
- package/tests/write-core.test.ts +141 -2
- package/dist/chunk-WUULQDOV.js +0 -1
- package/dist/contracts-resolver-PS2UH2G6.js +0 -1
package/src/factory.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { writeAtomic } from './core/fskit.js';
|
|
|
3
3
|
import { walkManifests as internalsWalk } from './assembly/walk-manifests.js';
|
|
4
4
|
import type { FileCache } from './core/file-cache.js';
|
|
5
5
|
import { createFileCache } from './core/file-cache.js';
|
|
6
|
-
import { resolveContractsForApp, invalidateContractsResolver } from './core/contracts-resolver.js';
|
|
6
|
+
import { resolveContractsForApp, invalidateContractsResolver, contractsTier } from './core/contracts-resolver.js';
|
|
7
7
|
import type { ResolvedContracts } from './core/contracts-resolver.js';
|
|
8
8
|
import { parseModuleDescriptor } from './core/module-schema.js';
|
|
9
9
|
import { loadProviderServiceDetailView, loadProvidersView } from './views/providers.js';
|
|
@@ -58,13 +58,15 @@ import type {
|
|
|
58
58
|
* Read+Write = HTTP 直通面 additive 冻结(L1 端点↔方法 1:1,L3 命名镜像:Integration=节点级 /
|
|
59
59
|
* Config=文件级);Internals = CLI/doctor/桥消费(自由演进)。
|
|
60
60
|
*
|
|
61
|
-
* **门控断言单点(policy at edge——
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
61
|
+
* **门控断言单点(policy at edge——0.8.2 降级写批收窄为 contractsTier 两策略)**:写×4 =
|
|
62
|
+
* tier !== 'blocked'(version null 降级放行——跳过 zod + STRICT_VALIDATION_SKIPPED warning 承载
|
|
63
|
+
* 感知;<0.9 已装/偏斜 503 升级指引);evaluate = tier === 'ok'(求值无降级语义);
|
|
64
|
+
* ensureMockBindings / writeIntegrationsConfig 无门(行为不随 contracts 状态分叉——纯 fs 派生 /
|
|
65
|
+
* 透传整写,blanket 残留摘除);静态方法不门控(永不 503——铁律 #3);**读求值轴(
|
|
66
|
+
* loadServiceResolutions/loadServiceResolution 及 include 装配)v7 起不再 503**——contracts 不可用
|
|
67
|
+
* → 200 降级骨架(evaluation-unavailable,doctor 分级先例对齐;依据链与裁决见 Agent Note
|
|
68
|
+
* evaluation-axis-degrade);**include 装配为条件分支非门控**(四面统一骨架);
|
|
69
|
+
* integrations/ views/ 机制层保持纯函数。
|
|
68
70
|
*
|
|
69
71
|
* 并发:进程内写串行(per-factory promise chain)+ 原子写 + 写后本实例缓存即刻失效。
|
|
70
72
|
* onApplied:toolkit 判定「需要重启」(实际落盘且非 dryRun/no-diff)→ 调用一次 +
|
|
@@ -170,8 +172,10 @@ export interface AppToolkitInternals {
|
|
|
170
172
|
loadProviderCatalogRaw(): ReturnType<typeof loadProviderCatalogRaw>;
|
|
171
173
|
/** 文件级读(doctor/migrate;宽松透传——strict 校验归门控面) */
|
|
172
174
|
readIntegrationsConfig(): Promise<Record<string, unknown> | null>;
|
|
173
|
-
/** 文件级整写(provider-migrate
|
|
175
|
+
/** 文件级整写(provider-migrate;0.8.2 降级写批摘门——行为不随 contracts 状态分叉,
|
|
176
|
+
* config 形状兼容性责任在调用方(保形迁移)) */
|
|
174
177
|
writeIntegrationsConfig(config: Record<string, unknown>): Promise<void>;
|
|
178
|
+
/** mock 绑定物化(0.8.2 降级写批摘门——纯 fs 派生零 contracts 依赖) */
|
|
175
179
|
ensureMockBindings(): Promise<ReturnType<typeof ensureMockBindings>>;
|
|
176
180
|
/** 谓词单源(contracts 注入签名;结构化输出) */
|
|
177
181
|
evaluateIntegrationServices(input: Omit<Parameters<typeof evaluateIntegrationServices>[0], 'contracts'>): Promise<IntegrationServiceIssue[]>;
|
|
@@ -185,15 +189,24 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
|
|
|
185
189
|
|
|
186
190
|
const viewCtx = { appDir, cache };
|
|
187
191
|
|
|
188
|
-
/**
|
|
189
|
-
*
|
|
190
|
-
*
|
|
191
|
-
|
|
192
|
-
|
|
192
|
+
/** 门控断言单点(policy at edge——0.8.2 降级写批收窄为 contractsTier 两策略,判据单源
|
|
193
|
+
* = core/contracts-resolver contractsTier;message 单源 = contractsNotResolvedMessage N1):
|
|
194
|
+
* - assertWritableContracts(写×4):tier === 'blocked' → 503——包在场但能力缺失(<0.9 已装 /
|
|
195
|
+
* 偏斜缺 v6 标记),v6 形状写入旧语境静默无效或被旧 zod 拒,fail-visible 拒绝 + 升级指引;
|
|
196
|
+
* version null(未装/未构建/导入拒绝)降级放行,跳过 zod 由写核 STRICT_VALIDATION_SKIPPED
|
|
197
|
+
* warning 承载感知。
|
|
198
|
+
* - assertFullyUsable(evaluate):tier !== 'ok' → 503——求值产物即求值结果,无降级可言
|
|
199
|
+
* (version null 亦不可求值)。
|
|
200
|
+
* - ensureMockBindings / writeIntegrationsConfig:无门(行为不随 contracts 状态分叉——
|
|
201
|
+
* 纯 fs 派生 / 透传整写零校验零形状生成,blanket 门控残留摘除;形状兼容性责任在调用方)。 */
|
|
202
|
+
function assertWritableContracts(contracts: ResolvedContracts): void {
|
|
203
|
+
if (contractsTier(contracts) === 'blocked') {
|
|
193
204
|
throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(contracts));
|
|
194
205
|
}
|
|
195
|
-
|
|
196
|
-
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
function assertFullyUsable(contracts: ResolvedContracts): void {
|
|
209
|
+
if (contractsTier(contracts) !== 'ok') {
|
|
197
210
|
throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(contracts));
|
|
198
211
|
}
|
|
199
212
|
}
|
|
@@ -365,13 +378,13 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
|
|
|
365
378
|
async writeAppIntegration(node: AppIntegrationNode, o?: WriteOptions) {
|
|
366
379
|
await core.warmup();
|
|
367
380
|
const contracts = await resolveContractsForApp(appDir);
|
|
368
|
-
|
|
381
|
+
assertWritableContracts(contracts);
|
|
369
382
|
return enqueue(() => core.applyApp(node as Record<string, unknown>, o));
|
|
370
383
|
},
|
|
371
384
|
async writeModuleIntegration(moduleId: string, node: ModuleIntegrationNode, o?: WriteOptions) {
|
|
372
385
|
await core.warmup();
|
|
373
386
|
const contracts = await resolveContractsForApp(appDir);
|
|
374
|
-
|
|
387
|
+
assertWritableContracts(contracts);
|
|
375
388
|
// enqueue 闭包内双键解析(写时新鲜度)——落盘键恒真实 id
|
|
376
389
|
return enqueue(() => {
|
|
377
390
|
const mod = resolveModuleKey(snapshot(contracts).walk, moduleId);
|
|
@@ -381,7 +394,7 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
|
|
|
381
394
|
async writeServiceIntegration(service: string, node: ServiceIntegrationNode, o?: WriteOptions) {
|
|
382
395
|
await core.warmup();
|
|
383
396
|
const contracts = await resolveContractsForApp(appDir);
|
|
384
|
-
|
|
397
|
+
assertWritableContracts(contracts);
|
|
385
398
|
return enqueue(() => {
|
|
386
399
|
const snap = snapshot(contracts);
|
|
387
400
|
const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
|
|
@@ -391,7 +404,7 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
|
|
|
391
404
|
async deleteServiceIntegration(service: string) {
|
|
392
405
|
await core.warmup();
|
|
393
406
|
const contracts = await resolveContractsForApp(appDir);
|
|
394
|
-
|
|
407
|
+
assertWritableContracts(contracts);
|
|
395
408
|
return enqueue(() => {
|
|
396
409
|
const snap = snapshot(contracts);
|
|
397
410
|
const serviceId = resolveServiceKey(snap.walk, configuredServiceKeys(snap), service);
|
|
@@ -421,21 +434,20 @@ export function createAppToolkit(appDir: string, options: AppToolkitOptions = {}
|
|
|
421
434
|
return readIntegrationsConfig(appDir, cache);
|
|
422
435
|
},
|
|
423
436
|
async writeIntegrationsConfig(config: Record<string, unknown>) {
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
437
|
+
// 无门(0.8.2 降级写批——行为不随 contracts 状态分叉:透传整写、零校验零形状生成,
|
|
438
|
+
// blanket 门控残留摘除;config 形状兼容性责任在调用方——CLI provider-migrate 保形迁移)。
|
|
439
|
+
// warmup 一并摘除(不跑 zod——严格校验缓存预热无消费方)
|
|
427
440
|
return enqueue(() => coreWriteIntegrationsConfig(appDir, config, cache));
|
|
428
441
|
},
|
|
429
442
|
async ensureMockBindings() {
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
assertContractsUsable(contracts);
|
|
443
|
+
// 无门(0.8.2 降级写批——纯 fs 派生零 contracts 依赖,输出 v4 兼容形状(terse/双字段均无
|
|
444
|
+
// modules 键);fresh clone 装依赖前物化 mock 绑定正当)。warmup 一并摘除(零校验无消费方)
|
|
433
445
|
return enqueue(() => ensureMockBindings(appDir));
|
|
434
446
|
},
|
|
435
447
|
async evaluateIntegrationServices(input) {
|
|
436
448
|
await core.warmup();
|
|
437
449
|
const contracts = await resolveContractsForApp(appDir);
|
|
438
|
-
|
|
450
|
+
assertFullyUsable(contracts);
|
|
439
451
|
const predicateContracts: PredicateContracts = {
|
|
440
452
|
resolveEffectiveService: assertFn(contracts.module.resolveEffectiveService, 'resolveEffectiveService'),
|
|
441
453
|
buildSupplyLookup: assertFn(contracts.module.buildSupplyLookup, 'buildSupplyLookup'),
|
package/src/integrations/read.ts
CHANGED
|
@@ -48,7 +48,7 @@ export async function readIntegrationsStrict(
|
|
|
48
48
|
if (contracts.strictValidation && contracts.module.parseIntegrationsConfig) {
|
|
49
49
|
// 严格链:assertNoInlineSecrets → 旧键直切防线 → zod strict(contracts 单源);
|
|
50
50
|
// 失败转换(A1——裸 ZodError/Error 穿透 500 的同族缺口):zod → 400 + fields(原始路径——
|
|
51
|
-
// 文件级读无节点上下文);普通 Error → 400 直通。结构性判定同 write.
|
|
51
|
+
// 文件级读无节点上下文);普通 Error → 400 直通。结构性判定同 write.validateOrDegrade。
|
|
52
52
|
try {
|
|
53
53
|
const parsed = contracts.module.parseIntegrationsConfig(raw);
|
|
54
54
|
return { config: parsed as unknown as Record<string, unknown>, strict: true, contracts };
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { join, resolve } from 'node:path';
|
|
3
3
|
import Ajv from 'ajv';
|
|
4
|
-
import { resolveContractsForApp } from '../core/contracts-resolver.js';
|
|
4
|
+
import { resolveContractsForApp, contractsTier } from '../core/contracts-resolver.js';
|
|
5
5
|
import { stemToFilePath } from '../core/credential-format.js';
|
|
6
6
|
import type { FileCache } from '../core/file-cache.js';
|
|
7
7
|
import { writeAtomic } from '../core/fskit.js';
|
|
@@ -20,8 +20,8 @@ import type { IntegrationServiceIssue } from './predicate.js';
|
|
|
20
20
|
import { checkInstanceKeys } from './predicate.js';
|
|
21
21
|
import { isKnownService } from './read.js';
|
|
22
22
|
import { moduleOwnershipWritable } from './module-binding.js';
|
|
23
|
-
import { AppToolkitError } from '../core/errors.js';
|
|
24
|
-
import { MODULE_INTEGRATION_NODE_KEYS } from '../dto.js';
|
|
23
|
+
import { AppToolkitError, contractsNotResolvedMessage } from '../core/errors.js';
|
|
24
|
+
import { MODULE_INTEGRATION_NODE_KEYS, SERVICE_INTEGRATION_NODE_KEYS, SERVICE_INSTANCE_NODE_KEYS } from '../dto.js';
|
|
25
25
|
|
|
26
26
|
/**
|
|
27
27
|
* 写核心(write;FX-1c 管线重排—— 九步定序 + D-B2 语义 + 输入扩位):
|
|
@@ -148,6 +148,25 @@ function assertSafeInstanceKeys(node: Record<string, unknown>, writeOpts: WriteO
|
|
|
148
148
|
assertSafeMapKeys(writeOpts.credentialsByInstance, 'credentialsByInstance', false);
|
|
149
149
|
}
|
|
150
150
|
|
|
151
|
+
/** 节点键集纪律单点(0.8.2 降级写批):未知键 400——zod 未知键拒绝语义前移为静态检查,
|
|
152
|
+
* 两态一致(降级态无 zod 此为唯一形状防线;ok 态同码 400 先行、fields 更精确)。
|
|
153
|
+
* 维度边界:仅键集(键名 ∈ 白名单),不查值类型/嵌套形状——非对象值静默跳过由 zod
|
|
154
|
+
* (ok 态)/ 滞后校验(降级态,后装依赖 doctor/求值轴暴露)兜底。
|
|
155
|
+
* 锁步约束:allowed 须 ⊆ contracts zod 节点 schema 键集(tests 键集锁步用例锁定)。 */
|
|
156
|
+
function assertNodeKeys(node: unknown, allowed: readonly string[], where: string): void {
|
|
157
|
+
if (!node || typeof node !== 'object' || Array.isArray(node)) return;
|
|
158
|
+
for (const k of Object.keys(node as Record<string, unknown>)) {
|
|
159
|
+
if (!(allowed as readonly string[]).includes(k)) {
|
|
160
|
+
throw new AppToolkitError(
|
|
161
|
+
'VALIDATION_FAILED',
|
|
162
|
+
400,
|
|
163
|
+
`${where} 仅接受 ${allowed.join('/')} 键(收到 ${k})`,
|
|
164
|
+
[k],
|
|
165
|
+
);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
|
|
151
170
|
/** 写时读当前配置(cache 优先;缺席 → null——调用方决定骨架物化) */
|
|
152
171
|
function loadConfig(appDir: string, cache?: FileCache): Record<string, unknown> | null {
|
|
153
172
|
const file = join(appDir, INTEGRATIONS_FILE);
|
|
@@ -298,21 +317,36 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
|
|
|
298
317
|
.filter((p) => p.length > 0);
|
|
299
318
|
}
|
|
300
319
|
|
|
301
|
-
/**
|
|
302
|
-
*
|
|
303
|
-
*
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
320
|
+
/** 整文档校验三向(0.8.2 降级写批——runStrictValidation 重构为 contractsTier 分流):
|
|
321
|
+
* ok → contracts zod 严格校验(zod → 400 + fields 节点相对,A1 单点转换;普通 Error
|
|
322
|
+
* ——旧键直切/内联密钥防线——同族 400 message 直通;结构性 ZodError 判定禁 instanceof
|
|
323
|
+
* ——contracts 动态 import,类身份跨模块实例不可靠);degraded → 跳过 zod +
|
|
324
|
+
* STRICT_VALIDATION_SKIPPED warning(message = contractsNotResolvedMessage N1 单源——
|
|
325
|
+
* 装/构建指引随行,fail-visible);blocked → 防御式 503(工厂边缘 assertWritableContracts
|
|
326
|
+
* 应已拦截,此处兜底)。 */
|
|
327
|
+
function validateOrDegrade(next: Record<string, unknown>, issues: IntegrationServiceIssue[], prefix: string): void {
|
|
328
|
+
if (!strictContracts) {
|
|
307
329
|
throw new AppToolkitError(
|
|
308
330
|
'CONTRACTS_NOT_RESOLVED',
|
|
309
331
|
503,
|
|
310
|
-
'contracts
|
|
332
|
+
'contracts 严格校验面不可用——写路径门控失败(工厂边缘断言应先行拦截)',
|
|
311
333
|
);
|
|
312
334
|
}
|
|
313
|
-
|
|
335
|
+
const tier = contractsTier(strictContracts);
|
|
336
|
+
if (tier === 'blocked') {
|
|
337
|
+
throw new AppToolkitError('CONTRACTS_NOT_RESOLVED', 503, contractsNotResolvedMessage(strictContracts));
|
|
338
|
+
}
|
|
339
|
+
if (tier === 'degraded') {
|
|
340
|
+
issues.push({
|
|
341
|
+
severity: 'warning',
|
|
342
|
+
code: 'STRICT_VALIDATION_SKIPPED',
|
|
343
|
+
message: contractsNotResolvedMessage(strictContracts),
|
|
344
|
+
});
|
|
345
|
+
return;
|
|
346
|
+
}
|
|
314
347
|
try {
|
|
315
|
-
|
|
348
|
+
// tier ok 蕴含 parseIntegrationsConfig 在场(resolver strictValidation 判据 = 该导出在场)
|
|
349
|
+
strictContracts.module.parseIntegrationsConfig!(next);
|
|
316
350
|
} catch (err) {
|
|
317
351
|
if (err instanceof Error && Array.isArray((err as { issues?: unknown }).issues)) {
|
|
318
352
|
throw new AppToolkitError(
|
|
@@ -332,6 +366,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
|
|
|
332
366
|
applyApp(node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
|
|
333
367
|
assertSafeNames(node, 'root');
|
|
334
368
|
assertSafeInstanceKeys(node, writeOpts, 'root');
|
|
369
|
+
assertNodeKeys(node, APP_INTEGRATION_NODE_KEYS, 'root');
|
|
335
370
|
const issues: IntegrationServiceIssue[] = [];
|
|
336
371
|
const current = loadConfig(appDir, cache);
|
|
337
372
|
const base: Record<string, unknown> = current ?? { services: {} };
|
|
@@ -343,7 +378,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
|
|
|
343
378
|
});
|
|
344
379
|
}
|
|
345
380
|
// root 全量替换(无例外语义):缺席根键删除(services/modules 域不在根键集——随 base 保留;v6 domains 键已退役),
|
|
346
|
-
// node
|
|
381
|
+
// node 全键置入(未知键已被 assertNodeKeys 前置 400——0.9.0 键集静态防线;B10:原实现 spread+merge 残留 stale 根键)
|
|
347
382
|
const next: Record<string, unknown> = { ...base };
|
|
348
383
|
for (const k of APP_INTEGRATION_NODE_KEYS) if (!(k in node)) delete next[k];
|
|
349
384
|
for (const [k, v] of Object.entries(node)) next[k] = v;
|
|
@@ -366,7 +401,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
|
|
|
366
401
|
if (noDiff && !hasCredentialInput) {
|
|
367
402
|
return { written: false, restartScheduled: false, files: [], credentials: [], issues };
|
|
368
403
|
}
|
|
369
|
-
|
|
404
|
+
validateOrDegrade(next, issues, '');
|
|
370
405
|
// 凭据工件落盘(后置于校验通过;dryRun 零写盘 + existsSync 预览)
|
|
371
406
|
const dryRun = writeOpts.dryRun === true;
|
|
372
407
|
const applied = writeCredentialArtifacts(appDir, plan, dryRun);
|
|
@@ -409,17 +444,8 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
|
|
|
409
444
|
const base: Record<string, unknown> = current ?? { services: {} };
|
|
410
445
|
const modulesNode = { ...((base.modules as Record<string, unknown>) ?? {}) };
|
|
411
446
|
const existing = { ...((modulesNode[moduleId] as Record<string, unknown> | undefined) ?? {}) };
|
|
412
|
-
//
|
|
413
|
-
|
|
414
|
-
if (!(MODULE_INTEGRATION_NODE_KEYS as readonly string[]).includes(k)) {
|
|
415
|
-
throw new AppToolkitError(
|
|
416
|
-
'VALIDATION_FAILED',
|
|
417
|
-
400,
|
|
418
|
-
`模块集成位仅接受 ${MODULE_INTEGRATION_NODE_KEYS.join('/')} 键(收到 ${k})`,
|
|
419
|
-
[k],
|
|
420
|
-
);
|
|
421
|
-
}
|
|
422
|
-
}
|
|
447
|
+
// 键集纪律(assertNodeKeys 单点——无条件两态一致 400;resources 不属可写键集恒保全)
|
|
448
|
+
assertNodeKeys(node, MODULE_INTEGRATION_NODE_KEYS, `modules.${moduleId}`);
|
|
423
449
|
// 全量替换(键集内):缺席键删除;空对象/空串值 = 删除(≡ 缺席——模块节点不留空键);
|
|
424
450
|
// PUT {} = 清 provider/config,resources 恒随 existing 保全(N2:清集成位不杀资源绑定)
|
|
425
451
|
const nextNode: Record<string, unknown> = { ...existing };
|
|
@@ -439,7 +465,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
|
|
|
439
465
|
if (deepEqual(current, next)) {
|
|
440
466
|
return { written: false, restartScheduled: false, files: [], credentials: [], issues };
|
|
441
467
|
}
|
|
442
|
-
|
|
468
|
+
validateOrDegrade(next, issues, `modules.${moduleId}.`);
|
|
443
469
|
issues.push(...registryCheck(next));
|
|
444
470
|
return finalize(next, [], issues, writeOpts.dryRun);
|
|
445
471
|
},
|
|
@@ -447,6 +473,12 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
|
|
|
447
473
|
applyService(service: string, node: Record<string, unknown>, writeOpts: WriteOptions = {}): SaveResult {
|
|
448
474
|
assertSafeNames(node, 'root');
|
|
449
475
|
assertSafeInstanceKeys(node, writeOpts, 'slot');
|
|
476
|
+
// 键集纪律(assertNodeKeys 单点):节点位 + 实例位双层('*' 为 instances map 键位,
|
|
477
|
+
// 不属实例节点键集;实例 map 键字符集归 assertSafeInstanceKeys)
|
|
478
|
+
assertNodeKeys(node, SERVICE_INTEGRATION_NODE_KEYS, `services.${service}`);
|
|
479
|
+
for (const [k, inst] of Object.entries((node.instances as Record<string, Record<string, unknown>> | undefined) ?? {})) {
|
|
480
|
+
assertNodeKeys(inst, SERVICE_INSTANCE_NODE_KEYS, `services.${service}.instances.${k}`);
|
|
481
|
+
}
|
|
450
482
|
const issues: IntegrationServiceIssue[] = [];
|
|
451
483
|
const current = loadConfig(appDir, cache);
|
|
452
484
|
// 服务身份判据单源(A2):写入集 = 词汇 ∪ 已配置 ∪ 归属——未知服务(含 typo)404(api.md §5;
|
|
@@ -496,7 +528,7 @@ export function createWriteCore(appDir: string, opts: WriteCoreOptions = {}): Wr
|
|
|
496
528
|
if (noDiff && !hasCredentialInput) {
|
|
497
529
|
return { written: false, restartScheduled: false, files: [], credentials: [], issues };
|
|
498
530
|
}
|
|
499
|
-
|
|
531
|
+
validateOrDegrade(next, issues, `services.${service}.`);
|
|
500
532
|
// 凭据工件落盘(后置于校验通过;dryRun 零写盘 + existsSync 预览)
|
|
501
533
|
const dryRun = writeOpts.dryRun === true;
|
|
502
534
|
const applied = writeCredentialArtifacts(appDir, plan, dryRun);
|
|
@@ -39,6 +39,7 @@ function toContractsResolution(contracts: ResolvedContracts): ContractsResolutio
|
|
|
39
39
|
version: contracts.version,
|
|
40
40
|
evaluation: contracts.evaluation,
|
|
41
41
|
strictValidation: contracts.strictValidation,
|
|
42
|
+
ownershipBindingV6: contracts.ownershipBindingV6,
|
|
42
43
|
notes: [...contracts.notes],
|
|
43
44
|
};
|
|
44
45
|
}
|
|
@@ -369,9 +370,10 @@ export type { IntegrationIssue };
|
|
|
369
370
|
// contracts 不可用(未安装 / 无严格面 / 求值面缺席 / v6 标记缺席)时,读求值轴不再 503,
|
|
370
371
|
// 改投静态骨架(walk + integrations 纯文件投影,零 contracts 依赖)+ evaluation-unavailable 标记。
|
|
371
372
|
// 依据链:doctor 分级先例(未安装 = warning 正常态)+ include→null 先例;fail-visible 语义
|
|
372
|
-
// 保留在数据内(status + statusMessage N1 分支文案),写路径与 internals
|
|
373
|
+
// 保留在数据内(status + statusMessage N1 分支文案),写路径与 internals 门控不变(0.8.2 降级
|
|
374
|
+
// 写批起写轴分层演进:version null 降级写 / blocked 503——见 Agent Note write-axis-degrade)。
|
|
373
375
|
|
|
374
|
-
/** 读求值轴可用判据(三条件与——降级门单源;写路径
|
|
376
|
+
/** 读求值轴可用判据(三条件与——降级门单源;写路径 assertWritableContracts 另有 503 语义,不复用) */
|
|
375
377
|
export function contractsEvaluable(contracts: ResolvedContracts): boolean {
|
|
376
378
|
return contracts.evaluation && contracts.strictValidation && contracts.ownershipBindingV6;
|
|
377
379
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { describe, it, expect, beforeEach } from 'vitest';
|
|
2
2
|
import { mkdirSync, writeFileSync, readFileSync, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
|
|
3
3
|
import { join } from 'node:path';
|
|
4
|
-
import { resolveContractsForApp, invalidateContractsResolver } from '../src/core/contracts-resolver.js';
|
|
4
|
+
import { resolveContractsForApp, invalidateContractsResolver, contractsTier } from '../src/core/contracts-resolver.js';
|
|
5
5
|
import {
|
|
6
6
|
bumpMtime,
|
|
7
7
|
createTempApp,
|
|
@@ -201,3 +201,18 @@ describe('contracts-resolver(D3 方案心脏)', () => {
|
|
|
201
201
|
expect(after.strictValidation).toBe(true);
|
|
202
202
|
});
|
|
203
203
|
});
|
|
204
|
+
|
|
205
|
+
describe('contractsTier 状态机(0.8.2 降级写批——穷举锁)', () => {
|
|
206
|
+
it('四可达组合 + 畸形保守 blocked(version-null 分界轴:无包可依 = degraded,包在场能力缺失 = blocked)', () => {
|
|
207
|
+
// 未安装/未构建/导入拒绝(UNRESOLVED 形态)——唯一降级放行态
|
|
208
|
+
expect(contractsTier({ version: null, strictValidation: false, ownershipBindingV6: false })).toBe('degraded');
|
|
209
|
+
// 健康全绿
|
|
210
|
+
expect(contractsTier({ version: '0.13.0', strictValidation: true, ownershipBindingV6: true })).toBe('ok');
|
|
211
|
+
// <0.9 已装(v5 旧代码在场——v6 形状写入静默无效)
|
|
212
|
+
expect(contractsTier({ version: '0.8.2', strictValidation: false, ownershipBindingV6: false })).toBe('blocked');
|
|
213
|
+
// 偏斜(≥0.9 缺 OWNERSHIP_BINDING_V6 标记——v6 形状被旧 zod 拒)
|
|
214
|
+
expect(contractsTier({ version: '0.9.0', strictValidation: true, ownershipBindingV6: false })).toBe('blocked');
|
|
215
|
+
// 畸形(有标记无严格面——现实中不可达,保守 blocked)
|
|
216
|
+
expect(contractsTier({ version: '0.13.0', strictValidation: false, ownershipBindingV6: true })).toBe('blocked');
|
|
217
|
+
});
|
|
218
|
+
});
|
package/tests/demo-app.ts
CHANGED
|
@@ -76,7 +76,7 @@ export interface FakeContractsOptions {
|
|
|
76
76
|
* 入参 (integrations, service, instanceId, supplies, ownerOf),需 return EffectiveServiceResolution 形状) */
|
|
77
77
|
resolveBody?: string;
|
|
78
78
|
/** v6 形状标记(OWNERSHIP_BINDING_V6)缺席 fixture——默认在场(v6 假件签名随动 N11);
|
|
79
|
-
* false = v5 contracts 形态(ownershipBindingV6: false →
|
|
79
|
+
* false = v5 contracts 形态(ownershipBindingV6: false → contractsTier blocked 503——写轴阻断保留) */
|
|
80
80
|
withMarker?: boolean;
|
|
81
81
|
/** service-slots.json 词汇(P9 身份判据/求值键集;缺省不物化 = 词汇空) */
|
|
82
82
|
slots?: string[];
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import { describe, it, expect } from 'vitest';
|
|
2
|
+
import {
|
|
3
|
+
APP_INTEGRATION_NODE_KEYS,
|
|
4
|
+
MODULE_INTEGRATION_NODE_KEYS,
|
|
5
|
+
SERVICE_INTEGRATION_NODE_KEYS,
|
|
6
|
+
SERVICE_INSTANCE_NODE_KEYS,
|
|
7
|
+
} from '../src/dto.js';
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* 键集-zod 锁步(0.8.2 降级写批——assertNodeKeys 白名单 ⊆ contracts zod 键集的行为锁):
|
|
11
|
+
* 以真实 @tbox.cn/app-contracts(devDep workspace 态)parseIntegrationsConfig 逐键验证——
|
|
12
|
+
* 常数键全过 zod(证明白名单不隐性收窄 ok 态行为)+ 未知键恰被 zod 拒(证明静态防线与
|
|
13
|
+
* 严格面收敛、降级态无隐性放行)。contracts zod 键集演进(additive)时本测试即锁步哨兵:
|
|
14
|
+
* 常数漏跟 = 红。
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
// dist 在场才锁步(contracts dist 为 gitignore——fresh clone / CI verify 无 build 步骤时 import 必败;
|
|
18
|
+
// 无 contracts 代码 = 无锁步对象,skip 可接受。本地有 dist 或发布链 prepack build 后自动激活)。
|
|
19
|
+
let parseIntegrationsConfig: ((raw: unknown) => unknown) | undefined;
|
|
20
|
+
try {
|
|
21
|
+
parseIntegrationsConfig = ((await import('@tbox.cn/app-contracts')) as {
|
|
22
|
+
parseIntegrationsConfig: (raw: unknown) => unknown;
|
|
23
|
+
}).parseIntegrationsConfig;
|
|
24
|
+
} catch {
|
|
25
|
+
// skip:contracts 未构建
|
|
26
|
+
}
|
|
27
|
+
const expectZodPass = (doc: unknown): void => expect(() => parseIntegrationsConfig!(doc)).not.toThrow();
|
|
28
|
+
const expectZodReject = (doc: unknown): void => expect(() => parseIntegrationsConfig!(doc)).toThrow();
|
|
29
|
+
|
|
30
|
+
describe.skipIf(parseIntegrationsConfig === undefined)('键集-zod 锁步(assertNodeKeys 白名单 ⊆ contracts zod)', () => {
|
|
31
|
+
it('app 节点:APP_INTEGRATION_NODE_KEYS 全键过 zod;未知键被 zod 拒', () => {
|
|
32
|
+
const full: Record<string, unknown> = { services: {} };
|
|
33
|
+
for (const k of APP_INTEGRATION_NODE_KEYS) {
|
|
34
|
+
full[k] =
|
|
35
|
+
k === 'instances'
|
|
36
|
+
? [{ id: 'mall-bj-01', name: 'bj' }]
|
|
37
|
+
: k === 'defaultInstanceId'
|
|
38
|
+
? 'mall-bj-01'
|
|
39
|
+
: k === 'provider'
|
|
40
|
+
? 'mock'
|
|
41
|
+
: k === 'credentialRef'
|
|
42
|
+
? 'secret://a-b-0'
|
|
43
|
+
: k === 'credentialRefByInstance'
|
|
44
|
+
? { 'mall-bj-01': 'secret://a-b-0' }
|
|
45
|
+
: k === 'configByInstance'
|
|
46
|
+
? { 'mall-bj-01': {} }
|
|
47
|
+
: {};
|
|
48
|
+
}
|
|
49
|
+
expectZodPass(full);
|
|
50
|
+
expectZodReject({ services: {}, unknownKey: 1 });
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
it('service 节点:SERVICE_INTEGRATION_NODE_KEYS 全键过 zod;未知键被 zod 拒', () => {
|
|
54
|
+
const slot: Record<string, unknown> = {};
|
|
55
|
+
for (const k of SERVICE_INTEGRATION_NODE_KEYS) {
|
|
56
|
+
slot[k] =
|
|
57
|
+
k === 'provider'
|
|
58
|
+
? 'mock'
|
|
59
|
+
: k === 'implementation'
|
|
60
|
+
? 'mock.impl'
|
|
61
|
+
: k === 'credentialRef'
|
|
62
|
+
? 'secret://a-b-0'
|
|
63
|
+
: {};
|
|
64
|
+
}
|
|
65
|
+
expectZodPass({ services: { 'x.y': slot } });
|
|
66
|
+
expectZodReject({ services: { 'x.y': { ...slot, unknownKey: 1 } } });
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
it('instance 节点:SERVICE_INSTANCE_NODE_KEYS 全键过 zod;未知键被 zod 拒', () => {
|
|
70
|
+
const inst: Record<string, unknown> = {};
|
|
71
|
+
for (const k of SERVICE_INSTANCE_NODE_KEYS) {
|
|
72
|
+
inst[k] =
|
|
73
|
+
k === 'provider'
|
|
74
|
+
? 'mock'
|
|
75
|
+
: k === 'implementation'
|
|
76
|
+
? 'mock.impl'
|
|
77
|
+
: k === 'credentialRef'
|
|
78
|
+
? 'secret://a-b-0'
|
|
79
|
+
: k === 'enabled'
|
|
80
|
+
? true
|
|
81
|
+
: {};
|
|
82
|
+
}
|
|
83
|
+
expectZodPass({ services: { 'x.y': { instances: { 'mall-bj-01': inst } } } });
|
|
84
|
+
expectZodReject({ services: { 'x.y': { instances: { 'mall-bj-01': { ...inst, unknownKey: 1 } } } } });
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
it('module 节点:MODULE_INTEGRATION_NODE_KEYS 全键过 zod;未知键被 zod 拒', () => {
|
|
88
|
+
const mod: Record<string, unknown> = {};
|
|
89
|
+
for (const k of MODULE_INTEGRATION_NODE_KEYS) {
|
|
90
|
+
mod[k] = k === 'provider' ? 'mock' : {};
|
|
91
|
+
}
|
|
92
|
+
expectZodPass({ services: {}, modules: { 'module-x': mod } });
|
|
93
|
+
expectZodReject({ services: {}, modules: { 'module-x': { ...mod, unknownKey: 1 } } });
|
|
94
|
+
});
|
|
95
|
+
});
|
package/tests/views.test.ts
CHANGED
|
@@ -467,6 +467,8 @@ describe('views/工厂(O 矩阵核心族)', () => {
|
|
|
467
467
|
// 正例:≥0.9 求值可用(harness 默认)
|
|
468
468
|
const batch = await h.tk.loadServiceResolutions();
|
|
469
469
|
expect(batch.contracts.strictValidation).toBe(true);
|
|
470
|
+
// 0.8.2 降级写批:echo 投影 obv6 判据(toContractsResolution 单点——前端降级判定镜像源)
|
|
471
|
+
expect(batch.contracts.ownershipBindingV6).toBe(true);
|
|
470
472
|
h.app.dispose();
|
|
471
473
|
|
|
472
474
|
// 反例:缺 zod 面(0.8.2)→ 读求值轴降级骨架 + N1 升级指引入 statusMessage;静态照常
|
|
@@ -481,7 +483,8 @@ describe('views/工厂(O 矩阵核心族)', () => {
|
|
|
481
483
|
// 静态永不 503
|
|
482
484
|
const appView = await low.tk.loadApp();
|
|
483
485
|
expect(appView.services).toBeInstanceOf(Array);
|
|
484
|
-
// 写端点 503
|
|
486
|
+
// 写端点 blocked 503 保留(0.8.2 降级写批——version '0.8.2' 非空 = 旧代码在场:503 升级指引不变;
|
|
487
|
+
// version null 态(未装/未构建)降级放行见 write-core 降级写批 describe)
|
|
485
488
|
await expect(
|
|
486
489
|
low.tk.writeServiceIntegration('parking.query', { provider: 'mock' }),
|
|
487
490
|
).rejects.toMatchObject({ code: 'CONTRACTS_NOT_RESOLVED', httpStatus: 503 });
|
|
@@ -1180,7 +1183,7 @@ describe('v6 所有权族(D34 多域钉死退役 → ownedServices/binding 单
|
|
|
1180
1183
|
}));
|
|
1181
1184
|
writeAppFile(app.appDir, 'config/integrations.json', JSON.stringify({ provider: 'mock', services: { 'parking.query': {} } }));
|
|
1182
1185
|
const tk = createAppToolkit(app.appDir);
|
|
1183
|
-
//
|
|
1186
|
+
// 写路径 blocked 门控保留(assertWritableContracts——contractsTier 判据单源,偏斜 503 不变)
|
|
1184
1187
|
await expect(tk.writeModuleIntegration('module-parking', { provider: 'wanda' })).rejects.toMatchObject({
|
|
1185
1188
|
code: 'CONTRACTS_NOT_RESOLVED',
|
|
1186
1189
|
httpStatus: 503,
|
|
@@ -1189,6 +1192,8 @@ describe('v6 所有权族(D34 多域钉死退役 → ownedServices/binding 单
|
|
|
1189
1192
|
// 读求值轴降级(503 退役):statusMessage 与写门控同源(N1 标记分支单源)
|
|
1190
1193
|
const degraded = await tk.loadServiceResolutions();
|
|
1191
1194
|
expect(degraded.contracts.strictValidation).toBe(true);
|
|
1195
|
+
// 偏斜态 echo 投影 obv6 = false(三绿假象破除——前端 blocked 判据唯一信号源)
|
|
1196
|
+
expect(degraded.contracts.ownershipBindingV6).toBe(false);
|
|
1192
1197
|
const entry = degraded.resolutions['parking.query'];
|
|
1193
1198
|
expect(entry.status).toBe('evaluation-unavailable');
|
|
1194
1199
|
expect(entry.statusMessage).toMatch(/OWNERSHIP_BINDING_V6 标记缺席/);
|