Skip to content

Commit f14ac17

Browse files
committed
docs(design): plugin-distribution names bundled as the one packaging strategy; manifest-deps retired
Claude-Session: https://claude.ai/code/session_01QSeKYmTYfaPbLQD4BJfomW Co-authored-by: Claude <noreply@anthropic.com>
1 parent 86f2afe commit f14ac17

1 file changed

Lines changed: 29 additions & 18 deletions

File tree

‎docs/design/plugin-distribution.md‎

Lines changed: 29 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -111,15 +111,13 @@ A `tar.gz`:
111111
<id>-<version>.osplugin
112112
├── objectstack.plugin.json # compiled manifest (below)
113113
├── dist/ # pre-built ESM bundle (tsup); @objectstack/* externalized
114-
├── package.json # only for the manifest-deps strategy
115-
├── pnpm-lock.yaml # only for the manifest-deps strategy
116114
├── assets/ README LICENSE icon
117115
└── SIGNATURE # detached signature + publisher cert chain
118116
```
119117

120118
Compiled manifest adds four blocks to the existing `ObjectStackManifest`:
121119
`engines` (protocol + platform ranges), `runtime` (`node|sandbox|worker`),
122-
`packaging` (`bundled|manifest-deps`), `permissions` (services/hooks/network/fs
120+
`packaging` (`bundled`, the one strategy and the default — §4.3), `permissions` (services/hooks/network/fs
123121
+ RLS data scopes), and `integrity` (per-file hashes).
124122

125123
### 4.2 UI plugin (`runtime: 'ui'` — ADR-0026 §3.1)
@@ -135,15 +133,27 @@ client-scoped `permissions` (data read/write via SDK, network → CSP, navigatio
135133
> `ManifestSchema` and `PluginSchema` refuse `ui-plugin`; this section and
136134
> worked example C in §10 use `ui`.
137135
138-
### 4.3 Packaging strategies (default: bundled)
139-
140-
- **Bundled (default).** `tsup --noExternal` bundles third-party JS into `dist`;
141-
no npm at install time. **`@objectstack/*` is externalized** as a host-provided
142-
peer-dep singleton (bundling it forks the engine — duplicate registries / broken
143-
`instanceof` / double Zod validation). Native addons disallowed.
144-
- **manifest-deps (opt-in).** Ships `package.json` + lockfile; install runs
145-
`pnpm install --frozen-lockfile --ignore-scripts`. For native addons / huge
146-
deps only; disallowed for unverified publishers.
136+
### 4.3 Packaging strategy: bundled only
137+
138+
- **Bundled — the one strategy, and the default.** `os plugin build` inlines
139+
every dependency the entry imports into `dist/index.mjs`, so install is unpack +
140+
verify with no npm or toolchain at install time: `os plugin install` and the
141+
boot-time loader import `dist/index.mjs` as packed, and the artifact carries
142+
neither `package.json` nor a lockfile. **`@objectstack/*` is externalized** as a
143+
host-provided peer-dep singleton (bundling it forks the engine — duplicate
144+
registries / broken `instanceof` / double Zod validation). A native (`.node`)
145+
addon is refused by name at build, before any artifact is written.
146+
147+
> **Note (2026-10-29, #27679).** This section used to list a second, opt-in
148+
> strategy, `manifest-deps`, which shipped `package.json` + a lockfile for an
149+
> install-time `pnpm install`. Nothing ever ran that install, so an artifact
150+
> built with it could not load the dependencies it left out. It is retired
151+
> (ADR-0025 v2 §3.3): `PluginPackagingSchema`
152+
> (`packages/spec/src/kernel/manifest.zod.ts`) accepts `bundled` alone and
153+
> refuses `packaging: 'manifest-deps'` by name with its migration prescription
154+
> (delete the key), and `os plugin build` no longer forks on the value. A plugin
155+
> that needs a native addon or a very large dependency is a fresh ADR-0025 M3
156+
> decision, not a strategy here. §4.1, §5, §6 and §8 name no second strategy.
147157
148158
## 5. Build → Sign → Publish
149159

@@ -164,8 +174,8 @@ os plugin build → os plugin sign → os plugin publish
164174
`sys_plugin_version` (`status: pending_review → published`).
165175
- **Server gates:** schema validation; secret/malware/known-vuln scan;
166176
**permission audit** (sensitive permissions → human review); **publish-time
167-
tier enforcement** (an unverified publisher cannot ship `runtime: 'node'` or
168-
`manifest-deps`); marketplace **counter-signs** with the platform key on
177+
tier enforcement** (an unverified publisher cannot ship `runtime: 'node'`);
178+
marketplace **counter-signs** with the platform key on
169179
approval.
170180
- Listed in the **contribution catalog** (not the consumer App Marketplace),
171181
with a "contains code" badge and a permission-disclosure screen.
@@ -191,8 +201,8 @@ resolve → compat check → permission consent → download+verify → material
191201
are wired to the KV secret store (ADR-0007) — never stored in the artifact.
192202
4. **Download + verify.** Verify signature (publisher + marketplace keys) and each
193203
file against `integrity`; reject on mismatch.
194-
5. **Materialize.** Unpack to `<OS_HOME>/plugins/<env>/<id>/<version>/`;
195-
manifest-deps runs `pnpm install --frozen-lockfile --ignore-scripts` here.
204+
5. **Materialize.** Unpack to `<OS_HOME>/plugins/<env>/<id>/<version>/`. No
205+
dependency install runs here: the bundle is imported as packed (§4.3).
196206
6. **Register.** Write `sys_plugin_installation` (env_id, plugin_id, version_id,
197207
granted_permissions incl. RLS scopes, status, is_preview). Persist to a local
198208
store so installs survive restarts (the ADR-0016 §9.7 disable-state pattern).
@@ -242,8 +252,9 @@ Reuses existing components, adds two compositions:
242252
- **Secrets.** `configuration` secret fields → KV secret store (ADR-0007) via
243253
secret-refs; the artifact never carries credentials; the plugin reads them
244254
through `PluginContext` gated by the network/service permission.
245-
- **Supply chain.** Lockfile + per-file integrity; server-side secret/vuln scans;
246-
SBOM on the version row; **always `--ignore-scripts`** (no `postinstall`).
255+
- **Supply chain.** Per-file integrity; server-side secret/vuln scans; SBOM on
256+
the version row; **no install-time package manager at all** (bundled only,
257+
§4.3), so no dependency's `postinstall` ever runs.
247258
- **Server-authoritative UI data.** UI plugins read/write only via the client SDK
248259
under the user's session → every access re-checked by server RLS; manifest
249260
`permissions.data` is a UI hint/guard, not the boundary. U1 iframes cannot read

0 commit comments

Comments
 (0)