Skip to content

Commit f273967

Browse files
committed
refactor(plugins): answer the review findings on the v1 removal
Point the traversal fixture at the file that exists outside the package, say the entry contract as it is (root export, which is main without exports), move the v1 manifest's connection to connection.capabilities in the migration note and separate the incompatible_plugin and invalid_plugin cases, claim the built-in id with a non-routing provider in the store test, and state what install checks.
1 parent 246cac4 commit f273967

8 files changed

Lines changed: 20 additions & 18 deletions

File tree

‎.changeset/remove-provider-plugin-v1.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,4 @@
66

77
Remove the version 1 provider plugin contract. A store package is now discovered only through its exports: `./agent-device`, or the package root when that subpath is absent. The host no longer reads an `agentDevicePlugin` manifest to choose an entry or to declare a provider, connection capabilities, or credential variables, and `agent-device plugins add` no longer refuses a package for a provider another manifest claims — the registry settles a duplicate provider id when the daemon next composes its plugins, as the first claim wins.
88

9-
Migrate a plugin by exporting its factory from `./agent-device` and returning the manifest's values from the factory: `provider`, `credentials: { variables: [...] }`, an optional `connection`, and `setup(host)` that returns `{ runtime, platformModule }` or `{ webDriver }`, with `apiVersion: 2`. See [Provider plugins](/docs/plugins) for the full migration. A package whose default export is not a version 2 plugin is listed as `failed` with `incompatible_plugin` and the daemon starts without it.
9+
Migrate a plugin by exporting its factory from `./agent-device` and returning the manifest's values from the factory: `provider`, `credentials: { variables: [...] }`, an optional `connection`, and `setup(host)` that returns `{ runtime, platformModule }` or `{ webDriver }`, with `apiVersion: 2`. See [Provider plugins](/docs/plugins) for the full migration. A plugin object with an `apiVersion` other than 2 is listed as `failed` with `incompatible_plugin`, and a default export that is not a plugin factory with `invalid_plugin`; the daemon starts without either.

‎docs/adr/0034-provider-plugin-registry.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@ Status: accepted. Umbrella #3747; contract and registry #3755.
2323
- `daemon.json` has one reader. Its states are `absent`, `unreadable`, and `invalid`. A missing or
2424
stale record reads as a stopped daemon; an unreadable or invalid one never does.
2525
- The plugin set is fixed for a daemon's lifetime. A plugin change takes effect on the next daemon.
26-
- A store package is discovered only through its exports: `./agent-device`, or the package root when
27-
that subpath is absent. Nothing is read from `package.json` to choose an entry or to declare a
28-
provider, connection capabilities, or credential variables (#3759).
26+
- A store package is discovered through its package targets: the `./agent-device` export, else the
27+
root export, which is `main` for a package that declares no `exports`. Nothing is read from
28+
`package.json` to declare a provider, connection capabilities, or credential variables (#3759).
2929

3030
## Context
3131

‎packages/plugins/src/discovery.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,7 @@ test('an entry outside the installed package is refused', () => {
158158
name: 'traversal',
159159
version: '1.0.0',
160160
type: 'module',
161-
exports: { './agent-device': './../outside.js' },
161+
exports: { './agent-device': './../../outside.js' },
162162
}),
163163
);
164164
assert.throws(

‎packages/plugins/src/registry.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ export type PluginCandidate = Readonly<{
3131
source: PluginSource;
3232
package?: string;
3333
version?: string;
34-
/** Claims `provider` without loading it, so a later candidate with that id is a duplicate. */
34+
/** Claims `provider` before its load settles, so a later candidate with that id is a duplicate. Dormant candidates claim it without loading. */
3535
provider?: string;
3636
/** Claims `provider` without registering or listing: a built-in that is not configured. */
3737
dormant?: boolean;

‎packages/plugins/src/store.test.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -205,13 +205,13 @@ test('a duplicate provider id is settled by the registry when the store composes
205205
['second', false, 'duplicate_provider'],
206206
],
207207
);
208-
// A built-in identity claims the id first, so a store package cannot take it either.
208+
// A dormant built-in claims the id first, so a store package cannot take it either.
209209
const { home: otherHome, env: otherEnv } = pluginHome();
210-
selectV2Plugin(otherHome, 'cloud', v2RegistrationSource('cloud'));
211-
const cloud = await listPlugins(otherEnv, ['cloud']);
210+
selectV2Plugin(otherHome, 'limrun-plugin', v2RegistrationSource('limrun'));
211+
const limrun = await listPlugins(otherEnv, ['limrun']);
212212
assert.deepEqual(
213-
cloud.map(({ name, compatible, error }) => [name, compatible, error?.reason]),
214-
[['cloud', false, 'reserved_provider']],
213+
limrun.map(({ name, compatible, error }) => [name, compatible, error?.reason]),
214+
[['limrun-plugin', false, 'duplicate_provider']],
215215
);
216216
});
217217

