Skip to content

Commit d108bd0

Browse files
committed
feat(cli): os validate refuses a field patch naming a field or option its in-stack target lacks; changeset
Claude-Session: https://claude.ai/code/session_01FEkQ5nSMgkteiemkoN31vf Co-authored-by: Claude <noreply@anthropic.com>
1 parent 26ce8d6 commit d108bd0

5 files changed

Lines changed: 273 additions & 0 deletions

File tree

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
'@objectstack/objectql': minor
3+
'@objectstack/metadata-core': minor
4+
'@objectstack/cloud-connection': minor
5+
'@objectstack/cli': minor
6+
'@objectstack/spec': minor
7+
---
8+
9+
feat(objectql): an object extension's `fieldPatches` is applied on every object read; a patch naming a field or option its target lacks is refused at install and by `os validate`
10+
11+
Clause-②: no
12+
Metadata-protocol: semantic
13+
14+
ADR-0146 D10's second rule, live. The per-field display patch an object extension declares (`objectExtensions[].fieldPatches`, added unenforced in the previous release) now reaches the screen:
15+
16+
```ts
17+
objectExtensions: [{
18+
extend: 'crm_account',
19+
fieldPatches: {
20+
industry: { label: 'Sector', inlineHelpText: 'The market the account sells into', options: { tech: { label: 'Technology' } } },
21+
},
22+
}]
23+
```
24+
25+
- **Applied, never carried.** The engine's extension registration carries the slot, and the registry merge (`mergeObjectDefinitions`) applies it after the additive merges: the `BASE_FIELD_DISPLAY_WHITELIST` keys (`label`, `description`, `inlineHelpText`, `placeholder`) onto the named field, and `label` onto each option addressed by its stored `value`. The field's type, requiredness, options and values stay the owner's. The list read, the by-name read and the layered view serve the same text, and uninstalling the extension serves the owner's text again.
26+
- **Precedence.** A key the tenant has edited keeps the tenant's text (ADR-0029 D9.2a, as for an extension's object `label`). Two extensions patching one key: the higher `priority` wins.
27+
- **Refused when it names nothing.** A patch naming a field the target does not have, an option value its field does not have, or an option of a picklist-bound field is refused at `POST /api/v1/marketplace/install-local` (`400 VALIDATION_ERROR`, every refusal located in `error.details.refusals`, nothing installed) and by `os validate` when the target is in the same stack. At boot such a patch is not applied and is named once in the log; the boot carries on.
28+
- **New export.** `@objectstack/metadata-core` exports the one judge the three readers share: `fieldPatchTargetMisses`, `fieldPatchTargetRefusals`, `fieldPatchTargetRefusalMessage`.
29+
30+
What changes for an existing package: a package that declared `fieldPatches` since the slot landed now sees them applied, and one whose patch names a missing field or option is now refused at install. An extension without `fieldPatches` folds exactly as before.

‎packages/cli/src/commands/validate.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,9 @@ import { findViewContainerNameRefusals } from '../utils/view-container-names.js'
7777
// [ADR-0146 D2, #28410] The override write gate's author-time half: the publish
7878
// door's own judge, walked over the artifact's packages.
7979
import { findOverrideDeclarationRefusals } from '../utils/override-declarations.js';
80+
// [ADR-0146 D10, second rule] The field-patch target check's walk; the verdict
81+
// is the marketplace install door's own judge.
82+
import { findFieldPatchTargetRefusals } from '../utils/field-patch-targets.js';
8083
// A field `picklist` that names no picklist the stack declares — refused, or
8184
// reported when the declaring package depends on packages outside the stack.
8285
// Walked the way the load path registers, like the refusal above.
@@ -690,6 +693,35 @@ export default class Validate extends Command {
690693
this.exit(1);
691694
}
692695

