Skip to content

Commit 7449e47

Browse files
fix(cloud-connection)!: install-local reads the manifest of a compiled artifact as os package install sends it, so the protocol handshake runs on it (#28603)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"} --> _Requested by **Leehom** · [project thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XTijUU5k4PYDn5KvdsA1jjC)_ Fixes #28535 Clause-②: no (narrowing) — `POST /api/v1/marketplace/install-local` refuses, with the 422 `OS_PROTOCOL_INCOMPATIBLE` (or `DEPENDENCY_MISSING`) a flat manifest already got, a compiled artifact sent with `id` and `version` lifted beside its nested `manifest` (the body `os package install ./dist/objectstack.json` sends) whose `engines.protocol` excludes this runtime or whose `dependencies` this runtime does not satisfy. That body installed before. Nothing is widened. Metadata-protocol: none Skills-docs: none — the pages already state the behaviour this restores: `skills/objectstack-platform/SKILL.md` ("The runtime checks it before it loads anything and refuses an out-of-range app at the boundary") and `content/docs/protocol/kernel/plugin-spec.mdx` ("the pre-install dependency check every install door runs"). No page described the CLI path as an exception. **BREAKING** accept-set narrowing at `POST /api/v1/marketplace/install-local` (`@objectstack/cloud-connection`), reached by `os package install ./dist/objectstack.json`. ## 维护者速读 - **改了什么**:离线安装接口(`POST /api/v1/marketplace/install-local`)现在按「body 里是否有嵌套的 `manifest` 对象」识别编译产物并展平,不再要求顶层没有 `id`/`name`。`os package install ./dist/objectstack.json` 发来的产物因此会被展平,协议握手(`engines.protocol`)和依赖检查(`dependencies`)都读得到真实值。CLI 不改。 - **为什么改**:卡 #28535(分诊 6554172575):CLI 把 `id`、`version` 提到顶层,正好绕过了服务端的展平条件,`engines` 留在下一层,服务端只记一条「未声明 engines.protocol」警告就装上了。用真实 CLI 二进制实测:`^17`、`^19` 的产物都装成功、退出码 0。 - **风险与回滚**:只收窄「协议不兼容 / 依赖不满足」的 CLI 产物安装,答复与平铺 manifest、`POST /packages` 完全一致;`^18` 和不声明 `engines` 的产物照旧安装(`^18` 不再出现那条误报警告)。目录(catalog)路径的已发布产物本来就没有顶层 `id`,行为不变。回滚即 revert。 - **先看**:`packages/cloud-connection/src/marketplace-install-local-plugin.ts`(`normalizeBundle` 改为调用已有的 `flattenPackageBody`);`packages/cloud-connection/src/marketplace-install-local-protocol-handshake.test.ts`(新 `[#28535]` 用例组);`.changeset/28535-install-local-nested-artifact-manifest.md`。 - **两分钟验证**:`pnpm --filter @objectstack/cloud-connection exec vitest run src/marketplace-install-local-protocol-handshake.test.ts src/marketplace-install-local-dependency-missing.test.ts` → 28/28 通过。 - **需要你做的**:无,席位落地(收窄需先过合约评审)。 ## What changes **Which side owns the shape, and why the server.** The measurement (below) separates the two candidates. On `origin/main`, the bare compiled artifact `{ manifest: { …, engines }, objects }` posted to install-local is already flattened by the door and refused 422 (the `refuses the bare compiled artifact` case passes on base). Only the body the CLI builds escapes: `install.ts` spreads the artifact and lifts `id` and `version` to the top, and the door's `normalizeBundle` flattened only when the body had NO top-level `id` and `name`. So the intended contract is the door's (ADR-0130 D4: a compiled artifact nests its manifest under `manifest:`; the door already flattens it on the inline and catalog branches, and `flattenPackageBody` already flattens it for the unmanaged import). The defect is that the door's detection depended on which sender built the body. Fixing the door closes it for every CLI already published, which all send the lifted shape; a CLI-only fix would leave every shipped CLI bypassing the handshake. ⛔ No second handshake: the one `assertProtocolCompat` (`packages/metadata-core/src/protocol-handshake.ts`) at step 1c is unchanged; it now receives the flat manifest. **The door** (`packages/cloud-connection/src/marketplace-install-local-plugin.ts`). `normalizeBundle` becomes `isPlainObject(m) ? flattenPackageBody(m) : m`: a body with a nested plain-object `manifest` is a compiled artifact, flattened `{ ...meta, ...sections }` (sections win, the order `flattenPackageBody` records). The old guard (`!m.id && !m.name && (m.manifest.id || m.manifest.name)`) is gone. One flatten now serves the inline branch, the catalog branch and the unmanaged import. For the CLI body the lifted top-level `id`/`version` equal the nested ones (`artifact.manifest.id ?? artifact.id`), so the flattened identity does not change. **What else stayed nested, and now is read.** Reading every top-level manifest key `handleInstall` reads: `engines` (handshake, step 1c) and `dependencies` (ADR-0141 D2 check, step 1c') were both one level down for the CLI body. `installModes` and `namespace` were already read through `declaredPackageManifest`, which reads the nested `manifest` itself, so they were right before and stay right. `packages` (multi-package artifacts) is a collection beside the manifest and was already top level. `name` now reaches the registered package for the CLI body (it was nested before). **Not changed:** `packages/cli/src/commands/package/install.ts` (the lift is now harmless against this runtime; dropping it would also let a new CLI get the check from an older runtime, but that is a second side and outside the ruling's "fix the side that owns the contract"). PR #28571's `handleUninstall` hunks and open PR #28554's hunks are untouched (re-read at start and before `pr_create`; #28554's nearest hunk is 30 lines from `flattenPackageBody`, which this PR does not edit). ## Tests - `marketplace-install-local-protocol-handshake.test.ts`, new group `[#28535] a compiled artifact as os package install sends it`. The body is built exactly as `install.ts` builds it (`cliInstallBody`). Cases: `^17` refused 422 with the five diagnostic fields and nothing registered, synced or ledgered; the CLI body answers byte-for-byte what the flat manifest answers; the bare compiled artifact is refused the same way (control, green on base too); `^18` installs with NO `[protocol]` warning, registered and ledgered flat (`engines` top level, no `manifest` key); no `engines` installs with exactly one warning, as before. - `marketplace-install-local-dependency-missing.test.ts`, new group: the CLI body with an absent dependency is refused 422 `DEPENDENCY_MISSING` and nothing is written; the lit control installs once the dependency is installed in range. **Red on base** (plugin source swapped to `origin/main` `a2e75562`, mutation proved on disk: `flattenPackageBody(m)` count 0, old guard count 1; restored with `git checkout HEAD --`, `git diff HEAD` 0 bytes, blob hash equal to HEAD): 4 failed / 24 passed of 28. Failing exactly: `refuses ^17`, `answers exactly what the flat manifest answers`, `lit control: ^18 installs with no protocol warning` (the false warning), and the dependency refusal. The bare-artifact and no-range controls pass on both trees. **Green** on `8454de72`: 28/28. Full package: `pnpm --filter @objectstack/cloud-connection test` 63 files / 779 tests passed; `typecheck` and `build` exit 0. This revert is also the ablation: the tests import the plugin by relative path (source, no dist), and reverting the one changed expression reds the `^17`, `^18`-no-warning and dependency cases, which is the whole behaviour change. ## Acceptance notes - **Ledger entries written by earlier builds** through the CLI carry the lifted shape with `engines` nested. Measured with a one-off probe (not kept) in this package's harness: a ledger entry in that shape declaring `^17` is re-registered at `kernel:ready` with no error and no `[protocol]` line (`registered = [..., "com.example.qaold"]`, `errors = 0`, `warns = []`), because the rehydrate's `checkProtocolCompat(entry.manifest)` reads the entry as stored. Not changed here: the claim's surface is the install read, and refusing an already-installed package at boot is its own narrowing for deployments that hold such entries. Reported to the seat as a finding. Reinstalling the package through the door now judges it. - `declaredPackageManifest` and `flattenPackageBody` at the unmanaged-import and install-mode steps now always receive a flat body on both branches, so they act as identity there. Left as they are: they still state where each shape keeps its keys. ## Verification **Real CLI binary, before and after.** `packages/cli/bin/run.js` (built `dist`) running `os package install ./dist/objectstack.json --runtime … --email … --password …` against a real `os start --artifact host.json` (development posture, `OS_CLOUD_URL=off`). Four artifacts, each `{ manifest: { id, namespace, version, type, name, engines? }, objects: [one object] }`. Script: `pm-orders/server/evidence/28535/measure.mjs` in the project files. **Base** (`origin/main` `a2e75562`): ```text === v17 exit=0 srv| WARN [MarketplaceInstallLocal] [protocol] package 'com.example.pv17' declares no engines.protocol range; loading under protocol 18.0.0 without a compatibility check (ADR-0087). === v19 exit=0 srv| WARN … package 'com.example.pv19' declares no engines.protocol range … === v18 exit=0 srv| WARN … package 'com.example.pv18' declares no engines.protocol range … === none exit=0 srv| WARN … package 'com.example.pnone' declares no engines.protocol range … LEDGER [ com.example.pnone.json, com.example.pv17.json, com.example.pv18.json, com.example.pv19.json ] ``` **Head** (`8454de72`, cloud-connection rebuilt): ```text === v17 exit=1 cli| ✗ Install failed (422 OS_PROTOCOL_INCOMPATIBLE): package 'com.example.pv17' targets protocol ^17 (engines.protocol) but this runtime is protocol 18.0.0. This is a major-version break. Run: objectstack migrate meta --from 17 === v19 exit=1 cli| ✗ Install failed (422 OS_PROTOCOL_INCOMPATIBLE): package 'com.example.pv19' targets protocol ^19 (engines.protocol) … Upgrade the runtime to protocol 19 … === v18 exit=0 cli| ✓ Package installed into the running kernel (no [protocol] warning) === none exit=0 cli| ✓ Package installed into the running kernel srv| WARN … 'com.example.pnone' declares no engines.protocol range … LEDGER [ com.example.pnone.json, com.example.pv18.json ] ``` **Gates** on `8454de72`. `dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 60 families for the 4 changed paths; each ran with its exit code captured before any pipe, and `--ran` answers `✓ dispatch-gates --ran: 60 derived famil(ies) accounted for — 60 run, 0 NOT-MEASURED`. All 60 exit 0. Two first ran into prerequisites and were re-run, not counted green on the first reading: `check:dual-build-cjs-loads` (exit 3, no full `dist/`; after the full packages build: `115 published require entry point(s) across 70 package(s) load`) and `check:type-check-debt` (exit 3, lock queue-timeout behind this PR's own dogfood run; re-run under the lock: exit 0). Record: `pm-orders/server/evidence/28535/gates-ran-8454de72.txt`. `eslint packages/cloud-connection --no-inline-config`: exit 0. **Dogfood battery** (owed: `(narrowing)` arm) on `8454de72`, under the lock, `pnpm --filter @objectstack/dogfood test` after the `^...` closure build: `VERDICT command-exit 0`, Test Files 364 passed / 3 skipped (367), Tests 2934 passed / 28 skipped (2962). **CI**: the families CI runs are read from this PR's check-runs; not re-run locally. --- _Generated by [Claude Code](https://claude.ai/code/session_01FEkQ5mLNytcuq6kvRwXHMq)_ 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01FEkQ5mLNytcuq6kvRwXHMq Co-authored-by: Claude <noreply@anthropic.com>
1 parent 20dcc07 commit 7449e47

4 files changed

Lines changed: 126 additions & 7 deletions
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/cloud-connection': patch
3+
---
4+
5+
fix(cloud-connection)!: install-local reads the manifest of a compiled artifact as `os package install <file>` sends it, so the protocol handshake and the dependency check run on it (#28535)
6+
7+
Clause-②: no (narrowing) — `POST /api/v1/marketplace/install-local` refuses, with the 422 `OS_PROTOCOL_INCOMPATIBLE` (or `DEPENDENCY_MISSING`) the flat manifest already got, a compiled artifact sent with `id` and `version` lifted beside its nested `manifest`, whose `engines.protocol` excludes this runtime or whose `dependencies` this runtime does not satisfy. That body installed before. Nothing is widened.
8+
Metadata-protocol: none
9+
10+
<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed, renamed or re-shaped, and no export or type changes: the install door's existing ADR-0087 handshake and ADR-0141 dependency check now read the keys of a compiled artifact the CLI sends, as they already read a flat manifest and a bare compiled artifact. The refusals are the existing shared answers, so there is nothing for a migration to rewrite. -->
11+
12+
**BREAKING** accept-set narrowing at `POST /api/v1/marketplace/install-local` (`@objectstack/cloud-connection`), reached by `os package install ./dist/objectstack.json`.
13+
14+
The door flattened a compiled artifact (`{ manifest: { … }, objects, … }`) only when the body had no top-level `id` or `name`. Every published CLI lifts `id` and `version` to the top beside the nested `manifest`, so that body was never flattened and the keys the install checks read at the manifest top level stayed one level down: an artifact built for another protocol installed with a "declares no engines.protocol range" warning, and an unmet dependency was never judged. The door now detects a compiled artifact by its nested `manifest` object alone, through the one flatten it already uses for the unmanaged import, so every sender's body is judged the same way. A compatible artifact installs as before, without the false warning.

‎packages/cloud-connection/src/marketplace-install-local-dependency-missing.test.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,29 @@ describe('POST install-local: ADR-0141 D2 refuses an unsatisfied dependency, and
180180
});
181181
});
182182

