Repository navigation
Commit 7449e47
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
File tree
- .changeset
- packages/cloud-connection/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
180 | 180 | | |
181 | 181 | | |
182 | 182 | | |
| 183 | + | |
| 184 | + | |
| 185 | + | |
| 186 | + | |
| 187 | + | |
| 188 | + | |
| 189 | + | |
| 190 | + | |
| 191 | + | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
183 | 206 | | |
184 | 207 | | |
185 | 208 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1444 | 1444 | | |
1445 | 1445 | | |
1446 | 1446 | | |
1447 | | - | |
1448 | | - | |
1449 | | - | |
1450 | | - | |
1451 | | - | |
1452 | | - | |
1453 | | - | |
| 1447 | + | |
| 1448 | + | |
| 1449 | + | |
| 1450 | + | |
| 1451 | + | |
| 1452 | + | |
| 1453 | + | |
| 1454 | + | |
| 1455 | + | |
| 1456 | + | |
| 1457 | + | |
| 1458 | + | |
| 1459 | + | |
1454 | 1460 | | |
1455 | 1461 | | |
1456 | 1462 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
24 | 24 | | |
25 | 25 | | |
26 | 26 | | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
27 | 31 | | |
28 | 32 | | |
29 | 33 | | |
| |||
268 | 272 | | |
269 | 273 | | |
270 | 274 | | |
| 275 | + | |
| 276 | + | |
| 277 | + | |
| 278 | + | |
| 279 | + | |
| 280 | + | |
| 281 | + | |
| 282 | + | |
| 283 | + | |
| 284 | + | |
| 285 | + | |
| 286 | + | |
| 287 | + | |
| 288 | + | |
| 289 | + | |
| 290 | + | |
| 291 | + | |
| 292 | + | |
| 293 | + | |
| 294 | + | |
| 295 | + | |
| 296 | + | |
| 297 | + | |
| 298 | + | |
| 299 | + | |
| 300 | + | |
| 301 | + | |
| 302 | + | |
| 303 | + | |
| 304 | + | |
| 305 | + | |
| 306 | + | |
| 307 | + | |
| 308 | + | |
| 309 | + | |
| 310 | + | |
| 311 | + | |
| 312 | + | |
| 313 | + | |
| 314 | + | |
| 315 | + | |
| 316 | + | |
| 317 | + | |
| 318 | + | |
| 319 | + | |
| 320 | + | |
| 321 | + | |
| 322 | + | |
| 323 | + | |
| 324 | + | |
| 325 | + | |
| 326 | + | |
| 327 | + | |
| 328 | + | |
| 329 | + | |
| 330 | + | |
| 331 | + | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
| 337 | + | |
| 338 | + | |
| 339 | + | |
| 340 | + | |
| 341 | + | |
| 342 | + | |
| 343 | + | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
271 | 347 | | |
272 | 348 | | |
273 | 349 | | |
| |||
0 commit comments