696+
// 3a-iv. [ADR-0146 D10, second rule] The field-patch target check, at
697+
// author time: an object extension's `fieldPatches` naming a field
698+
// its target does not have, or an option value the field does not
699+
// have, when the target is in this composed stack. The verdict is the
700+
// install door's own judge (`fieldPatchTargetRefusals`), so a green
701+
// validate is a patch the install door admits; see
702+
// `utils/field-patch-targets.ts` for the walk.
703+
const patchTargetRefusals = findFieldPatchTargetRefusals(result.data as Record<string, unknown>);
704+
if (patchTargetRefusals.length > 0) {
705+
if (flags.json) {
706+
await emitJson({
707+
valid: false,
708+
errors: patchTargetRefusals,
709+
warnings: warningsSoFar(),
710+
conversions: conversionNotices,
711+
duration: timer.elapsed(),
712+
});
713+
this.exit(1);
714+
}
715+
const n = patchTargetRefusals.length;
716+
console.log('');
717+
printError(`${n} field patch${n > 1 ? 'es name' : ' names'} a field or option the extended object does not have (ADR-0146 D10)`);
718+
printBulletList(
719+
patchTargetRefusals.map((r) => `${r.path} ${r.message}`),
720+
{ noun: 'field-patch refusal(s)', remedy: JSON_FULL_LIST_REMEDY },
721+
);
722+
this.exit(1);
723+
}
724+
693725
// 3b. [#3366] Installable-provider preflight — the shift-left of the
694726
// `serve`-time capability check. `os validate` previously only checked
695727
// the `requires` tokens against the vocabulary (ADR-0066), never
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [ADR-0146 D10, second rule] `os validate`'s walk for the field-patch target
5+
* check: which objects the composed stack declares and which extensions each
6+
* package carries. The verdict is `@objectstack/metadata-core`'s own judge.
7+
*/
8+
9+
import { describe, it, expect } from 'vitest';
10+
import { findFieldPatchTargetRefusals } from './field-patch-targets.js';
11+
12+
const account = {
13+
name: 'fpt_account',
14+
fields: {
15+
industry: { type: 'select', label: 'Industry', options: [{ value: 'tech', label: 'Tech' }] },
16+
},
17+
};
18+
19+
describe('findFieldPatchTargetRefusals', () => {
20+
it('judges an extension of an object the stack declares', () => {
21+
const refusals = findFieldPatchTargetRefusals({
22+
objects: [account],
23+
objectExtensions: [{ extend: 'fpt_account', fieldPatches: { sector: { label: 'Sector' }, industry: { options: { retail: { label: 'R' } } } } }],
24+
});
25+
expect(refusals.map((r) => r.path)).toEqual([
26+
'objectExtensions[0].fieldPatches.sector',
27+
'objectExtensions[0].fieldPatches.industry.options.retail',
28+
]);
29+
});
30+
31+
it('admits a patch whose field and option the target has', () => {
32+
expect(findFieldPatchTargetRefusals({
33+
objects: [account],
34+
objectExtensions: [{ extend: 'fpt_account', fieldPatches: { industry: { label: 'Sector', options: { tech: { label: 'Technology' } } } } }],
35+
})).toEqual([]);
36+
});
37+
38+
it('leaves a target outside the composed stack to the install door', () => {
39+
expect(findFieldPatchTargetRefusals({
40+
objectExtensions: [{ extend: 'crm_account', fieldPatches: { anything: { label: 'X' } } }],
41+
})).toEqual([]);
42+
});
43+
44+
it('reads a target another packages[] entry declares, and locates the refusal under its own entry', () => {
45+
const refusals = findFieldPatchTargetRefusals({
46+
packages: [
47+
{ manifest: { id: 'com.acme.core', objects: [account] } },
48+
{ manifest: { id: 'com.acme.wording', objectExtensions: [{ extend: 'fpt_account', fieldPatches: { sector: { label: 'Sector' } } }] } },
49+
],
50+
});
51+
expect(refusals.map((r) => r.path)).toEqual(['packages[1].manifest.objectExtensions[0].fieldPatches.sector']);
52+
});
53+
54+
it('reads a name-keyed objects map', () => {
55+
const { name: _name, ...body } = account;
56+
expect(findFieldPatchTargetRefusals({
57+
objects: { fpt_account: body },
58+
objectExtensions: [{ extend: 'fpt_account', fieldPatches: { sector: { label: 'Sector' } } }],
59+
})).toHaveLength(1);
60+
});
61+
});
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* `os validate`'s half of the field-patch target check (ADR-0146 D10, second
5+
* rule): an object extension's `fieldPatches` naming a field its target does
6+
* not have, or an option value the field does not have, is refused when the
7+
* target is in the composed stack.
8+
*
9+
* ## One judge, not a second rule
10+
*
11+
* The verdict is `@objectstack/metadata-core`'s `fieldPatchTargetRefusals`, the
12+
* SAME judge the marketplace install door refuses by and the registry fold
13+
* names its boot-time misses by. What this module owns is the WALK: which
14+
* objects the composed stack declares — its own, or every `packages[]` entry's
15+
* (ADR-0130 D4) — and which extensions each package carries. A target outside
16+
* the stack is not judged here; the install door judges it against the
17+
* installed base.
18+
*/
19+
20+
import { fieldPatchTargetRefusals, type FieldPatchTargetRefusal } from '@objectstack/metadata-core';
21+
22+
import { artifactPackages } from './artifact-packages.js';
23+
24+
const isRecord = (v: unknown): v is Record<string, unknown> =>
25+
v !== null && typeof v === 'object' && !Array.isArray(v);
26+
27+
/** The objects a stack body declares, by name — a list of definitions or a name-keyed map. */
28+
function declaredObjects(body: Record<string, unknown>): Array<[string, unknown]> {
29+
const objects = body.objects;
30+
if (Array.isArray(objects)) {
31+
return objects.flatMap((o) => (isRecord(o) && typeof o.name === 'string' ? [[o.name, o] as [string, unknown]] : []));
32+
}
33+
return isRecord(objects) ? Object.entries(objects) : [];
34+
}
35+
36+
/** Every field patch in the parsed stack that names what its in-stack target lacks, located. */
37+
export function findFieldPatchTargetRefusals(parsed: Record<string, unknown>): FieldPatchTargetRefusal[] {
38+
const entries = artifactPackages(parsed);
39+
const bodies = entries.length > 0
40+
? entries.map(({ index, body }) => ({ body, prefix: `packages[${index}].manifest.` }))
41+
: [{ body: parsed, prefix: '' }];
42+
const composed = new Map<string, unknown>();
43+
for (const { body } of bodies) for (const [name, object] of declaredObjects(body)) composed.set(name, object);
44+
return bodies.flatMap(({ body, prefix }) =>
45+
fieldPatchTargetRefusals(body.objectExtensions, (name) => composed.get(name), prefix));
46+
}
Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* [ADR-0146 D10, second rule] `os validate` asks the field-patch target check —
5+
* the install door's own judge (`fieldPatchTargetRefusals`), over the walk
6+
* `utils/field-patch-targets.ts` takes, whose own file pins which targets it
7+
* reads. What is pinned here is the command: a stack whose object extension
8+
* patches a field or option value its in-stack target lacks exits 1, each
9+
* refusal located on `errors`; the same stack patching what exists validates
10+
* clean.
11+
*/
12+
13+
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
14+
import { execFile } from 'node:child_process';
15+
import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
16+
import { tmpdir } from 'node:os';
17+
import { join, resolve } from 'node:path';
18+
import { fileURLToPath } from 'node:url';
19+
import { childEnv } from './helpers/serve-process.js';
20+
import { linkSpec } from './helpers/define-stack-fixture.js';
21+
22+
const HERE = resolve(fileURLToPath(import.meta.url), '..');
23+
const CLI = resolve(HERE, '../bin/run-dev.js');
24+
const TSX = resolve(HERE, '../../../node_modules/.bin/tsx');
25+
26+
const stack = (fieldPatches: string) => `
27+
import { defineStack } from '@objectstack/spec';
28+
29+
export default defineStack({
30+
manifest: { id: 'com.acme.fpt', name: 'fpt', version: '1.0.0', type: 'app', namespace: 'fpt' },
31+
objects: [{
32+
name: 'fpt_account',
33+
label: 'Account',
34+
fields: {
35+
name: { type: 'text', label: 'Name' },
36+
industry: { type: 'select', label: 'Industry', options: [{ value: 'tech', label: 'Tech' }, { value: 'retail', label: 'Retail' }] },
37+
},
38+
}],
39+
objectExtensions: [{ extend: 'fpt_account', fieldPatches: ${fieldPatches} }],
40+
}, { strict: false });
41+
`;
42+
43+
interface Run {
44+
code: number;
45+
stdout: string;
46+
stderr: string;
47+
}
48+
49+
function runValidate(cwd: string): Promise<Run> {
50+
return new Promise((resolvePromise) => {
51+
execFile(
52+
TSX,
53+
[CLI, 'validate', '--json'],
54+
// `childEnv()`, never a bulk `process.env` copy (check:cli-test-child-env).
55+
{ cwd, maxBuffer: 16 * 1024 * 1024, env: childEnv({ NO_COLOR: '1' }) },
56+
(err, stdout, stderr) => {
57+
resolvePromise({
58+
code: err ? (typeof (err as { code?: unknown }).code === 'number' ? (err as unknown as { code: number }).code : 1) : 0,
59+
stdout: String(stdout),
60+
stderr: String(stderr),
61+
});
62+
},
63+
);
64+
});
65+
}
66+
67+
let missingDir: string;
68+
let matchingDir: string;
69+
70+
beforeAll(() => {
71+
missingDir = mkdtempSync(join(tmpdir(), 'os-validate-fpt-missing-'));
72+
writeFileSync(join(missingDir, 'objectstack.config.ts'),
73+
stack(`{ sector: { label: 'Sector' }, industry: { options: { finance: { label: 'Finance' } } } }`));
74+
linkSpec(missingDir);
75+
matchingDir = mkdtempSync(join(tmpdir(), 'os-validate-fpt-matching-'));
76+
writeFileSync(join(matchingDir, 'objectstack.config.ts'),
77+
stack(`{ industry: { label: 'Sector', options: { tech: { label: 'Technology' } } } }`));
78+
linkSpec(matchingDir);
79+
});
80+
81+
afterAll(() => {
82+
rmSync(missingDir, { recursive: true, force: true });
83+
rmSync(matchingDir, { recursive: true, force: true });
84+
});
85+
86+
describe('os validate — the field-patch target check (ADR-0146 D10)', () => {
87+
it('exits 1 with each patch naming a missing field or option value located on errors', async () => {
88+
const run = await runValidate(missingDir);
89+
expect(run.code, run.stderr).toBe(1);
90+
const report = JSON.parse(run.stdout);
91+
expect(report.valid).toBe(false);
92+
expect(report.errors.map((e: { path: string }) => e.path)).toEqual([
93+
'objectExtensions[0].fieldPatches.sector',
94+
'objectExtensions[0].fieldPatches.industry.options.finance',
95+
]);
96+
expect(report.errors.map((e: { reason: string }) => e.reason)).toEqual(['field', 'option']);
97+
});
98+
99+
it('validates clean when the patch names a field and option value the target has', async () => {
100+
const run = await runValidate(matchingDir);
101+
expect(run.code, `${run.stdout}\n${run.stderr}`).toBe(0);
102+
expect(JSON.parse(run.stdout).valid).toBe(true);
103+
});
104+
});

0 commit comments

Comments
 (0)