183+
describe('[#28535] a compiled artifact as `os package install <file>` sends it: the check reads its nested manifest', () => {
184+
/** The body `packages/cli/src/commands/package/install.ts` builds: the artifact, `id` and `version` lifted beside its nested manifest. */
185+
const cliInstallBody = (manifest: Record<string, any>) => {
186+
const artifact = { manifest, objects: [{ name: 'psa_task', label: 'Task', fields: { name: { type: 'text', label: 'Name' } } }] };
187+
return { manifest: { ...artifact, id: artifact.manifest.id, version: artifact.manifest.version } };
188+
};
189+
190+
it('refuses an absent dependency the compiled artifact declares, and installs nothing', async () => {
191+
const h = await mount(dir);
192+
expectDependencyRefusal(await h.install(cliInstallBody(PSA)), [
193+
{ packageId: 'com.example.psa', dependency: 'com.example.sales', range: '6.x', found: 'absent' },
194+
]);
195+
expectNothingWritten(h);
196+
});
197+
198+
it('lit control: installs once the dependency is installed inside the range', async () => {
199+
const h = await mount(dir, { 'com.example.sales': '6.2.0' });
200+
const res = await h.install(cliInstallBody(PSA));
201+
expect(res.status, JSON.stringify(res.payload)).toBe(200);
202+
expect(h.installRegistrations()).toHaveLength(1);
203+
});
204+
});
205+
183206
describe('POST install-local: a multi-package artifact judges each entry, presence-only inside the artifact', () => {
184207
const artifact = (ordersDeps: Record<string, string>) => ({
185208
id: 'com.example.multi', name: 'Multi', version: '1.0.0', scope: 'project', type: 'app',

‎packages/cloud-connection/src/marketplace-install-local-plugin.ts‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1444,13 +1444,19 @@ export class MarketplaceInstallLocalPlugin implements Plugin {
14441444
// while ObjectQL's registerApp expects the FLAT app shape (top-level
14451445
// id + sections). Flatten when detected — otherwise every install of
14461446
// a published compiled bundle dies with "Invalid manifest payload".
1447-
const normalizeBundle = (m: any): any => {
1448-
if (m && !m.id && !m.name && m.manifest && typeof m.manifest === 'object' && (m.manifest.id || m.manifest.name)) {
1449-
const { manifest: meta, ...sections } = m;
1450-
return { ...meta, ...sections };
1451-
}
1452-
return m;
1453-
};
1447+
//
1448+
// [#28535] ⭐ Detected by the nested `manifest` object ALONE, through
1449+
// the one flatten this door already owns (`flattenPackageBody`). The
1450+
// detection used to also require NO top-level `id`/`name`, and
1451+
// `os package install <file>` (every published CLI) lifts `id` and
1452+
// `version` to the top beside the nested `manifest` — so that body
1453+
// was never flattened, and every key the checks below read at the
1454+
// manifest top level (`engines` for the ADR-0087 handshake,
1455+
// `dependencies` for the ADR-0141 check) stayed one level down: a
1456+
// package built for another protocol installed with a "declares no
1457+
// engines.protocol range" warning. The door reads the shape it
1458+
// receives; it does not depend on which sender built it.
1459+
const normalizeBundle = (m: unknown): any => (isPlainObject(m) ? flattenPackageBody(m) : m);
14541460

14551461
let manifest: any;
14561462
let resolvedVersionId: string;

‎packages/cloud-connection/src/marketplace-install-local-protocol-handshake.test.ts‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@
2424
* - the two doors give the SAME answer for the same manifest: status, code,
2525
* message and `details`, byte-compared. Both answer through one helper,
2626
* `protocolIncompatibleAnswer` in `@objectstack/metadata-core`;
27+
* - [#28535] the same refusal for a compiled artifact in the body
28+
* `os package install <file>` sends (manifest nested, `id` and `version`
29+
* lifted beside it), where the range used to stay one level down and the
30+
* package installed with a "declares no engines.protocol range" warning;
2731
* - the `kernel:ready` rehydrate of an incompatible ledger entry, as
2832
* measured: on `origin/main` before this change it registered the package,
2933
* ran `syncSchemas` and logged only `info` "rehydrated". Now it is NOT
@@ -268,6 +272,78 @@ describe('POST install-local: an incompatible protocol range is refused, and not
268272
});
269273
});
270274

275+
/**
276+
* [#28535] The body `os package install ./dist/objectstack.json` sends, built
277+
* the way `packages/cli/src/commands/package/install.ts` builds it: the whole
278+
* compiled artifact (manifest nested under `manifest:` beside its collections,
279+
* ADR-0130 D4) with `id` and `version` lifted to the top. Every published CLI
280+
* sends this shape, so the door is judged on it, not on a body only a test
281+
* would build.
282+
*/
283+
function cliInstallBody(artifact: { manifest: Record<string, any>; [k: string]: any }) {
284+
return { manifest: { ...artifact, id: artifact.manifest.id ?? artifact.id, version: artifact.manifest.version ?? artifact.version } };
285+
}
286+
287+
/** A compiled artifact: the manifest nested under `manifest:`, one object beside it. */
288+
function compiledArtifact(manifest: Record<string, any>) {
289+
return {
290+
manifest,
291+
objects: [{ name: 'qa_task', label: 'Task', fields: { name: { type: 'text', label: 'Name' } } }],
292+
};
293+
}
294+
295+
describe('[#28535] a compiled artifact as `os package install <file>` sends it: the handshake reads its nested manifest', () => {
296+
const protocolWarnings = (h: { logger: { warn: { mock: { calls: unknown[][] } } } }) =>
297+
h.logger.warn.mock.calls.map(([m]) => String(m)).filter((m) => m.includes('[protocol]'));
298+
299+
it(`refuses ${OLD_RANGE} on protocol ${PROTOCOL_MAJOR}: 422 with the five diagnostic fields, and nothing is installed`, async () => {
300+
const h = await mount(dir);
301+
const res = await h.install(cliInstallBody(compiledArtifact(INCOMPATIBLE)));
302+
expectProtocolRefusal(res);
303+
expectNothingWritten(h);
304+
expect(protocolWarnings(h)).toEqual([]);
305+
});
306+
307+
it('answers exactly what the flat manifest answers, byte for byte', async () => {
308+
const h = await mount(dir);
309+
const viaCli = await h.install(cliInstallBody(compiledArtifact(INCOMPATIBLE)));
310+
const viaFlat = await h.install({ manifest: INCOMPATIBLE });
311+
expect(JSON.stringify(viaCli)).toBe(JSON.stringify(viaFlat));
312+
});
313+
314+
it('refuses the bare compiled artifact (no lifted id) the same way', async () => {
315+
const h = await mount(dir);
316+
expectProtocolRefusal(await h.install({ manifest: compiledArtifact(INCOMPATIBLE) }));
317+
expectNothingWritten(h);
318+
});
319+
320+
it(`lit control: ${CURRENT_RANGE} installs with no protocol warning, registered and ledgered flat`, async () => {
321+
const h = await mount(dir);
322+
const res = await h.install(cliInstallBody(compiledArtifact(COMPATIBLE)));
323+
expect(res.status, JSON.stringify(res.payload)).toBe(200);
324+
expect(res.payload.data.manifestId).toBe(COMPATIBLE.id);
325+
expect(protocolWarnings(h)).toEqual([]);
326+
const [registered] = h.installRegistrations() as any[];
327+
expect(h.installRegistrations()).toHaveLength(1);
328+
expect(registered.id).toBe(COMPATIBLE.id);
329+
expect(registered.engines).toEqual({ protocol: CURRENT_RANGE });
330+
expect(registered.objects.map((o: any) => o.name)).toEqual(['qa_task']);
331+
expect(registered.manifest).toBeUndefined();
332+
expect(readdirSync(dir)).toEqual([`${COMPATIBLE.id}.json`]);
333+
expect(new LocalManifestSource(dir).read(COMPATIBLE.id).entry?.manifest.engines).toEqual({ protocol: CURRENT_RANGE });
334+
});
335+
336+
it('lit control: an artifact with no range is admitted with the one warning, as before', async () => {
337+
const { engines: _omitted, ...noRange } = COMPATIBLE;
338+
const h = await mount(dir);
339+
const res = await h.install(cliInstallBody(compiledArtifact(noRange)));
340+
expect(res.status, JSON.stringify(res.payload)).toBe(200);
341+
const warned = protocolWarnings(h);
342+
expect(warned).toHaveLength(1);
343+
expect(warned[0]).toContain(COMPATIBLE.id);
344+
});
345+
});
346+
271347
describe('the two package-install doors give the same answer for the same manifest', () => {
272348
/**
273349
* `POST /api/v1/packages` through the runtime's real dispatcher, on its

0 commit comments

Comments
 (0)