‎packages/plugins/src/store.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -242,9 +242,10 @@ async function stagePlugin(
242242
}
243243

244244
/**
245-
* Installs, updates or removes one plugin selection. A package is accepted when its entry loads as
246-
* a plugin; a provider-id clash with another plugin or a built-in is the registry's to settle when
247-
* the daemon next composes its plugins.
245+
* Installs, updates or removes one plugin selection. Install checks the staged package's identity
246+
* and version and resolves its entry to a readable file; the factory first runs when the daemon next
247+
* composes its plugins. A provider-id clash with another plugin or a built-in is the registry's to
248+
* settle then, by first claim.
248249
*/
249250
export async function changePlugin(
250251
action: PluginAction,

‎scripts/release-workspace.mjs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,8 @@ function checkPublishedDependencies(packed) {
7070
packages.filter((pkg) => pkg.manifest.private === true).map((pkg) => pkg.manifest.name),
7171
);
7272
// A provider plugin exports its factory as `./agent-device` and imports only types from
73-
// agent-device, so it must never carry the core as a runtime dependency.
73+
// agent-device, so it must never carry the core as a runtime dependency. The root and `main`
74+
// loading fallbacks stay a loader convenience; a published plugin package names `./agent-device`.
7475
if (packed.exports && Object.hasOwn(packed.exports, './agent-device'))
7576
unpublishableNames.add(rootPackage.manifest.name);
7677
for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies']) {

‎website/docs/docs/plugins.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -132,7 +132,7 @@ connection: {
132132

133133
### Package for installation
134134

135-
Bundle the plugin implementation and ship ready-to-run ESM: installation disables lifecycle scripts. Bundle shared helpers with the plugin; `AppError` carries a shared brand so the host preserves its code and details across package copies. Import types with `import type` to keep them out of the runtime dependency graph.
135+
Bundle the plugin implementation and ship ready-to-run ESM: installation disables lifecycle scripts. Bundle shared helpers with the plugin; `AppError` carries a shared brand so the host preserves its code and details across package copies. Import types with `import type` to keep them out of the runtime dependency graph. A published plugin package names `./agent-device` in its `exports`: that is the subpath the host's loader and the publish checks read, so don't ship a plugin only through the root export or `main`.
136136

137137
## Migrating from a version 1 manifest
138138

@@ -141,7 +141,7 @@ Earlier plugin packages declared `agentDevicePlugin` with `apiVersion: 1` in `pa
141141
To move a package:
142142

143143
1. Export the factory from `./agent-device` instead of naming an entry file in the manifest, and drop `agentDevicePlugin` from `package.json`.
144-
2. Return the manifest's values from the factory: `provider` stays `provider`, `credentialVariables` becomes `credentials: { variables: [...] }`, and the `connection` object goes on the plugin next to `setup`.
144+
2. Return the manifest's values from the factory: `provider` stays `provider`, `credentialVariables` becomes `credentials: { variables: [...] }`, and the manifest's `connection` becomes `connection.capabilities`, with the `resolve` and `verify` the v1 entry returned for `connection` moved into that same `connection` object next to `setup`.
145145
3. Return `apiVersion: 2` and keep the default export a function; the host calls it with the selection's options and `setup` receives the `ProviderPluginHost` the v1 entry used to receive first.
146146

147147
```diff
@@ -159,4 +159,4 @@ To move a package:
159159
+});
160160
```
161161

162-
A package that still ships the old manifest loads when it also exports `./agent-device`, and the manifest is then ignored. A package whose default export isn't a v2 plugin is listed as `failed` with `incompatible_plugin` and the daemon starts without it.
162+
A package that still ships the old manifest loads when it also exports `./agent-device`, and the manifest is then ignored. A plugin object with an `apiVersion` other than 2 is listed as `failed` with `incompatible_plugin`, and a default export that is not a plugin factory with `invalid_plugin`; the daemon starts without either.

0 commit comments

Comments
 (0)