diff --git a/.changeset/remove-provider-plugin-v1.md b/.changeset/remove-provider-plugin-v1.md new file mode 100644 index 0000000000..a18f09fb30 --- /dev/null +++ b/.changeset/remove-provider-plugin-v1.md @@ -0,0 +1,9 @@ +--- +'agent-device': minor +'@agent-device/testmu': minor +'@agent-device/revyl': minor +--- + +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. + +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. diff --git a/.fallowrc.json b/.fallowrc.json index c1d92c5396..1daaeb3098 100644 --- a/.fallowrc.json +++ b/.fallowrc.json @@ -7,10 +7,8 @@ "scripts/check-affected/command.ts", "packages/provider-testmu/test/package-smoke.mjs", "packages/provider-testmu/tsdown.config.ts", - "packages/provider-testmu/src/plugin.ts", "packages/provider-revyl/test/package-smoke.mjs", "packages/provider-revyl/tsdown.config.ts", - "packages/provider-revyl/src/plugin.ts", "packages/provider-webos/test/package-smoke.mjs", "packages/provider-webos/tsdown.config.ts", "packages/provider-tizen/test/package-smoke.mjs", @@ -152,15 +150,10 @@ "exports": ["*"] }, { - // A published provider package's default export is its plugin contract; packages/plugins/src/load.ts imports the package by name at runtime and reads `default`. + // A published provider package's default export is its plugin contract; the plugin loader imports the installed package's resolved entry at runtime and reads `default`. "file": "packages/provider-*/src/index.ts", "exports": ["default"] }, - { - // The version 1 entry a provider package's `agentDevicePlugin.entry` names; hosts without the version 2 contract import the built file and read `default`. - "file": "packages/provider-*/src/plugin.ts", - "exports": ["default"] - }, { // packages/platform-apple/src/lifecycle.ts loads this module on demand and reads the member off the memoized import() promise, which Fallow cannot follow. "file": "packages/platform-apple/src/expo-dev-client-launch.ts", diff --git a/docs/adr/0034-provider-plugin-registry.md b/docs/adr/0034-provider-plugin-registry.md index 6c3d1bc277..5b97037db5 100644 --- a/docs/adr/0034-provider-plugin-registry.md +++ b/docs/adr/0034-provider-plugin-registry.md @@ -23,10 +23,9 @@ Status: accepted. Umbrella #3747; contract and registry #3755. - `daemon.json` has one reader. Its states are `absent`, `unreadable`, and `invalid`. A missing or stale record reads as a stopped daemon; an unreadable or invalid one never does. - The plugin set is fixed for a daemon's lifetime. A plugin change takes effect on the next daemon. -- v1 plugins (`agentDevicePlugin.apiVersion: 1`) without a `./agent-device` export are dispatched by - their manifest before any code runs and load through an adapter until 0.22 removes them (#3759). - A package that keeps the manifest and also exports `./agent-device` loads as v2; hosts without - v2 still read the manifest. +- A store package is discovered through its package targets: the `./agent-device` export, else the + root export, which is `main` for a package that declares no `exports`. Nothing is read from + `package.json` to declare a provider, connection capabilities, or credential variables (#3759). ## Context @@ -44,17 +43,15 @@ had to fake the store to load a plugin from its own dependencies (#3747). fingerprint. - **A package exports its entry as `./agent-device`.** The host resolves it with import conditions and falls back to the package root only when the subpath is absent. A subpath whose - import or setup throws never falls back. A v2 package needs no manifest. + import or setup throws never falls back. A plugin package needs no manifest. - **The registry owns identity, not the retired lists.** Duplicate ids and bundled ids are one question answered by claim order. Credential variables, per-backend narrowing and connect - capabilities are read from the registry's plugins, not from manifests. A v1 manifest still - supplies them for a v1 plugin. + capabilities are read from the registry's plugins, not from manifests. - **Failure is data.** A failed plugin is an inventory entry, not an exception. Behavior keys on `error.reason`, never on the message. - **A client reads a daemon's inventory from `daemon.json`.** The client credential fingerprint - takes variable names from it and falls back to v1 manifests. A v2 plugin declares its connect - capabilities in code, so a client loads the store, without setting up a runtime, before it reads - them. + takes variable names from it. A v2 plugin declares its connect capabilities in code, so a client + loads the store, without setting up a runtime, before it reads them. ## Daemon ownership diff --git a/packages/plugins/package.json b/packages/plugins/package.json index 319a6e2fb0..a5d803b8fc 100644 --- a/packages/plugins/package.json +++ b/packages/plugins/package.json @@ -30,10 +30,6 @@ "types": "./src/load.ts", "default": "./src/load.ts" }, - "./manifest": { - "types": "./src/manifest.ts", - "default": "./src/manifest.ts" - }, "./registry": { "types": "./src/registry.ts", "default": "./src/registry.ts" diff --git a/packages/plugins/src/connection.ts b/packages/plugins/src/connection.ts index 021c297ce0..7012d89711 100644 --- a/packages/plugins/src/connection.ts +++ b/packages/plugins/src/connection.ts @@ -2,7 +2,7 @@ import type { ConnectionProviderCapabilities } from '@agent-device/contracts/rem import { resolveUserConfigPath } from '@agent-device/host-kit/file'; import type { PluginInventoryEntry } from '@agent-device/contracts/plugin-inventory'; import type { PluginConnection, PluginConnectionContext } from './contract.ts'; -import { legacyStoreManifests, storePluginCandidates } from './store.ts'; +import { storePluginCandidates } from './store.ts'; /** A plugin's connection as the client calls it: the registry adds the `host` to each context. */ export type PluginConnectionCallbacks = Readonly<{ @@ -15,10 +15,9 @@ export type PluginConnectionCallbacks = Readonly<{ export type RegisteredConnection = PluginConnectionCallbacks & Readonly<{ capabilities: PluginConnection['capabilities'] }>; -// Capabilities live in the plugin, so a v2 store plugin answers only once its package has loaded. -// A client loads the store once per process through primePluginConnections; every synchronous -// reader below then answers from that registry alone. Before the store is primed, a v1 plugin -// answers from its manifest. +// A plugin declares its connection capabilities in code, so a store plugin answers only once its +// package has loaded. A client loads the store once per process through primePluginConnections; +// every synchronous reader below then answers from that registry alone. export type FailedPlugin = Extract; type PrimedStore = Readonly<{ @@ -69,16 +68,10 @@ export function pluginConnectionCapabilities( env: NodeJS.ProcessEnv, ): ConnectionProviderCapabilities | undefined { if (provider === undefined) return undefined; - const store = primed.get(resolveUserConfigPath(env)); - if (store) return store.connections.get(provider)?.capabilities; - return legacyStoreManifests(env).find((plugin) => plugin.agentDevicePlugin.provider === provider) - ?.agentDevicePlugin.connection; + return primed.get(resolveUserConfigPath(env))?.connections.get(provider)?.capabilities; } export function pluginConnectionNames(env: NodeJS.ProcessEnv): string[] { const store = primed.get(resolveUserConfigPath(env)); - if (store) return [...store.connections.keys()]; - return legacyStoreManifests(env) - .filter((plugin) => plugin.agentDevicePlugin.connection) - .map((plugin) => plugin.agentDevicePlugin.provider); + return store ? [...store.connections.keys()] : []; } diff --git a/packages/plugins/src/contract.ts b/packages/plugins/src/contract.ts index 956645453a..99037cddae 100644 --- a/packages/plugins/src/contract.ts +++ b/packages/plugins/src/contract.ts @@ -9,6 +9,9 @@ import type { ProviderPluginHost } from './host.ts'; /** The provider plugin contract version this module defines. */ export const PROVIDER_PLUGIN_API_VERSION = 2; +/** Provider ids that name daemon routing; no plugin can claim either of them. */ +export const ROUTING_PROVIDER_IDENTITIES: readonly string[] = ['cloud', 'proxy']; + /** * The environment variables a plugin reads credentials from. The host fingerprints their values to * refuse a lease when the shell holds different credentials than the daemon started with. List diff --git a/packages/plugins/src/credential-fingerprint.ts b/packages/plugins/src/credential-fingerprint.ts index f2797cd046..3249ecaf56 100644 --- a/packages/plugins/src/credential-fingerprint.ts +++ b/packages/plugins/src/credential-fingerprint.ts @@ -4,7 +4,6 @@ import { type PluginInventoryEntry, } from '@agent-device/contracts/plugin-inventory'; import type { EnvMap } from '@agent-device/kernel/source-value'; -import { legacyStoreManifests } from './store-legacy.ts'; type CredentialValues = Readonly>; @@ -12,7 +11,7 @@ type CredentialValues = Readonly>; * A versioned, non-reversible digest of the credentials a lease on `leaseBackend` reads from `env`, * or undefined when `env` holds none of them or the provider's credentials do not come from the * environment. Provider names are trimmed before lookup. Variable names come from the daemon's - * plugin inventory, then from v1 manifests. + * plugin inventory. */ export function providerCredentialFingerprint( provider: string, @@ -20,7 +19,7 @@ export function providerCredentialFingerprint( leaseBackend?: string, inventory?: readonly PluginInventoryEntry[], ): string | undefined { - const variables = declaredCredentialVariables(provider.trim(), env, leaseBackend, inventory); + const variables = declaredCredentialVariables(provider.trim(), leaseBackend, inventory); // Whitespace-only counts as unset and other values are kept as is, as the provider's requireEnv does. return variables ? digest( @@ -31,17 +30,14 @@ export function providerCredentialFingerprint( : undefined; } -// Read from the inventory or manifest, so neither the client nor the daemon evaluates provider code. +// Read from the inventory the daemon published, so neither the client nor the daemon evaluates +// provider code. function declaredCredentialVariables( provider: string, - env: EnvMap, leaseBackend: string | undefined, inventory: readonly PluginInventoryEntry[] | undefined, ): readonly string[] | undefined { - const published = inventory && pluginCredentialVariables(inventory, provider, leaseBackend); - if (published) return published; - return legacyStoreManifests(env).find((plugin) => plugin.agentDevicePlugin.provider === provider) - ?.agentDevicePlugin.credentialVariables; + return inventory && pluginCredentialVariables(inventory, provider, leaseBackend); } function digest(values: CredentialValues): string | undefined { diff --git a/packages/plugins/src/discovery.test.ts b/packages/plugins/src/discovery.test.ts index ff2299bb0c..31ea661dd9 100644 --- a/packages/plugins/src/discovery.test.ts +++ b/packages/plugins/src/discovery.test.ts @@ -120,11 +120,68 @@ test('package export resolution agrees with Node for each shape a plugin package entry.name, ); } else { - assert.deepEqual( - discoverPluginEntry(directory), - { kind: 'v2', file: path.join(directory, entry.loads) }, - entry.name, - ); + assert.equal(discoverPluginEntry(directory), path.join(directory, entry.loads), entry.name); } } }); + +test('a manifest entry never selects the loaded file', () => { + const root = fs.realpathSync(mkdtempForTestSync('agent-device-manifest-entry-')); + const directory = path.join(root, 'node_modules', 'declared'); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name: 'declared', + version: '1.0.0', + type: 'module', + main: './main.js', + agentDevicePlugin: { apiVersion: 1, provider: 'declared', entry: './legacy.js' }, + }), + ); + for (const file of ['main.js', 'legacy.js']) + fs.writeFileSync(path.join(directory, file), 'export {};'); + + assert.equal(discoverPluginEntry(directory), path.join(directory, 'main.js')); +}); + +test('an entry outside the installed package is refused', () => { + const root = mkdtempForTestSync('agent-device-entry-containment-'); + const outside = path.join(root, 'outside.js'); + fs.writeFileSync(outside, 'export {};'); + + const escaped = path.join(root, 'node_modules', 'traversal'); + fs.mkdirSync(escaped, { recursive: true }); + fs.writeFileSync( + path.join(escaped, 'package.json'), + JSON.stringify({ + name: 'traversal', + version: '1.0.0', + type: 'module', + exports: { './agent-device': './../../outside.js' }, + }), + ); + assert.throws( + () => discoverPluginEntry(escaped), + (error: unknown) => + (error as { details?: { reason?: string } }).details?.reason === 'plugin_load_failed', + ); + + const linked = path.join(root, 'node_modules', 'symlinked'); + fs.mkdirSync(linked, { recursive: true }); + fs.writeFileSync( + path.join(linked, 'package.json'), + JSON.stringify({ + name: 'symlinked', + version: '1.0.0', + type: 'module', + exports: { './agent-device': './plugin.js' }, + }), + ); + fs.symlinkSync(outside, path.join(linked, 'plugin.js')); + assert.throws( + () => discoverPluginEntry(linked), + (error: unknown) => + (error as { details?: { reason?: string } }).details?.reason === 'plugin_load_failed', + ); +}); diff --git a/packages/plugins/src/discovery.ts b/packages/plugins/src/discovery.ts index d052660a03..b44c4ef0c3 100644 --- a/packages/plugins/src/discovery.ts +++ b/packages/plugins/src/discovery.ts @@ -2,7 +2,6 @@ import fs from 'node:fs'; import path from 'node:path'; import { AppError } from '@agent-device/kernel/errors'; import { isRecord } from '@agent-device/kernel/record'; -import { readPluginManifest, resolvePluginEntry, type PluginManifest } from './manifest.ts'; const PROVIDER_ID = /^[a-z][a-z0-9-]*$/; @@ -10,29 +9,19 @@ export function isProviderId(value: unknown): value is string { return typeof value === 'string' && PROVIDER_ID.test(value); } -/** The subpath a v2 plugin package exports; its default export is the plugin factory. */ +/** The subpath a plugin package exports; its default export is the plugin factory. */ const PLUGIN_ENTRY_SUBPATH = './agent-device'; -export type PluginPackageEntry = - | Readonly<{ kind: 'v2'; file: string }> - | Readonly<{ kind: 'v1'; manifest: PluginManifest }>; - /** - * Chooses how an installed package loads, without evaluating it. The `./agent-device` export wins; - * a package that lacks that subpath and declares `agentDevicePlugin` is a v1 plugin dispatched by - * its manifest; any other package falls back to its root export. A subpath that exists but does - * not resolve is an error, never a reason to fall back. + * Chooses the file an installed package loads, without evaluating it. The `./agent-device` export + * wins; a package that lacks that subpath falls back to its root export. A subpath that exists but + * does not resolve is an error, never a reason to fall back. */ -export function discoverPluginEntry(directory: string): PluginPackageEntry { +export function discoverPluginEntry(directory: string): string { const manifest = readPackageJson(directory); const subpath = resolveExport(manifest.exports, PLUGIN_ENTRY_SUBPATH); - if (subpath.status === 'resolved') { - return { kind: 'v2', file: resolvePluginEntry(directory, subpath.target) }; - } + if (subpath.status === 'resolved') return resolvePluginEntry(directory, subpath.target); if (subpath.status === 'blocked') throw unresolvableEntry(directory, PLUGIN_ENTRY_SUBPATH); - if (manifest.agentDevicePlugin !== undefined) { - return { kind: 'v1', manifest: readPluginManifest(directory) }; - } const root = resolveExport(manifest.exports, '.'); if (root.status === 'blocked') throw unresolvableEntry(directory, '.'); const target = @@ -43,7 +32,30 @@ export function discoverPluginEntry(directory: string): PluginPackageEntry { ? `./${path.posix.normalize(manifest.main)}` : undefined; if (target === undefined) throw missingEntry(directory, PLUGIN_ENTRY_SUBPATH); - return { kind: 'v2', file: resolvePluginEntry(directory, target) }; + return resolvePluginEntry(directory, target); +} + +/** + * The entry a plugin package names: a readable file inside the package directory it is installed + * in. Traversal and a symlink out of that directory are refused. + */ +function resolvePluginEntry(directory: string, target: string): string { + try { + const root = fs.realpathSync(directory); + const resolved = fs.realpathSync(path.resolve(directory, target)); + if ( + target.startsWith('./') && + resolved.startsWith(`${root}${path.sep}`) && + fs.statSync(resolved).isFile() + ) { + return resolved; + } + } catch {} + throw new AppError('INVALID_ARGS', 'Plugin entry must be a readable file inside its package', { + reason: 'plugin_load_failed', + directory, + entry: target, + }); } export function readPackageJson(directory: string): Record { diff --git a/packages/plugins/src/legacy.ts b/packages/plugins/src/legacy.ts deleted file mode 100644 index 2a61fddea4..0000000000 --- a/packages/plugins/src/legacy.ts +++ /dev/null @@ -1,90 +0,0 @@ -import { pathToFileURL } from 'node:url'; -import { AppError } from '@agent-device/kernel/errors'; -import { isRecord } from '@agent-device/kernel/record'; -import type { EnvMap } from '@agent-device/kernel/source-value'; -import type { ProviderDeviceRuntime } from '@agent-device/contracts/device'; -import { - PROVIDER_PLUGIN_API_VERSION, - type AgentDevicePlugin, - type PluginConnection, - type PluginSetupResult, -} from './contract.ts'; -import { createPluginHost, type ProviderPluginHost } from './host.ts'; -import { resolvePluginEntry, type PluginManifest } from './manifest.ts'; - -type LegacyConnection = Pick; - -/** - * Presents a v1 plugin as a v2 plugin until 0.22 removes v1. The manifest still declares the - * provider, connection capabilities and credential variables, and the v1 factory still runs with - * the host and returns `{ runtime, platformModule }` or `{ webDriver }`, so no v1 plugin changes. - */ -export function adaptLegacyPlugin( - manifest: PluginManifest, - directory: string, - options: Record | undefined, -): AgentDevicePlugin { - const declaration = manifest.agentDevicePlugin; - const runFactory = async (host: ProviderPluginHost): Promise => { - const module = await import( - pathToFileURL(resolvePluginEntry(directory, declaration.entry)).href - ); - if (typeof module.default !== 'function') - throw new AppError('INVALID_ARGS', `Plugin must export a default factory: ${manifest.name}`, { - reason: 'invalid_plugin', - }); - return await (module.default as (host: ProviderPluginHost) => unknown)(host); - }; - const withConnection = async ( - env: EnvMap, - run: (connection: LegacyConnection) => Promise | T, - ): Promise => { - const result = await runFactory(createPluginHost(env, options)); - try { - const connection = isRecord(result) ? result.connection : undefined; - if ( - !isRecord(connection) || - !isFunction(connection.resolve) || - !isFunction(connection.verify) - ) { - throw new AppError( - 'INVALID_ARGS', - `Plugin connection must provide resolve and verify: ${manifest.name}`, - { reason: 'invalid_plugin' }, - ); - } - return await run(connection as LegacyConnection); - } finally { - const runtime = isRecord(result) - ? (result.runtime as ProviderDeviceRuntime | undefined) - : undefined; - if (isFunction(runtime?.shutdown)) await Promise.allSettled([runtime.shutdown()]); - } - }; - return { - apiVersion: PROVIDER_PLUGIN_API_VERSION, - provider: declaration.provider, - credentials: { variables: declaration.credentialVariables ?? [] }, - ...(declaration.connection - ? { - connection: { - capabilities: declaration.connection, - resolve: async (context) => - await withConnection(context.env, (connection) => connection.resolve(context)), - verify: async (context) => - await withConnection(context.env, (connection) => connection.verify(context)), - }, - } - : {}), - setup: async (host) => { - const result = await runFactory(host); - return ( - isRecord(result) && 'webDriver' in result ? { webDriver: result.webDriver } : result - ) as PluginSetupResult; - }, - }; -} - -function isFunction(value: unknown): value is (...args: never[]) => unknown { - return typeof value === 'function'; -} diff --git a/packages/plugins/src/load.test.ts b/packages/plugins/src/load.test.ts index 1da14a14eb..d18fca5ce5 100644 --- a/packages/plugins/src/load.test.ts +++ b/packages/plugins/src/load.test.ts @@ -5,14 +5,11 @@ import { test } from 'vitest'; import { withPluginConnection } from './load.ts'; import { pluginHome, - registrationSource, - selectPlugin, selectV2Plugin, v2RegistrationSource, webDriverPluginSource, } from '@agent-device/test-kit'; import { AppError } from '@agent-device/kernel/errors'; -import type { ProviderPluginHost } from './host.ts'; import type { PluginRegistryPolicy } from './registry.ts'; import type { ProviderDeviceRuntime } from '@agent-device/contracts/device'; @@ -51,17 +48,27 @@ async function startStore(env: NodeJS.ProcessEnv, builtin: readonly string[] = [ return await startProviderRegistry(resolved, env, FAKE_POLICY); } -test('a v1 store plugin loads through the adapter with options and the host error constructor', async () => { +test('a store plugin loads its factory with the selection options and the host error constructor', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', registrationSource('example')); + selectV2Plugin( + home, + '@example/v2', + v2RegistrationSource('example').replace( + 'options, hostEnv: host.env }', + 'options, hostEnv: host.env, createError: host.createError }', + ), + ); const registry = await startStore(env); - const runtime = registry.registrations[0]!.runtime as ProviderDeviceRuntime & ProviderPluginHost; + const runtime = registry.registrations[0]!.runtime as ProviderDeviceRuntime & { + options: unknown; + createError: (code: 'INVALID_ARGS', message: string) => unknown; + }; assert.deepEqual(runtime.options, { region: 'eu' }); assert.ok(runtime.createError('INVALID_ARGS', 'bad profile') instanceof AppError); await registry.close(); }); -test('a v2 store plugin loads its factory with the selection options', async () => { +test('a plugin package loads its factory with the selection options', async () => { const { home, env } = pluginHome(); selectV2Plugin(home, '@example/v2', v2RegistrationSource('example')); const registry = await startStore(env); @@ -84,10 +91,10 @@ test('a v2 store plugin loads its factory with the selection options', async () await registry.close(); }); -test('v1 and v2 store plugins register in package-name order whichever version they are', async () => { +test('store plugins register in package-name order', async () => { const { home, env } = pluginHome(); selectV2Plugin(home, 'b-plugin', v2RegistrationSource('second')); - selectPlugin(home, 'a-plugin', 'first', registrationSource('first')); + selectV2Plugin(home, 'a-plugin', v2RegistrationSource('first')); const registry = await startStore(env); assert.deepEqual( registry.inventory.map(({ provider, source, package: name }) => [provider, source, name]), @@ -118,7 +125,17 @@ test('a broken plugin is listed as failed while its working neighbor registers', 'e-setup-fails', `export default () => ({ apiVersion: 2, provider: 'setup-fails', credentials: { variables: [] }, setup: async () => { throw new Error('setup failed'); } });`, ); - selectPlugin(home, 'f-bad-owner', 'bad-owner', registrationSource('other-id')); + selectV2Plugin( + home, + 'f-bad-owner', + `export default () => ({ + apiVersion: 2, provider: 'declared-id', credentials: { variables: [] }, + setup: async () => ({ + runtime: { provider: 'other-id', ownsDevice: () => false, getInteractor: () => undefined, + deviceInventoryProvider: async () => [], leaseLifecycle: {}, shutdown: async () => {} }, + platformModule: { owner: { kind: 'provider-runtime', provider: 'other-id', instance: 'test' }, loadRuntime: async () => { throw new Error('lazy'); } } }) + });`, + ); const registry = await startStore(env); assert.deepEqual( @@ -167,16 +184,16 @@ test('the first plugin to name a provider claims it even when it fails, and late await registry.close(); }); -test('a v1 manifest is dispatched before any factory runs and an incompatible one is only listed', async () => { +test('a package whose factory returns the v1 shape is listed as incompatible', async () => { const { home, env } = pluginHome(); - const marker = path.join(home, 'evaluated'); - selectPlugin( + selectV2Plugin( home, - 'one', - 'one', - `import fs from 'node:fs'; fs.writeFileSync(${JSON.stringify(marker)}, 'yes');`, + 'v1-factory', + `export default () => ({ + runtime: { provider: 'v1-factory', ownsDevice: () => false, getInteractor: () => undefined, + deviceInventoryProvider: async () => [], leaseLifecycle: {}, shutdown: async () => {} }, + platformModule: { owner: { kind: 'provider-runtime', provider: 'v1-factory', instance: 'test' }, loadRuntime: async () => { throw new Error('lazy'); } } });`, ); - selectPlugin(home, 'two', 'other', 'throw new Error("evaluated");', 2); const { resolveProviderPlugins, claimProviderIds } = await import('./registry.ts'); const { storePluginCandidates } = await import('./store.ts'); const resolved = await resolveProviderPlugins([ @@ -184,13 +201,11 @@ test('a v1 manifest is dispatched before any factory runs and an incompatible on ...(await storePluginCandidates(env)), ]); - assert.ok(!fs.existsSync(marker)); + // A v1 package used to be dispatched from its manifest and registered; the contract version is + // now the only way in, so it is listed and skipped like any other incompatible plugin. assert.deepEqual( resolved.inventory().map(({ package: name, state, error }) => [name, state, error?.reason]), - [ - ['one', 'active', undefined], - ['two', 'failed', 'incompatible_plugin'], - ], + [['v1-factory', 'failed', 'incompatible_plugin']], ); }); @@ -231,16 +246,16 @@ test('entry discovery prefers ./agent-device and falls back to the root export o }); test('startup failure of one plugin cleans up its constructed runtime and keeps the others', async () => { - for (const instance of ["'test'", 'undefined', '42', '" "']) { + for (const instance of ['null', 'undefined', '42', '" "']) { const { home, env } = pluginHome(); const first = path.join(home, 'first-shutdown'); const invalid = path.join(home, 'invalid-shutdown'); - selectPlugin(home, 'one', 'one', registrationSource('one', first)); - const source = registrationSource(instance === "'test'" ? 'wrong' : 'two', invalid).replace( + selectV2Plugin(home, 'one', v2RegistrationSource('one', { shutdownFile: first })); + const source = v2RegistrationSource('two', { shutdownFile: invalid }).replace( "instance: 'test'", `instance: ${instance}`, ); - selectPlugin(home, 'two', 'two', source); + selectV2Plugin(home, 'two', source); const registry = await startStore(env); assert.deepEqual( registry.registrations.map(({ provider }) => provider), @@ -307,49 +322,7 @@ test('a frozen runtime registers untouched, serves its facets, and is shut down assert.equal(fs.readFileSync(log, 'utf8'), 'runtime;dispose;'); }); -test('connection callbacks run from a v1 plugin and always release its runtime', async () => { - const { home, env } = pluginHome(); - const marker = path.join(home, 'shutdown'); - const source = registrationSource('example', marker).replace( - 'platformModule:', - "connection: { resolve: () => ({ profile: { leaseProvider: 'example', platform: 'android' } }), verify: async () => { throw host.createError('COMMAND_FAILED', 'verification failed'); } }, platformModule:", - ); - selectPlugin(home, 'example', 'example', source); - selectPlugin(home, 'unrelated', 'unrelated', 'throw new Error("unrelated plugin evaluated");'); - const manifestPath = path.join( - home, - 'plugins', - JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')).plugins.example - .installation, - 'node_modules/example/package.json', - ); - const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - manifest.agentDevicePlugin.connection = LOCAL_CONNECTION; - fs.writeFileSync(manifestPath, JSON.stringify(manifest)); - const flags = { json: false, help: false, version: false }; - - const profile = await withPluginConnection( - 'example', - ['limrun'], - env, - async (connection) => await connection.resolve({ flags, stateDir: home, cwd: home, env }), - ); - assert.equal(profile.profile.platform, 'android'); - assert.ok(fs.existsSync(marker)); - fs.unlinkSync(marker); - await assert.rejects( - withPluginConnection( - 'example', - ['limrun'], - env, - async (connection) => await connection.verify({ flags, env }), - ), - { code: 'COMMAND_FAILED' }, - ); - assert.ok(fs.existsSync(marker)); -}); - -test('a v2 plugin connection runs without setting up any runtime', async () => { +test('a plugin connection runs without setting up any runtime', async () => { const { home, env } = pluginHome(); const marker = path.join(home, 'setup-ran'); selectV2Plugin( @@ -397,7 +370,7 @@ const LOCAL_CONNECTION = { test('a WebDriver descriptor is adapted by the policy, and a mismatched provider never reaches it', async () => { const { home, env } = pluginHome(); const source = webDriverPluginSource('example'); - selectPlugin(home, 'example', 'example', source); + selectV2Plugin(home, 'example', source); const registry = await startStore(env, []); assert.deepEqual( registry.registrations.map(({ provider, runtime }) => [provider, runtime.provider]), @@ -408,7 +381,12 @@ test('a WebDriver descriptor is adapted by the policy, and a mismatched provider adaptedDescriptors.length = 0; const other = pluginHome(); - selectPlugin(other.home, 'example', 'wrong', source); + selectV2Plugin( + other.home, + 'example', + // The descriptor names a provider the plugin did not declare. + source.replace('"provider":"example","endpoint"', '"provider":"wrong","endpoint"'), + ); const mismatched = await startStore(other.env, []); assert.deepEqual(mismatched.registrations, []); assert.equal(mismatched.inventory[0]!.error?.reason, 'invalid_plugin'); @@ -418,7 +396,7 @@ test('a WebDriver descriptor is adapted by the policy, and a mismatched provider test('a factory returning a primitive is listed as an invalid plugin', async () => { for (const value of ['42', '"runtime"', 'true']) { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', `export default () => ${value};`); + selectV2Plugin(home, 'example', `export default () => ${value};`); const registry = await startStore(env, []); assert.deepEqual(registry.registrations, []); assert.equal(registry.inventory[0]!.state, 'failed'); diff --git a/packages/plugins/src/manifest.test.ts b/packages/plugins/src/manifest.test.ts deleted file mode 100644 index e676087558..0000000000 --- a/packages/plugins/src/manifest.test.ts +++ /dev/null @@ -1,90 +0,0 @@ -import assert from 'node:assert/strict'; -import fs from 'node:fs'; -import path from 'node:path'; -import { test } from 'vitest'; -import { readPluginManifest } from './manifest.ts'; -import { pluginHome, writePlugin } from '@agent-device/test-kit'; - -test('manifest compatibility is checked without evaluating plugin code', () => { - const { home } = pluginHome(); - const directory = writePlugin(home); - assert.equal(readPluginManifest(directory).agentDevicePlugin.provider, 'example'); - writePlugin(home, '@example/provider', 2); - assert.throws(() => readPluginManifest(directory), { - code: 'INVALID_ARGS', - details: { - reason: 'incompatible_plugin', - apiVersion: 1, - hint: 'Install a plugin release supporting agentDevicePlugin.apiVersion 1.', - }, - }); -}); - -test('manifest refuses traversal and symlink entries outside the installed package', () => { - const { home } = pluginHome(); - const directory = writePlugin(home); - const outside = path.join(home, 'outside.js'); - fs.writeFileSync(outside, 'throw new Error("outside");'); - fs.unlinkSync(path.join(directory, 'plugin.js')); - fs.symlinkSync(outside, path.join(directory, 'plugin.js')); - assert.throws(() => readPluginManifest(directory), { code: 'INVALID_ARGS' }); - const manifest = JSON.parse(fs.readFileSync(path.join(directory, 'package.json'), 'utf8')); - manifest.agentDevicePlugin.entry = '../../../outside.js'; - fs.writeFileSync(path.join(directory, 'package.json'), JSON.stringify(manifest)); - assert.throws(() => readPluginManifest(directory), { code: 'INVALID_ARGS' }); -}); - -test('connection metadata admits local providers and rejects malformed or remote policies', () => { - const { home } = pluginHome(); - const directory = writePlugin(home); - const file = path.join(directory, 'package.json'); - const manifest = JSON.parse(fs.readFileSync(file, 'utf8')); - const connection = { - leaseKind: 'direct-device-provider', - requiresAppAttachment: true, - requiresRemoteDaemon: false, - supportsArtifacts: true, - supportsDeferredAppSelection: false, - supportsDirectPortReverse: false, - usesCloudWebDriverLease: true, - }; - const read = (policy: unknown) => { - manifest.agentDevicePlugin.connection = policy; - fs.writeFileSync(file, JSON.stringify(manifest)); - return readPluginManifest(directory); - }; - assert.deepEqual(read(connection).agentDevicePlugin.connection, connection); - const cloud = { ...connection, holdsCloudDevice: true, forgetsEndedConnectionLease: true }; - assert.deepEqual(read(cloud).agentDevicePlugin.connection, cloud); - for (const invalid of [ - null, - {}, - { ...connection, leaseKind: 'remote-daemon' }, - { ...connection, requiresRemoteDaemon: true }, - { ...connection, supportsArtifacts: 'true' }, - { ...connection, supportsDeferredAppSelection: undefined }, - { ...connection, holdsCloudDevice: 'false' }, - { ...connection, forgetsEndedConnectionLease: 'false' }, - ]) { - assert.throws(() => read(invalid), { code: 'INVALID_ARGS' }); - } -}); - -test('credential variables are optional environment variable names', () => { - const { home } = pluginHome(); - const directory = writePlugin(home); - const file = path.join(directory, 'package.json'); - const manifest = JSON.parse(fs.readFileSync(file, 'utf8')); - const read = (credentialVariables: unknown) => { - manifest.agentDevicePlugin.credentialVariables = credentialVariables; - fs.writeFileSync(file, JSON.stringify(manifest)); - return readPluginManifest(directory); - }; - assert.equal(read(undefined).agentDevicePlugin.credentialVariables, undefined); - assert.deepEqual(read(['EXAMPLE_USER', '_KEY_2']).agentDevicePlugin.credentialVariables, [ - 'EXAMPLE_USER', - '_KEY_2', - ]); - for (const invalid of [null, 'EXAMPLE_USER', {}, [''], ['example_user'], ['2KEY'], ['A-B'], [1]]) - assert.throws(() => read(invalid), { code: 'INVALID_ARGS' }, JSON.stringify(invalid)); -}); diff --git a/packages/plugins/src/manifest.ts b/packages/plugins/src/manifest.ts deleted file mode 100644 index 0422c38cee..0000000000 --- a/packages/plugins/src/manifest.ts +++ /dev/null @@ -1,118 +0,0 @@ -import fs from 'node:fs'; -import path from 'node:path'; -import { AppError } from '@agent-device/kernel/errors'; -import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; - -/** Provider ids that name daemon routing, not a runtime a plugin can supply. */ -export const ROUTING_PROVIDER_IDENTITIES: readonly string[] = ['cloud', 'proxy']; - -const V1_PLUGIN_API_VERSION = 1; - -/** A v1 plugin package: the manifest declares what the host reads before any plugin code runs. */ -export type PluginManifest = { - name: string; - version: string; - agentDevicePlugin: { - apiVersion: number; - provider: string; - entry: string; - connection?: ConnectionProviderCapabilities; - credentialVariables?: string[]; - }; -}; - -const ENVIRONMENT_VARIABLE = /^[A-Z_][A-Z0-9_]*$/; - -function invalidManifest(message: string): AppError { - return new AppError('INVALID_ARGS', message, { reason: 'invalid_plugin' }); -} - -export function assertLocalConnectionCapabilities( - policy: ConnectionProviderCapabilities | undefined, -): void { - if (policy === undefined) return; - if ( - !policy || - typeof policy !== 'object' || - policy.leaseKind !== 'direct-device-provider' || - [ - 'requiresAppAttachment', - 'requiresRemoteDaemon', - 'supportsArtifacts', - 'supportsDeferredAppSelection', - 'supportsDirectPortReverse', - 'usesCloudWebDriverLease', - ].some((key) => typeof policy[key as keyof ConnectionProviderCapabilities] !== 'boolean') || - (policy.holdsCloudDevice !== undefined && typeof policy.holdsCloudDevice !== 'boolean') || - (policy.forgetsEndedConnectionLease !== undefined && - typeof policy.forgetsEndedConnectionLease !== 'boolean') || - policy.requiresRemoteDaemon - ) { - throw invalidManifest('Plugin connection must declare local provider capabilities'); - } -} - -export function assertCredentialVariables(variables: unknown): void { - if ( - variables !== undefined && - (!Array.isArray(variables) || - !variables.every((name) => typeof name === 'string' && ENVIRONMENT_VARIABLE.test(name))) - ) { - throw invalidManifest('Plugin credential variables must list environment variable names'); - } -} - -export function readPluginManifest(directory: string): PluginManifest { - let manifest: PluginManifest; - try { - const file = path.join(directory, 'package.json'); - manifest = JSON.parse(fs.readFileSync(file, 'utf8')) as PluginManifest; - } catch (error) { - throw new AppError( - 'INVALID_ARGS', - `Cannot read plugin manifest: ${directory}`, - {}, - error as Error, - ); - } - const declaration = manifest?.agentDevicePlugin; - if ( - typeof manifest?.name !== 'string' || - typeof manifest?.version !== 'string' || - !declaration || - declaration.apiVersion !== V1_PLUGIN_API_VERSION || - typeof declaration.provider !== 'string' || - !/^[a-z][a-z0-9-]*$/.test(declaration.provider) || - typeof declaration.entry !== 'string' || - !declaration.entry.startsWith('./') - ) { - throw new AppError('INVALID_ARGS', 'Package does not declare a compatible provider plugin', { - reason: 'incompatible_plugin', - apiVersion: V1_PLUGIN_API_VERSION, - hint: `Install a plugin release supporting agentDevicePlugin.apiVersion ${V1_PLUGIN_API_VERSION}.`, - }); - } - resolvePluginEntry(directory, declaration.entry); - assertLocalConnectionCapabilities(declaration.connection); - assertCredentialVariables(declaration.credentialVariables); - return manifest as PluginManifest; -} - -export function resolvePluginEntry(directory: string, target: string): string { - try { - const root = fs.realpathSync(directory); - const resolved = fs.realpathSync(path.resolve(directory, target)); - if ( - target.startsWith('./') && - resolved.startsWith(`${root}${path.sep}`) && - fs.statSync(resolved).isFile() - ) { - return resolved; - } - } catch {} - throw new AppError('INVALID_ARGS', 'Plugin entry must be a readable file inside its package', { - reason: 'plugin_load_failed', - directory, - entry: target, - }); -} diff --git a/packages/plugins/src/registry.ts b/packages/plugins/src/registry.ts index e5b2e9cb90..00acf6328f 100644 --- a/packages/plugins/src/registry.ts +++ b/packages/plugins/src/registry.ts @@ -20,7 +20,7 @@ import { } from '@agent-device/contracts/plugin-inventory'; import { describePluginFailure } from './inventory.ts'; import { isProviderId } from './discovery.ts'; -import { ROUTING_PROVIDER_IDENTITIES } from './manifest.ts'; +import { ROUTING_PROVIDER_IDENTITIES } from './contract.ts'; import { assertProviderRuntime, invalidPlugin, validateAgentDevicePlugin } from './validate.ts'; /** @@ -31,11 +31,11 @@ export type PluginCandidate = Readonly<{ source: PluginSource; package?: string; version?: string; - /** Known before the plugin loads, such as a v1 manifest; a load failure still claims it. */ + /** Claims `provider` before its load settles, so a later candidate with that id is a duplicate. Dormant candidates claim it without loading. */ provider?: string; /** Claims `provider` without registering or listing: a built-in that is not configured. */ dormant?: boolean; - /** The `options` the store passes to the host, which a v1 plugin reads. */ + /** The `options` the store passes to the host when it calls the factory. */ hostOptions?: Record; /** Returns the unvalidated plugin, or throws the reason it cannot load. */ load(): Promise | unknown; diff --git a/packages/plugins/src/store-legacy.ts b/packages/plugins/src/store-legacy.ts deleted file mode 100644 index 8d82695809..0000000000 --- a/packages/plugins/src/store-legacy.ts +++ /dev/null @@ -1,83 +0,0 @@ -import fs from 'node:fs'; -import path from 'node:path'; -import { AppError } from '@agent-device/kernel/errors'; -import { isRecord } from '@agent-device/kernel/record'; -import { resolveUserConfigPath } from '@agent-device/host-kit/file'; -import { readPluginManifest, type PluginManifest } from './manifest.ts'; - -export type PluginSelection = { - installation: string; - version?: string; - options?: Record; -}; -type PluginConfig = Record & { plugins?: Record }; -export function readPluginConfig(env: NodeJS.ProcessEnv): PluginConfig { - const configPath = resolveUserConfigPath(env); - try { - const config = JSON.parse(fs.readFileSync(configPath, 'utf8')) as PluginConfig; - if (!isRecord(config) || (config.plugins !== undefined && !isRecord(config.plugins))) - throw new AppError('INVALID_ARGS', 'Plugin config must contain an object'); - return config; - } catch (error) { - if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {}; - if (error instanceof SyntaxError) - throw new AppError('INVALID_ARGS', `Invalid plugin JSON: ${configPath}`, {}, error); - throw error; - } -} - -export function validatePluginSelection(name: string, selection: PluginSelection): void { - if ( - !isPackageName(name) || - !isRecord(selection) || - typeof selection.installation !== 'string' || - !/^[a-f0-9-]{36}$/.test(selection.installation) || - (selection.version !== undefined && !isVersionSelector(selection.version)) || - (selection.options !== undefined && !isRecord(selection.options)) - ) { - throw new AppError('INVALID_ARGS', `Invalid plugin selection: ${name}`); - } -} - -export function storeHome(env: NodeJS.ProcessEnv): string { - return path.dirname(resolveUserConfigPath(env)); -} - -export function installationDirectory(home: string, name: string, installation: string): string { - return path.join(home, 'plugins', installation, 'node_modules', name); -} - -/** - * The v1 manifests in the store, read without executing anything, including those of a package - * that also exports `./agent-device`; unreadable selections are skipped. - */ -export function legacyStoreManifests(env: NodeJS.ProcessEnv): PluginManifest[] { - const home = storeHome(env); - let selections: [string, PluginSelection][]; - try { - selections = Object.entries(readPluginConfig(env).plugins ?? {}); - } catch { - return []; - } - return selections.flatMap(([name, selection]) => { - try { - validatePluginSelection(name, selection); - const manifest = readPluginManifest( - installationDirectory(home, name, selection.installation), - ); - return manifest.name === name ? [manifest] : []; - } catch { - return []; - } - }); -} - -function isPackageName(value: string): boolean { - return /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value); -} - -export function isVersionSelector(value: unknown): value is string { - return ( - typeof value === 'string' && /^[a-zA-Z0-9*^~<>=| .+-]+$/.test(value) && value.trim().length > 0 - ); -} diff --git a/packages/plugins/src/store.test.ts b/packages/plugins/src/store.test.ts index 0a46f95f82..6e30bbcf85 100644 --- a/packages/plugins/src/store.test.ts +++ b/packages/plugins/src/store.test.ts @@ -3,14 +3,8 @@ import fs from 'node:fs'; import path from 'node:path'; import { afterEach, test, vi } from 'vitest'; import { runCmd } from '@agent-device/host-kit/command'; -import { changePlugin, legacyStoreManifests, listPlugins } from './store.ts'; -import { - pluginHome, - selectPlugin, - selectV2Plugin, - v2RegistrationSource, - writePlugin, -} from '@agent-device/test-kit'; +import { changePlugin, listPlugins } from './store.ts'; +import { pluginHome, selectV2Plugin, v2RegistrationSource } from '@agent-device/test-kit'; vi.mock('@agent-device/host-kit/command', () => ({ runCmd: vi.fn() })); afterEach(() => vi.mocked(runCmd).mockReset()); @@ -33,7 +27,8 @@ function installedPlugins(env: NodeJS.ProcessEnv) { }); } -function installFixture(name = packageName, apiVersion = 1, provider = 'example') { +/** Stands in for `npm install`: writes a v2 plugin package into the staged project. */ +function installFixture(name = packageName, provider = 'example') { vi.mocked(runCmd).mockImplementation(async (command, argv, options) => { assert.equal(command, 'npm'); assert.equal(argv[argv.indexOf('--prefix') + 1], options!.cwd); @@ -41,7 +36,18 @@ function installFixture(name = packageName, apiVersion = 1, provider = 'example' assert.ok(argv.includes('--ignore-scripts')); assert.ok(argv.includes('--workspaces=false')); assert.ok(argv.includes('--package-lock=true')); - writePlugin(options!.cwd!, name, apiVersion, provider); + const directory = path.join(options!.cwd!, 'node_modules', name); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name, + version: '1.2.3', + type: 'module', + exports: { './agent-device': { import: './plugin.mjs' } }, + }), + ); + fs.writeFileSync(path.join(directory, 'plugin.mjs'), v2RegistrationSource(provider)); return { stdout: '', stderr: '', exitCode: 0 }; }); } @@ -50,13 +56,13 @@ test('add, pinned update and remove preserve flags, options and old installation const { home, env } = pluginHome(); fs.writeFileSync(path.join(home, 'config.json'), JSON.stringify({ platform: 'android' })); installFixture(); - await changePlugin('add', `${packageName}@1.2.3`, env, []); + await changePlugin('add', `${packageName}@1.2.3`, env); const [first] = installedPlugins(env); const config = readPluginConfig(env); config.plugins![packageName]!.options = { region: 'eu' }; config.plugins![packageName]!.installation = '../damaged'; fs.writeFileSync(path.join(home, 'config.json'), JSON.stringify(config)); - await changePlugin('update', packageName, env, []); + await changePlugin('update', packageName, env); const [second] = installedPlugins(env); assert.notEqual(first!.directory, second!.directory); assert.deepEqual(second!.selection.options, { region: 'eu' }); @@ -66,7 +72,7 @@ test('add, pinned update and remove preserve flags, options and old installation { [packageName]: '1.2.3' }, ); assert.equal(readPluginConfig(env).platform, 'android'); - await changePlugin('remove', packageName, env, []); + await changePlugin('remove', packageName, env); assert.deepEqual(installedPlugins(env), []); assert.ok(fs.existsSync(first!.directory)); assert.ok(fs.existsSync(second!.directory)); @@ -75,31 +81,83 @@ test('add, pinned update and remove preserve flags, options and old installation test('failed npm install and incompatible replacement preserve the active selection', async () => { const { home, env } = pluginHome(); installFixture(); - await changePlugin('add', packageName, env, []); + await changePlugin('add', packageName, env); const before = fs.readFileSync(path.join(home, 'config.json'), 'utf8'); vi.mocked(runCmd).mockRejectedValue(new Error('npm failed')); - await assert.rejects(changePlugin('update', packageName, env, []), /npm failed/); + await assert.rejects(changePlugin('update', packageName, env), /npm failed/); assert.equal(fs.readFileSync(path.join(home, 'config.json'), 'utf8'), before); - installFixture(packageName, 2); - await assert.rejects(changePlugin('update', packageName, env, []), { code: 'INVALID_ARGS' }); + // The replacement exports neither ./agent-device nor a root entry, so it is not a plugin package. + vi.mocked(runCmd).mockImplementation(async (_command, _argv, options) => { + const directory = path.join(options!.cwd!, 'node_modules', packageName); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name: packageName, + version: '2.0.0', + type: 'module', + exports: { './tools': './tools.js' }, + }), + ); + fs.writeFileSync(path.join(directory, 'tools.js'), 'export {};'); + return { stdout: '', stderr: '', exitCode: 0 }; + }); + await assert.rejects(changePlugin('update', packageName, env), { code: 'INVALID_ARGS' }); assert.equal(fs.readFileSync(path.join(home, 'config.json'), 'utf8'), before); assert.equal(fs.readdirSync(path.join(home, 'plugins')).length, 1); }); +test('a factory shaped for the removed v1 contract still installs', async () => { + const { env } = pluginHome(); + vi.mocked(runCmd).mockImplementation(async (_command, _argv, options) => { + const directory = path.join(options!.cwd!, 'node_modules', packageName); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name: packageName, + version: '1.2.3', + type: 'module', + exports: { './agent-device': { import: './plugin.mjs' } }, + }), + ); + fs.writeFileSync(path.join(directory, 'plugin.mjs'), 'export default () => ({ register: 1 });'); + return { stdout: '', stderr: '', exitCode: 0 }; + }); + // Installation only needs a loadable default export; the registry rejects the shape later. + await changePlugin('add', packageName, env); + const [listed] = await listPlugins(env, []); + assert.deepEqual( + { name: listed?.name, compatible: listed?.compatible }, + { name: packageName, compatible: false }, + ); +}); + test('concurrent additions serialize without dropping the other package', async () => { const { env } = pluginHome(); vi.mocked(runCmd).mockImplementation(async (_, __, options) => { const { dependencies } = JSON.parse( fs.readFileSync(path.join(options!.cwd!, 'package.json'), 'utf8'), ); - const name = Object.keys(dependencies)[0]!; - writePlugin(options!.cwd!, name, 1, name); + const name: string = Object.keys(dependencies)[0]!; + const directory = path.join(options!.cwd!, 'node_modules', name); + fs.mkdirSync(directory, { recursive: true }); + fs.writeFileSync( + path.join(directory, 'package.json'), + JSON.stringify({ + name, + version: '1.2.3', + type: 'module', + exports: { './agent-device': { import: './plugin.mjs' } }, + }), + ); + fs.writeFileSync( + path.join(directory, 'plugin.mjs'), + v2RegistrationSource(name.toLowerCase().replaceAll(/[^a-z0-9-]/g, '-')), + ); return { stdout: '', stderr: '', exitCode: 0 }; }); - await Promise.all([ - changePlugin('add', 'constructor', env, []), - changePlugin('add', 'two', env, []), - ]); + await Promise.all([changePlugin('add', 'constructor', env), changePlugin('add', 'two', env)]); assert.deepEqual( installedPlugins(env) .map(({ name }) => name) @@ -117,43 +175,52 @@ test('invalid package sources and damaged selections fail before invoking npm', 'plugin@npm:other', 'https://example.com/plugin', ]) { - await assert.rejects(changePlugin('add', name, env, []), { code: 'INVALID_ARGS' }); + await assert.rejects(changePlugin('add', name, env), { code: 'INVALID_ARGS' }); } fs.writeFileSync( path.join(home, 'config.json'), JSON.stringify({ plugins: { one: { installation: '../other' } } }), ); assert.equal((await listPlugins(env, []))[0]?.compatible, false); - await changePlugin('remove', 'one', env, []); + await changePlugin('remove', 'one', env); assert.deepEqual(await listPlugins(env, []), []); fs.writeFileSync( path.join(home, 'config.json'), JSON.stringify({ plugins: { UPPERCASE: null } }), ); - await changePlugin('remove', 'UPPERCASE', env, []); + await changePlugin('remove', 'UPPERCASE', env); assert.deepEqual(await listPlugins(env, []), []); assert.equal(vi.mocked(runCmd).mock.calls.length, 0); }); -test('provider collisions refuse activation and preserve existing selections', async () => { - const { env } = pluginHome(); - installFixture(); - await assert.rejects(changePlugin('add', packageName, env, ['example']), { - code: 'INVALID_ARGS', - }); - assert.deepEqual(installedPlugins(env), []); - await changePlugin('add', packageName, env, []); - installFixture('other'); - await assert.rejects(changePlugin('add', 'other', env, []), { code: 'INVALID_ARGS' }); - assert.equal(installedPlugins(env).length, 1); +test('a duplicate provider id is settled by the registry when the store composes', async () => { + const { home, env } = pluginHome(); + selectV2Plugin(home, 'first', v2RegistrationSource('example')); + selectV2Plugin(home, 'second', v2RegistrationSource('example')); + const listed = await listPlugins(env, []); + assert.deepEqual( + listed.map(({ name, compatible, error }) => [name, compatible, error?.reason]), + [ + ['first', true, undefined], + ['second', false, 'duplicate_provider'], + ], + ); + // A dormant built-in claims the id first, so a store package cannot take it either. + const { home: otherHome, env: otherEnv } = pluginHome(); + selectV2Plugin(otherHome, 'limrun-plugin', v2RegistrationSource('limrun')); + const limrun = await listPlugins(otherEnv, ['limrun']); + assert.deepEqual( + limrun.map(({ name, compatible, error }) => [name, compatible, error?.reason]), + [['limrun-plugin', false, 'duplicate_provider']], + ); }); test('broken siblings do not block pinned updates or unrelated additions', async () => { - for (const damage of ['missing', 'json', 'abi']) { + for (const damage of ['missing', 'json', 'load']) { const { home, env } = pluginHome(); installFixture(); - await changePlugin('add', `${packageName}@1.2.3`, env, []); - selectPlugin(home, 'broken', 'broken', 'throw new Error("must not evaluate");', 2); + await changePlugin('add', `${packageName}@1.2.3`, env); + selectV2Plugin(home, 'broken', 'throw new Error("must not evaluate");'); const config = readPluginConfig(env); config.plugins![packageName]!.options = { region: 'eu' }; fs.writeFileSync(path.join(home, 'config.json'), JSON.stringify(config)); @@ -161,13 +228,13 @@ test('broken siblings do not block pinned updates or unrelated additions', async if (damage === 'missing') fs.rmSync(directory, { recursive: true }); if (damage === 'json') fs.writeFileSync(path.join(directory, 'node_modules/broken/package.json'), '{'); - await changePlugin('update', packageName, env, []); + await changePlugin('update', packageName, env); const repaired = readPluginConfig(env).plugins![packageName]!; assert.deepEqual(repaired.options, { region: 'eu' }); assert.equal(repaired.version, '1.2.3'); assert.deepEqual(readPluginConfig(env).plugins!.broken, config.plugins!.broken); - installFixture('other', 1, 'other'); - await changePlugin('add', 'other', env, []); + installFixture('other', 'other'); + await changePlugin('add', 'other', env); const listed = await listPlugins(env, []); assert.deepEqual( listed.map(({ name, compatible }) => [name, compatible]), @@ -179,28 +246,3 @@ test('broken siblings do not block pinned updates or unrelated additions', async ); } }); - -test('a package that declares the v1 manifest and exports ./agent-device still supplies its manifest', () => { - const { home, env } = pluginHome(); - const directory = selectV2Plugin(home, 'dual', v2RegistrationSource('dual'), { - manifest: { - agentDevicePlugin: { - apiVersion: 1, - provider: 'dual', - entry: './plugin.mjs', - credentialVariables: ['DUAL_KEY'], - }, - }, - }); - selectV2Plugin(home, 'v2-only', v2RegistrationSource('v2-only')); - assert.deepEqual( - legacyStoreManifests(env).map((manifest) => manifest.agentDevicePlugin.credentialVariables), - [['DUAL_KEY']], - ); - - // An installation that holds another package supplies nothing under this selection's name. - const manifestPath = path.join(directory, 'package.json'); - const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - fs.writeFileSync(manifestPath, JSON.stringify({ ...manifest, name: 'someone-else' })); - assert.deepEqual(legacyStoreManifests(env), []); -}); diff --git a/packages/plugins/src/store.ts b/packages/plugins/src/store.ts index db1dcd0af3..8faf7ec77b 100644 --- a/packages/plugins/src/store.ts +++ b/packages/plugins/src/store.ts @@ -1,12 +1,3 @@ -import { - legacyStoreManifests, - readPluginConfig, - validatePluginSelection, - storeHome, - installationDirectory, - isVersionSelector, - type PluginSelection, -} from './store-legacy.ts'; import crypto from 'node:crypto'; import fs from 'node:fs'; import path from 'node:path'; @@ -20,18 +11,67 @@ import { resolveUserConfigPath, } from '@agent-device/host-kit/file'; import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; -import type { PluginPackageEntry } from './discovery.ts'; -import { ROUTING_PROVIDER_IDENTITIES, type PluginManifest } from './manifest.ts'; import type { PluginCandidate } from './registry.ts'; -export { legacyStoreManifests }; +export type PluginSelection = { + installation: string; + version?: string; + options?: Record; +}; +type PluginConfig = Record & { plugins?: Record }; + +function readPluginConfig(env: NodeJS.ProcessEnv): PluginConfig { + const configPath = resolveUserConfigPath(env); + try { + const config = JSON.parse(fs.readFileSync(configPath, 'utf8')) as PluginConfig; + if (!isRecord(config) || (config.plugins !== undefined && !isRecord(config.plugins))) + throw new AppError('INVALID_ARGS', 'Plugin config must contain an object'); + return config; + } catch (error) { + if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {}; + if (error instanceof SyntaxError) + throw new AppError('INVALID_ARGS', `Invalid plugin JSON: ${configPath}`, {}, error); + throw error; + } +} + +function validatePluginSelection(name: string, selection: PluginSelection): void { + if ( + !isPackageName(name) || + !isRecord(selection) || + typeof selection.installation !== 'string' || + !/^[a-f0-9-]{36}$/.test(selection.installation) || + (selection.version !== undefined && !isVersionSelector(selection.version)) || + (selection.options !== undefined && !isRecord(selection.options)) + ) { + throw new AppError('INVALID_ARGS', `Invalid plugin selection: ${name}`); + } +} + +function storeHome(env: NodeJS.ProcessEnv): string { + return path.dirname(resolveUserConfigPath(env)); +} + +function installationDirectory(home: string, name: string, installation: string): string { + return path.join(home, 'plugins', installation, 'node_modules', name); +} + +function isPackageName(value: string): boolean { + return /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value); +} + +function isVersionSelector(value: unknown): value is string { + return ( + typeof value === 'string' && /^[a-zA-Z0-9*^~<>=| .+-]+$/.test(value) && value.trim().length > 0 + ); +} type StoreInstallation = { name: string; version: string; directory: string; selection: PluginSelection; - entry: PluginPackageEntry; + entry: string; }; async function describeInstallation( @@ -61,12 +101,8 @@ async function readInstallation(home: string, name: string, selection: PluginSel ); } -async function loadInstallation({ name, directory, selection, entry }: StoreInstallation) { - if (entry.kind === 'v1') { - const { adaptLegacyPlugin } = await import('./legacy.ts'); - return adaptLegacyPlugin(entry.manifest, directory, selection.options); - } - const module = await import(pathToFileURL(entry.file).href); +async function loadInstallation({ name, entry, selection }: StoreInstallation) { + const module = await import(pathToFileURL(entry).href); if (typeof module.default !== 'function') throw new AppError('INVALID_ARGS', `Plugin must export a default factory: ${name}`, { reason: 'invalid_plugin', @@ -77,7 +113,8 @@ async function loadInstallation({ name, directory, selection, entry }: StoreInst /** * The store's contribution to the provider registry, in package-name order. Nothing here runs * plugin code: a selection or package that cannot be read becomes a candidate that fails when - * loaded, so one damaged installation never hides the others. + * loaded, so one damaged installation never hides the others. A store package names its provider + * only once its factory runs, and the registry settles a duplicate then. */ export async function storePluginCandidates(env: NodeJS.ProcessEnv): Promise { const home = storeHome(env); @@ -96,9 +133,6 @@ export async function storePluginCandidates(env: NodeJS.ProcessEnv): Promise loadInstallation(installation), }; @@ -207,11 +241,16 @@ async function stagePlugin( } } +/** + * Installs, updates or removes one plugin selection. Install checks the staged package's identity + * and version and resolves its entry to a readable file; the factory first runs when the daemon next + * composes its plugins. A provider-id clash with another plugin or a built-in is the registry's to + * settle then, by first claim. + */ export async function changePlugin( action: PluginAction, input: string, env: NodeJS.ProcessEnv, - reservedProviders: readonly string[], ): Promise { const { name, version } = parsePluginRequest(action, input); const configPath = resolveUserConfigPath(env); @@ -234,13 +273,6 @@ export async function changePlugin( const requested = action === 'update' && isVersionSelector(previous?.version) ? previous.version : version; staged = await stagePlugin(home, name, requested, env); - assertUniqueLegacyProviders( - [ - ...legacyStoreManifests(env).filter((manifest) => manifest.name !== name), - ...(staged.entry.kind === 'v1' ? [staged.entry.manifest] : []), - ], - reservedProviders, - ); selections[name] = { installation: staged.installation, version: requested, @@ -259,23 +291,3 @@ export async function changePlugin( await release(); } } - -// A v1 manifest names its provider before any code runs, so a clash is refused at install time. A -// v2 package names its provider only once loaded; the registry records a clash then. -function assertUniqueLegacyProviders( - manifests: readonly PluginManifest[], - reserved: readonly string[], -): void { - const providers = new Set([...ROUTING_PROVIDER_IDENTITIES, ...reserved]); - for (const { agentDevicePlugin } of manifests) { - if (providers.has(agentDevicePlugin.provider)) - throw new AppError( - 'INVALID_ARGS', - `Duplicate provider plugin: ${agentDevicePlugin.provider}`, - { - reason: 'duplicate_provider', - }, - ); - providers.add(agentDevicePlugin.provider); - } -} diff --git a/packages/plugins/src/validate.ts b/packages/plugins/src/validate.ts index 9c573d495a..6fe6008f84 100644 --- a/packages/plugins/src/validate.ts +++ b/packages/plugins/src/validate.ts @@ -1,15 +1,16 @@ import { AppError } from '@agent-device/kernel/errors'; import { isRecord } from '@agent-device/kernel/record'; import { isProviderId } from './discovery.ts'; -import { - assertCredentialVariables, - assertLocalConnectionCapabilities, - ROUTING_PROVIDER_IDENTITIES, -} from './manifest.ts'; import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; import type { ProviderDeviceRuntime } from '@agent-device/contracts/device'; import type { PlatformRuntimeProviderModule } from '@agent-device/contracts/platform-runtime-operations'; -import { PROVIDER_PLUGIN_API_VERSION, type AgentDevicePlugin } from './contract.ts'; +import { + PROVIDER_PLUGIN_API_VERSION, + ROUTING_PROVIDER_IDENTITIES, + type AgentDevicePlugin, +} from './contract.ts'; + +const ENVIRONMENT_VARIABLE = /^[A-Z_][A-Z0-9_]*$/; /** The one validation of what a plugin factory returned, whichever source produced it. */ export function validateAgentDevicePlugin(value: unknown): AgentDevicePlugin { @@ -53,6 +54,15 @@ function assertCredentials(credentials: unknown): void { } } +function assertCredentialVariables(variables: unknown): void { + if ( + !Array.isArray(variables) || + !variables.every((name) => typeof name === 'string' && ENVIRONMENT_VARIABLE.test(name)) + ) { + throw invalidPlugin('Plugin credential variables must list environment variable names'); + } +} + function assertConnection(connection: unknown): void { if ( !isRecord(connection) || @@ -65,6 +75,31 @@ function assertConnection(connection: unknown): void { assertLocalConnectionCapabilities(connection.capabilities as ConnectionProviderCapabilities); } +function assertLocalConnectionCapabilities( + policy: ConnectionProviderCapabilities | undefined, +): void { + if (policy === undefined) return; + if ( + !policy || + typeof policy !== 'object' || + policy.leaseKind !== 'direct-device-provider' || + [ + 'requiresAppAttachment', + 'requiresRemoteDaemon', + 'supportsArtifacts', + 'supportsDeferredAppSelection', + 'supportsDirectPortReverse', + 'usesCloudWebDriverLease', + ].some((key) => typeof policy[key as keyof ConnectionProviderCapabilities] !== 'boolean') || + (policy.holdsCloudDevice !== undefined && typeof policy.holdsCloudDevice !== 'boolean') || + (policy.forgetsEndedConnectionLease !== undefined && + typeof policy.forgetsEndedConnectionLease !== 'boolean') || + policy.requiresRemoteDaemon + ) { + throw invalidPlugin('Plugin connection must declare local provider capabilities'); + } +} + /** The runtime a plugin built must answer to the provider id it registered. */ export function assertProviderRuntime( provider: string, diff --git a/packages/provider-revyl/package.json b/packages/provider-revyl/package.json index 8fbb597a4f..f00dc546ed 100644 --- a/packages/provider-revyl/package.json +++ b/packages/provider-revyl/package.json @@ -30,25 +30,6 @@ "@agent-device/test-kit": "workspace:*", "agent-device": "workspace:*" }, - "agentDevicePlugin": { - "apiVersion": 1, - "provider": "revyl", - "entry": "./dist/plugin.mjs", - "connection": { - "leaseKind": "direct-device-provider", - "requiresAppAttachment": false, - "requiresRemoteDaemon": false, - "supportsArtifacts": false, - "supportsDeferredAppSelection": false, - "supportsDirectPortReverse": false, - "usesCloudWebDriverLease": false, - "holdsCloudDevice": true - }, - "credentialVariables": [ - "REVYL_API_KEY", - "REVYL_API_URL" - ] - }, "publishConfig": { "exports": { ".": { diff --git a/packages/provider-revyl/src/plugin.ts b/packages/provider-revyl/src/plugin.ts deleted file mode 100644 index 71e65786f2..0000000000 --- a/packages/provider-revyl/src/plugin.ts +++ /dev/null @@ -1,21 +0,0 @@ -import type { ProviderPluginHost } from 'agent-device/plugins'; -import type { RevylConnection } from './connection.ts'; -import type { RevylRuntimeRegistration } from './runtime.ts'; - -/** What the version 1 host reads out of this entry: the runtime pair, plus the connect half. */ -export type RevylPluginEntryResult = RevylRuntimeRegistration & { - connection: RevylConnection; -}; - -/** - * The version 1 plugin entry, kept so hosts without the version 2 contract still load this package. - * The runtime is built by the same setup the version 2 declaration runs. - */ -export default async function revylPlugin( - host: ProviderPluginHost, -): Promise { - const { setupRevylPlugin } = await import('./plugin-setup.ts'); - const { createRevylConnection } = await import('./connection.ts'); - const registration = await setupRevylPlugin(host); - return { ...registration, connection: createRevylConnection(host) }; -} diff --git a/packages/provider-revyl/tsdown.config.ts b/packages/provider-revyl/tsdown.config.ts index 6173fbf90a..b0e02a7587 100644 --- a/packages/provider-revyl/tsdown.config.ts +++ b/packages/provider-revyl/tsdown.config.ts @@ -1,7 +1,7 @@ import { defineConfig } from 'tsdown'; export default defineConfig({ - entry: { plugin: 'src/plugin.ts', 'agent-device': 'src/index.ts' }, + entry: { 'agent-device': 'src/index.ts' }, outDir: 'dist', format: 'esm', platform: 'node', diff --git a/packages/provider-testmu/package.json b/packages/provider-testmu/package.json index fba7b447fe..d2e80e65c5 100644 --- a/packages/provider-testmu/package.json +++ b/packages/provider-testmu/package.json @@ -31,24 +31,6 @@ "@agent-device/provider-webdriver": "workspace:*", "agent-device": "workspace:*" }, - "agentDevicePlugin": { - "apiVersion": 1, - "provider": "testmu", - "entry": "./dist/plugin.mjs", - "connection": { - "leaseKind": "direct-device-provider", - "requiresAppAttachment": false, - "requiresRemoteDaemon": false, - "supportsArtifacts": true, - "supportsDeferredAppSelection": false, - "supportsDirectPortReverse": false, - "usesCloudWebDriverLease": true - }, - "credentialVariables": [ - "LT_USERNAME", - "LT_ACCESS_KEY" - ] - }, "publishConfig": { "exports": { ".": { diff --git a/packages/provider-testmu/src/index.test.ts b/packages/provider-testmu/src/index.test.ts index 924457b2fd..005a4182fb 100644 --- a/packages/provider-testmu/src/index.test.ts +++ b/packages/provider-testmu/src/index.test.ts @@ -4,7 +4,6 @@ import type { ProviderPluginHost } from 'agent-device/plugins'; import { AppError } from '@agent-device/kernel/errors'; import testmu from './index.ts'; import { verifyTestMuConnection } from './testmu-connection-verification.ts'; -import manifest from '../package.json' with { type: 'json' }; vi.mock('./testmu-connection-verification.ts', () => ({ verifyTestMuConnection: vi.fn() })); @@ -119,12 +118,20 @@ test('connect uses the option credentials without an environment and verifies wi ); }); -test('the v2 declaration matches the v1 manifest that hosts without the v2 contract read', () => { - const v1 = manifest.agentDevicePlugin; - assert.equal(testmu().provider, v1.provider); - assert.deepEqual(testmu().connection?.capabilities, v1.connection); - assert.deepEqual(testmu().credentials.variables, v1.credentialVariables); - assert.equal(v1.apiVersion, 1); +test('the plugin declares its provider, capabilities and credential variables', () => { + const plugin = testmu(); + assert.equal(plugin.apiVersion, 2); + assert.equal(plugin.provider, 'testmu'); + assert.deepEqual(plugin.credentials, { variables: ['LT_USERNAME', 'LT_ACCESS_KEY'] }); + assert.deepEqual(plugin.connection?.capabilities, { + leaseKind: 'direct-device-provider', + requiresAppAttachment: false, + requiresRemoteDaemon: false, + supportsArtifacts: true, + supportsDeferredAppSelection: false, + supportsDirectPortReverse: false, + usesCloudWebDriverLease: true, + }); }); test('a credentials object missing one key falls back to the environment for that key', async () => { diff --git a/packages/provider-testmu/src/plugin.test.ts b/packages/provider-testmu/src/plugin.test.ts deleted file mode 100644 index 29621ae951..0000000000 --- a/packages/provider-testmu/src/plugin.test.ts +++ /dev/null @@ -1,68 +0,0 @@ -import assert from 'node:assert/strict'; -import { afterEach, test, vi } from 'vitest'; -import type { ProviderPluginHost } from 'agent-device/plugins'; -import { AppError } from '@agent-device/kernel/errors'; -import testMuPlugin from './plugin.ts'; -import { verifyTestMuConnection } from './testmu-connection-verification.ts'; - -vi.mock('./testmu-connection-verification.ts', () => ({ verifyTestMuConnection: vi.fn() })); - -const realFetch = globalThis.fetch; - -afterEach(() => { - globalThis.fetch = realFetch; - vi.clearAllMocks(); -}); - -function host(env: Record): ProviderPluginHost { - return { - env, - options: {}, - clientVersion: '0.0.0-test', - createError: (code, message, details) => new AppError(code, message, details), - }; -} - -test('whitespace-only credentials are missing, not a provider authentication failure', async () => { - globalThis.fetch = async () => { - throw new Error('a missing credential must not reach TestMu AI'); - }; - for (const env of [ - { LT_USERNAME: ' ', LT_ACCESS_KEY: 'key' }, - { LT_USERNAME: 'user', LT_ACCESS_KEY: '\t' }, - ]) { - await assert.rejects( - testMuPlugin(host(env)).webDriver.listArtifacts!({ - provider: 'testmu', - providerSessionId: 'SESSION1', - }), - (error: unknown) => - error instanceof AppError && - error.code === 'INVALID_ARGS' && - /requires LT_(USERNAME|ACCESS_KEY) in the environment/.test(error.message), - ); - } -}); - -test('verification of a hand-authored profile canonicalizes an upper-case app scheme', async () => { - vi.mocked(verifyTestMuConnection).mockResolvedValue({ - provider: 'testmu', - service: 'TestMu AI', - verificationMessage: 'verified', - device: { status: 'verified', name: 'iPhone 16', platform: 'ios', osVersion: '18.0' }, - app: { status: 'verified', reference: 'lt://APP1' }, - }); - const env = { LT_USERNAME: 'user', LT_ACCESS_KEY: 'key' }; - await testMuPlugin(host(env)).connection.verify({ - flags: { - json: false, - help: false, - version: false, - platform: 'ios', - device: 'iPhone 16', - providerOsVersion: '18.0', - providerApp: 'LT://APP1', - }, - }); - assert.equal(vi.mocked(verifyTestMuConnection).mock.calls[0]?.[0].app, 'lt://APP1'); -}); diff --git a/packages/provider-testmu/src/plugin.ts b/packages/provider-testmu/src/plugin.ts deleted file mode 100644 index 6303af5632..0000000000 --- a/packages/provider-testmu/src/plugin.ts +++ /dev/null @@ -1,8 +0,0 @@ -import type { ProviderPluginHost } from 'agent-device/plugins'; -import { createTestMuConnection } from './connection.ts'; -import { createTestMuWebDriver } from './testmu-webdriver.ts'; - -/** The version 1 plugin entry, kept so hosts without the version 2 contract still load this package. */ -export default function testMuPlugin(host: ProviderPluginHost) { - return { webDriver: createTestMuWebDriver(host), connection: createTestMuConnection(host) }; -} diff --git a/packages/provider-testmu/tsdown.config.ts b/packages/provider-testmu/tsdown.config.ts index 6173fbf90a..b0e02a7587 100644 --- a/packages/provider-testmu/tsdown.config.ts +++ b/packages/provider-testmu/tsdown.config.ts @@ -1,7 +1,7 @@ import { defineConfig } from 'tsdown'; export default defineConfig({ - entry: { plugin: 'src/plugin.ts', 'agent-device': 'src/index.ts' }, + entry: { 'agent-device': 'src/index.ts' }, outDir: 'dist', format: 'esm', platform: 'node', diff --git a/packages/provider-webdriver/src/providers.ts b/packages/provider-webdriver/src/providers.ts index dd0e6c5a46..7768dd8e3a 100644 --- a/packages/provider-webdriver/src/providers.ts +++ b/packages/provider-webdriver/src/providers.ts @@ -16,8 +16,8 @@ export const BROWSERSTACK_CREDENTIAL_VARIABLES = { /** * What a bundled provider declares before any of its code runs: the same fields an installed - * plugin publishes under `agentDevicePlugin` in its manifest. Connect policy and the credential - * fingerprint read this, never the provider implementation. + * plugin returns from its factory. Connect policy and the credential fingerprint read this, never + * the provider implementation. */ export type CloudWebDriverProviderDeclaration = Readonly<{ provider: CloudWebDriverKnownProviderName; diff --git a/packages/test-kit/src/index.ts b/packages/test-kit/src/index.ts index 5d74593d59..6a78bd476c 100644 --- a/packages/test-kit/src/index.ts +++ b/packages/test-kit/src/index.ts @@ -101,13 +101,9 @@ export { } from './loopback.ts'; export { pluginHome, - registrationSource, - selectPlugin, - selectPluginManifest, selectV2Plugin, v2RegistrationSource, webDriverPluginSource, - writePlugin, } from './plugin.fixtures.ts'; export { formatRef, diff --git a/packages/test-kit/src/plugin.fixtures.ts b/packages/test-kit/src/plugin.fixtures.ts index 7b65aa248b..d402e0b116 100644 --- a/packages/test-kit/src/plugin.fixtures.ts +++ b/packages/test-kit/src/plugin.fixtures.ts @@ -9,58 +9,44 @@ export function pluginHome() { return { home, env: { AGENT_DEVICE_HOME: home } }; } -export function writePlugin( - project: string, - name = '@example/provider', - apiVersion = 1, - provider = 'example', - source = 'throw new Error("evaluated");', +/** + * Installs a plugin package: no `agentDevicePlugin` manifest, an `./agent-device` export, options + * recorded. `exports` and `manifest` override the package.json fields, `files` adds extra files. + */ +export function selectV2Plugin( + home: string, + name: string, + source: string, + options: { + exports?: unknown; + manifest?: Record; + files?: Record; + selectionOptions?: unknown; + } = {}, ) { - const directory = path.join(project, 'node_modules', name); + const installation = crypto.randomUUID(); + const directory = path.join(home, 'plugins', installation, 'node_modules', name); fs.mkdirSync(directory, { recursive: true }); fs.writeFileSync( path.join(directory, 'package.json'), JSON.stringify({ name, - version: '1.2.3', + version: '2.0.0', type: 'module', - agentDevicePlugin: { apiVersion, provider, entry: './plugin.js' }, + exports: + 'exports' in options ? options.exports : { './agent-device': { import: './plugin.mjs' } }, + ...options.manifest, }), ); - fs.writeFileSync(path.join(directory, 'plugin.js'), source); + fs.writeFileSync(path.join(directory, 'plugin.mjs'), source); + for (const [file, contents] of Object.entries(options.files ?? {})) { + fs.mkdirSync(path.dirname(path.join(directory, file)), { recursive: true }); + fs.writeFileSync(path.join(directory, file), contents); + } + recordSelection(home, name, installation, options.selectionOptions); return directory; } -export function selectPlugin( - home: string, - name: string, - provider: string, - source: string, - apiVersion = 1, -) { - const installation = crypto.randomUUID(); - writePlugin(path.join(home, 'plugins', installation), name, apiVersion, provider, source); - recordSelection(home, name, installation); -} - -/** Installs `manifest` as-is, with an entry file that throws if evaluated. */ -export function selectPluginManifest( - home: string, - manifest: { - name: string; - version: string; - agentDevicePlugin: Record & { entry: string }; - }, -) { - const installation = crypto.randomUUID(); - const directory = path.join(home, 'plugins', installation, 'node_modules', manifest.name); - const entry = path.join(directory, manifest.agentDevicePlugin.entry); - fs.mkdirSync(path.dirname(entry), { recursive: true }); - fs.writeFileSync(path.join(directory, 'package.json'), JSON.stringify(manifest)); - fs.writeFileSync(entry, 'throw new Error("evaluated");'); - recordSelection(home, manifest.name, installation); -} - function recordSelection( home: string, name: string, @@ -74,19 +60,6 @@ function recordSelection( fs.writeFileSync(configPath, JSON.stringify(config)); } -export function registrationSource(provider: string, shutdownFile?: string) { - return `import fs from 'node:fs'; - export default host => ({ - runtime: { provider: ${JSON.stringify(provider)}, - ownsDevice: () => false, getInteractor: () => undefined, - deviceInventoryProvider: async () => [], leaseLifecycle: {}, - shutdown: async () => { ${shutdownFile ? `fs.writeFileSync(${JSON.stringify(shutdownFile)}, 'shutdown');` : ''} }, - options: host.options, env: host.env, createError: host.createError }, - platformModule: { owner: { kind: 'provider-runtime', provider: ${JSON.stringify(provider)}, instance: 'test' }, - loadRuntime: async () => { throw new Error('lazy'); } } - });`; -} - const CONSUMED_PROFILE_FIELDS: Record = { providerApp: 'consumed', providerOsVersion: 'consumed', @@ -112,31 +85,8 @@ const CONSUMED_PROFILE_FIELDS: Record = { awsInteractionMode: 'consumed', }; -/** A `{ webDriver }` factory with a total field declaration; `connection` is a JS expression. */ -export function webDriverPluginSource( - provider: string, - refused: readonly ProviderProfileField[] = [], - connection?: string, -) { - const fields = { - ...CONSUMED_PROFILE_FIELDS, - ...Object.fromEntries(refused.map((field) => [field, 'refused'])), - }; - const webDriver = { - provider, - endpoint: 'https://webdriver.test/wd/hub/', - platform: 'android', - deviceName: provider, - profileFields: { provider, label: provider, fields }, - requestPolicy: { retryAttempts: 0 }, - }; - return `export default (host) => ({ webDriver: ${JSON.stringify(webDriver)}${ - connection ? `, connection: ${connection}` : '' - } });`; -} - /** - * A v2 plugin factory module. `extra` is spliced into the returned plugin object, so a test can add + * A plugin factory module. `extra` is spliced into the returned plugin object, so a test can add * `connection` or override `credentials`; `shutdownFile` is written when the runtime shuts down. */ export function v2RegistrationSource( @@ -161,37 +111,25 @@ export function v2RegistrationSource( });`; } -/** Installs a v2 package: no `agentDevicePlugin` manifest, an `./agent-device` export, options recorded. */ -export function selectV2Plugin( - home: string, - name: string, - source: string, - options: { - exports?: unknown; - manifest?: Record; - files?: Record; - selectionOptions?: unknown; - } = {}, +/** A `{ webDriver }` factory with a total field declaration; `refused` fields the engine must refuse. */ +export function webDriverPluginSource( + provider: string, + refused: readonly ProviderProfileField[] = [], ) { - const installation = crypto.randomUUID(); - const directory = path.join(home, 'plugins', installation, 'node_modules', name); - fs.mkdirSync(directory, { recursive: true }); - fs.writeFileSync( - path.join(directory, 'package.json'), - JSON.stringify({ - name, - version: '2.0.0', - type: 'module', - exports: - 'exports' in options ? options.exports : { './agent-device': { import: './plugin.mjs' } }, - ...options.manifest, - }), - ); - fs.writeFileSync(path.join(directory, 'plugin.mjs'), source); - for (const [file, contents] of Object.entries(options.files ?? {})) { - fs.mkdirSync(path.dirname(path.join(directory, file)), { recursive: true }); - fs.writeFileSync(path.join(directory, file), contents); - } - recordSelection(home, name, installation, options.selectionOptions); - return directory; + const fields = { + ...CONSUMED_PROFILE_FIELDS, + ...Object.fromEntries(refused.map((field) => [field, 'refused'])), + }; + const webDriver = { + provider, + endpoint: 'https://webdriver.test/wd/hub/', + platform: 'android', + deviceName: provider, + profileFields: { provider, label: provider, fields }, + requestPolicy: { retryAttempts: 0 }, + }; + return `export default () => ({ + apiVersion: 2, provider: ${JSON.stringify(provider)}, credentials: { variables: [] }, + setup: async () => ({ webDriver: ${JSON.stringify(webDriver)} }), + });`; } diff --git a/scripts/release-workspace.mjs b/scripts/release-workspace.mjs index d526775a92..23659ead61 100644 --- a/scripts/release-workspace.mjs +++ b/scripts/release-workspace.mjs @@ -69,7 +69,11 @@ function checkPublishedDependencies(packed) { const unpublishableNames = new Set( packages.filter((pkg) => pkg.manifest.private === true).map((pkg) => pkg.manifest.name), ); - if (packed.agentDevicePlugin) unpublishableNames.add(rootPackage.manifest.name); + // A provider plugin exports its factory as `./agent-device` and imports only types from + // agent-device, so it must never carry the core as a runtime dependency. The root and `main` + // loading fallbacks stay a loader convenience; a published plugin package names `./agent-device`. + if (packed.exports && Object.hasOwn(packed.exports, './agent-device')) + unpublishableNames.add(rootPackage.manifest.name); for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies']) { checkDependencyField(field, packed[field] ?? {}, unpublishableNames); } diff --git a/src/__tests__/cloud-connect-testmu.test.ts b/src/__tests__/cloud-connect-testmu.test.ts index ddb3b18311..b3682dca87 100644 --- a/src/__tests__/cloud-connect-testmu.test.ts +++ b/src/__tests__/cloud-connect-testmu.test.ts @@ -15,7 +15,8 @@ import { resolveConnectProviderProfile } from '../cli/connection/connect-provide import { mkdtempForTestSync, pluginHome, - selectPlugin, + selectV2Plugin, + v2RegistrationSource, bindTestCommandHost, } from '@agent-device/test-kit'; import manifest from '@agent-device/testmu/package.json' with { type: 'json' }; @@ -50,20 +51,16 @@ const mockedVerifyWebDriverConnection = vi.mocked(verifyTestMuConnection); beforeEach(() => { const { home } = pluginHome(); - selectPlugin(home, manifest.name, 'testmu', 'export default () => {};'); - const { installation } = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')) - .plugins[manifest.name]; - const manifestPath = path.join( + // The store declares the plugin installed with TestMu's capabilities; the mocked loader above + // supplies the workspace factory those assertions exercise. + selectV2Plugin( home, - 'plugins', - installation, - 'node_modules', manifest.name, - 'package.json', + v2RegistrationSource('testmu', { + extra: `connection: { capabilities: ${JSON.stringify(testmu().connection?.capabilities)}, resolve() {}, verify() {} },`, + credentials: '{ variables: ["LT_USERNAME", "LT_ACCESS_KEY"] }', + }), ); - const declared = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - declared.agentDevicePlugin.connection = manifest.agentDevicePlugin.connection; - fs.writeFileSync(manifestPath, JSON.stringify(declared)); vi.stubEnv('AGENT_DEVICE_HOME', home); mockedVerifyWebDriverConnection.mockImplementation(async (options) => { assert.equal(options.provider, 'testmu'); diff --git a/src/__tests__/provider-device-runtimes.test.ts b/src/__tests__/provider-device-runtimes.test.ts index 0b15653879..17f980167b 100644 --- a/src/__tests__/provider-device-runtimes.test.ts +++ b/src/__tests__/provider-device-runtimes.test.ts @@ -3,16 +3,11 @@ import { test } from 'vitest'; import { createDaemonProviderRuntimeComposition } from '../provider-device-runtimes.ts'; import fs from 'node:fs'; import path from 'node:path'; -import { - pluginHome, - registrationSource, - selectPlugin, - selectV2Plugin, -} from '@agent-device/test-kit'; +import { pluginHome, selectV2Plugin, v2RegistrationSource } from '@agent-device/test-kit'; test('daemon composition registers installed provider runtimes and their lazy platform modules', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', registrationSource('example')); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const composition = await createDaemonProviderRuntimeComposition({ env: env, cwd: process.cwd(), @@ -28,7 +23,7 @@ test('daemon composition registers installed provider runtimes and their lazy pl test('built-in providers register ahead of the store and an unconfigured Limrun still claims its id', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', registrationSource('example')); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const composition = await createDaemonProviderRuntimeComposition({ env: env, cwd: process.cwd(), @@ -51,7 +46,7 @@ test('built-in providers register ahead of the store and an unconfigured Limrun test('daemon composition records Limrun as failed for a partial instance set and still loads every other provider', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', registrationSource('example')); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const composition = await createDaemonProviderRuntimeComposition({ env: { ...env, @@ -76,7 +71,7 @@ test('daemon composition records Limrun as failed for a partial instance set and test('a plugin claiming a built-in provider ID is recorded as failed and the built-in keeps the ID', async () => { for (const provider of ['limrun', 'browserstack', 'aws-device-farm']) { const { home, env } = pluginHome(); - selectPlugin(home, 'example', provider, 'throw new Error("must not evaluate");'); + selectV2Plugin(home, 'example', v2RegistrationSource(provider)); const composition = await createDaemonProviderRuntimeComposition({ env: env, cwd: process.cwd(), @@ -93,6 +88,21 @@ test('a plugin claiming a built-in provider ID is recorded as failed and the bui } }); +test('a plugin claiming a routing identity is refused before the registry settles claims', async () => { + for (const provider of ['cloud', 'proxy']) { + const { home, env } = pluginHome(); + selectV2Plugin(home, 'example', v2RegistrationSource(provider)); + const composition = await createDaemonProviderRuntimeComposition({ + env: env, + cwd: process.cwd(), + }); + const plugin = composition.inventory.find(({ package: name }) => name === 'example'); + assert.equal(plugin?.state, 'failed'); + assert.equal(plugin?.error?.reason, 'reserved_provider'); + await composition.shutdown(); + } +}); + test('Limrun stays unregistered when only the removed API key alias is configured', async () => { const { env } = pluginHome(); const { runtimes, platformModules, inventory, shutdown } = diff --git a/src/builtin-provider-ids.ts b/src/builtin-provider-ids.ts index b2e542a59e..a9d2d79827 100644 --- a/src/builtin-provider-ids.ts +++ b/src/builtin-provider-ids.ts @@ -1,5 +1,5 @@ import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; -import { ROUTING_PROVIDER_IDENTITIES } from '@agent-device/plugins/manifest'; +import { ROUTING_PROVIDER_IDENTITIES } from '@agent-device/plugins/contract'; import { CLOUD_WEBDRIVER_PROVIDER_DECLARATIONS } from '@agent-device/provider-webdriver/providers'; export const LIMRUN_ID = 'limrun'; diff --git a/src/cli/commands/__tests__/connection-revyl.test.ts b/src/cli/commands/__tests__/connection-revyl.test.ts index ba9a563eaf..45330a3d7a 100644 --- a/src/cli/commands/__tests__/connection-revyl.test.ts +++ b/src/cli/commands/__tests__/connection-revyl.test.ts @@ -4,7 +4,12 @@ import http from 'node:http'; import type { AddressInfo } from 'node:net'; import path from 'node:path'; import { afterEach, beforeEach, test, vi } from 'vitest'; -import { mkdtempForTestSync, pluginHome, selectPlugin } from '@agent-device/test-kit'; +import { + mkdtempForTestSync, + pluginHome, + selectV2Plugin, + v2RegistrationSource, +} from '@agent-device/test-kit'; import type { CliFlags } from '@agent-device/contracts/command'; import { AppError } from '@agent-device/kernel/errors'; import { readActiveConnectionState } from '@agent-device/remote/remote-connection-state'; @@ -15,9 +20,9 @@ import manifest from '@agent-device/revyl/package.json' with { type: 'json' }; import { resolveConnectProviderProfile } from '../../connection/connect-provider-adapters.ts'; import { connectWithGeneratedProviderProfile } from '../../../__tests__/test-utils/connect-command.ts'; -// Mirrors src/__tests__/cloud-connect-testmu.test.ts: the plugin store is told the Revyl plugin is -// installed and its connection callbacks are loaded from the workspace source, so the assertions read -// the HTTP the plugin really sends rather than a mock of it. +// Mirrors src/__tests__/cloud-connect-testmu.test.ts: the store declares the Revyl plugin installed +// and its connection callbacks are loaded from the workspace source, so the assertions read the HTTP +// the plugin really sends rather than a mock of it. const mockedWithPluginConnection = vi.hoisted(() => vi.fn()); vi.mock('@agent-device/plugins/load', () => ({ @@ -81,20 +86,16 @@ afterEach(async () => { beforeEach(() => { const { home } = pluginHome(); - selectPlugin(home, manifest.name, 'revyl', 'export default () => {};'); - const { installation } = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')) - .plugins[manifest.name]; - const manifestPath = path.join( + // The store declares the plugin installed with Revyl's capabilities; the mocked loader below + // supplies the workspace factory those assertions exercise. + selectV2Plugin( home, - 'plugins', - installation, - 'node_modules', manifest.name, - 'package.json', + v2RegistrationSource('revyl', { + extra: `connection: { capabilities: ${JSON.stringify(revyl().connection?.capabilities)}, resolve() {}, verify() {} },`, + credentials: '{ variables: ["REVYL_API_KEY"] }', + }), ); - const declared = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - declared.agentDevicePlugin.connection = manifest.agentDevicePlugin.connection; - fs.writeFileSync(manifestPath, JSON.stringify(declared)); vi.stubEnv('AGENT_DEVICE_HOME', home); vi.stubEnv('REVYL_API_KEY', 'rk_test'); vi.stubEnv('REVYL_API_URL', ''); diff --git a/src/cli/commands/__tests__/plugins.test.ts b/src/cli/commands/__tests__/plugins.test.ts index b6b8ac5db7..207589a32d 100644 --- a/src/cli/commands/__tests__/plugins.test.ts +++ b/src/cli/commands/__tests__/plugins.test.ts @@ -4,7 +4,12 @@ import path from 'node:path'; import { afterEach, test, vi } from 'vitest'; import { runCli } from '../../../cli.ts'; import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; -import { pluginHome, selectPlugin, beginStdoutCapture } from '@agent-device/test-kit'; +import { + pluginHome, + selectV2Plugin, + v2RegistrationSource, + beginStdoutCapture, +} from '@agent-device/test-kit'; import { parseArgs, parseRawArgs, usageForCommand } from '../../parser/args.ts'; vi.mock('../../../provider-device-runtimes.ts', () => { @@ -15,17 +20,20 @@ afterEach(() => { vi.restoreAllMocks(); }); -test('plugins list and remove route through the CLI and emits JSON without daemon access or plugin evaluation', async () => { +test('plugins list and remove route through the CLI and emits JSON without daemon access or setup', async () => { const { home } = pluginHome(); vi.stubEnv('AGENT_DEVICE_HOME', home); vi.stubEnv('AGENT_DEVICE_STATE_DIR', path.join(home, 'state')); vi.stubEnv('AGENT_DEVICE_NO_UPDATE_NOTIFIER', '1'); - const marker = path.join(home, 'evaluated'); - selectPlugin( + const marker = path.join(home, 'setup'); + selectV2Plugin( home, 'example', - 'example', - `import fs from 'node:fs'; fs.writeFileSync(${JSON.stringify(marker)}, 'yes');`, + `import fs from 'node:fs'; + export default () => ({ + apiVersion: 2, provider: 'example', credentials: { variables: [] }, + setup: async () => { fs.writeFileSync(${JSON.stringify(marker)}, 'yes'); throw new Error('must not set up'); }, + });`, ); const sendToDaemon = vi.fn(async () => { throw new Error('unexpected daemon access'); @@ -40,7 +48,7 @@ test('plugins list and remove route through the CLI and emits JSON without daemo const result = JSON.parse(stdout); assert.equal(result.success, true); assert.deepEqual(result.data.plugins, [ - { name: 'example', version: '1.2.3', provider: 'example', compatible: true }, + { name: 'example', version: '2.0.0', provider: 'example', compatible: true }, ]); assert.equal(sendToDaemon.mock.calls.length, 0); await runCli(['plugins', 'remove', 'example', '--json'], { sendToDaemon }); @@ -87,7 +95,7 @@ test('plugins list reports the running daemon inventory next to the store select plugins: [failed], }), ); - selectPlugin(home, 'example', 'example', 'export default () => {};'); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const stdoutCapture = beginStdoutCapture(); try { await runCli(['plugins', 'list', '--json'], { @@ -161,7 +169,7 @@ test('plugins list names a plugin the running daemon did not register', async () ], }), ); - selectPlugin(home, 'example', 'example', 'export default () => {};'); + selectV2Plugin(home, 'example', v2RegistrationSource('example')); const text = await listPluginsAsText(home, stateDir); assert.match(text, /example@.* \(example\)/); assert.match(text, /The running daemon did not register example: bad plugin/); diff --git a/src/cli/commands/plugins.ts b/src/cli/commands/plugins.ts index 284a0f840f..9b40e6d65a 100644 --- a/src/cli/commands/plugins.ts +++ b/src/cli/commands/plugins.ts @@ -23,12 +23,7 @@ export const pluginsCommand: ClientCommandHandler = async ({ positionals, flags ); } if (action !== 'list' && name) { - await changePlugin( - action as 'add' | 'update' | 'remove', - name, - process.env, - BUILTIN_PROVIDER_IDS, - ); + await changePlugin(action as 'add' | 'update' | 'remove', name, process.env); } const plugins = await listPlugins(process.env, BUILTIN_PROVIDER_IDS); const daemon = readDaemonStatus(resolveDaemonPaths(flags.stateDir)); diff --git a/src/cli/connection/provider-policy.test.ts b/src/cli/connection/provider-policy.test.ts index b708979f2d..eb2f0fc785 100644 --- a/src/cli/connection/provider-policy.test.ts +++ b/src/cli/connection/provider-policy.test.ts @@ -1,20 +1,17 @@ import assert from 'node:assert/strict'; -import fs from 'node:fs'; -import path from 'node:path'; import { expect, test } from 'vitest'; -import { pluginConnectionNames, primePluginConnections } from '@agent-device/plugins/connection'; +import { + pluginConnectionNames, + pluginLoadFailures, + primePluginConnections, +} from '@agent-device/plugins/connection'; import { connectionProviderCapabilities, connectProviderNamesForError, isConnectProviderName, primeProviderConnection, } from './provider-policy.ts'; -import { - pluginHome, - selectPlugin, - selectV2Plugin, - v2RegistrationSource, -} from '@agent-device/test-kit'; +import { pluginHome, selectV2Plugin, v2RegistrationSource } from '@agent-device/test-kit'; test('provider policy projects provider identity into semantic capabilities', () => { assert.deepEqual(connectionProviderCapabilities('limrun'), { @@ -35,32 +32,32 @@ test('provider policy projects provider identity into semantic capabilities', () assert.equal(connectionProviderCapabilities('proxy').leaseKind, 'proxy'); }); -test('plugin capabilities come from the same environment as the provider name check', () => { +test('a manifest connection on a store package supplies no capabilities', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', 'export default () => {};'); - const { installation } = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')) - .plugins.example; - const manifestPath = path.join( - home, - 'plugins', - installation, - 'node_modules/example/package.json', - ); - const declared = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - const connection = { - leaseKind: 'direct-device-provider', - requiresAppAttachment: true, - requiresRemoteDaemon: false, - supportsArtifacts: true, - supportsDeferredAppSelection: false, - supportsDirectPortReverse: false, - usesCloudWebDriverLease: true, - } as const; - declared.agentDevicePlugin.connection = connection; - fs.writeFileSync(manifestPath, JSON.stringify(declared)); + selectV2Plugin(home, 'example', v2RegistrationSource('example'), { + manifest: { + agentDevicePlugin: { + apiVersion: 1, + provider: 'example', + entry: './plugin.mjs', + connection: { + leaseKind: 'direct-device-provider', + requiresAppAttachment: true, + requiresRemoteDaemon: false, + supportsArtifacts: true, + supportsDeferredAppSelection: false, + supportsDirectPortReverse: false, + usesCloudWebDriverLease: true, + }, + }, + }, + }); - assert.equal(isConnectProviderName('example', env), true); - assert.deepEqual(connectionProviderCapabilities('example', env), connection); + assert.equal(isConnectProviderName('example', env), false); + await primeProviderConnection('example', env); + // The factory declares no connection, so the manifest never fills the gap. + assert.equal(isConnectProviderName('example', env), false); + assert.deepEqual(pluginConnectionNames(env), []); }); test('a v2 plugin declares its capabilities in code, so they are read once the store is primed', async () => { @@ -97,25 +94,13 @@ test('a store plugin that fails to load is named where an unknown connect provid ); }); -test('once the store is primed a duplicate v1 manifest no longer supplies capabilities', async () => { +test('a plugin that fails to load supplies no connection name even after priming', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'dup', 'browserstack', 'export default () => {};'); - const { installation } = JSON.parse(fs.readFileSync(path.join(home, 'config.json'), 'utf8')) - .plugins.dup; - const manifestPath = path.join(home, 'plugins', installation, 'node_modules/dup/package.json'); - const declared = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); - declared.agentDevicePlugin.connection = { - leaseKind: 'direct-device-provider', - requiresAppAttachment: true, - requiresRemoteDaemon: false, - supportsArtifacts: true, - supportsDeferredAppSelection: false, - supportsDirectPortReverse: false, - usesCloudWebDriverLease: true, - }; - fs.writeFileSync(manifestPath, JSON.stringify(declared)); - - expect(pluginConnectionNames(env)).toEqual(['browserstack']); + selectV2Plugin(home, 'dup', v2RegistrationSource('browserstack')); await primePluginConnections(env, ['browserstack']); + // The built-in claimed the id first, so the store package registers nothing. expect(pluginConnectionNames(env)).toEqual([]); + expect(pluginLoadFailures(env).map(({ package: name, error }) => [name, error.reason])).toEqual([ + ['dup', 'duplicate_provider'], + ]); }); diff --git a/src/provider-credential-fingerprint.test.ts b/src/provider-credential-fingerprint.test.ts index 6ef316818d..1c0ffa6508 100644 --- a/src/provider-credential-fingerprint.test.ts +++ b/src/provider-credential-fingerprint.test.ts @@ -1,15 +1,19 @@ -import fs from 'node:fs'; -import path from 'node:path'; import { expect, test } from 'vitest'; import { providerCredentialFingerprint as fingerprintFor } from '@agent-device/plugins/credential-fingerprint'; import { readDaemonProviderCredentials as daemonCredentialsFor } from './provider-credential-fingerprint.ts'; +import type { PluginInventoryEntry } from '@agent-device/contracts/plugin-inventory'; import type { EnvMap } from '@agent-device/kernel/source-value'; import { builtinPluginInventory } from './__tests__/test-utils/builtin-plugin-inventory.ts'; -import { pluginHome, selectPluginManifest } from '@agent-device/test-kit'; +import { pluginHome, selectV2Plugin, v2RegistrationSource } from '@agent-device/test-kit'; +import { BUILTIN_PROVIDER_IDS } from './builtin-provider-ids.ts'; const inventory = await builtinPluginInventory(); -const providerCredentialFingerprint = (provider: string, env: EnvMap, leaseBackend?: string) => - fingerprintFor(provider, env, leaseBackend, inventory); +const providerCredentialFingerprint = ( + provider: string, + env: EnvMap, + leaseBackend?: string, + inventoryOverride?: readonly PluginInventoryEntry[], +) => fingerprintFor(provider, env, leaseBackend, inventoryOverride ?? inventory); const readDaemonProviderCredentials = (env: EnvMap, stateDir: string) => daemonCredentialsFor(env, stateDir, inventory); @@ -127,65 +131,100 @@ test('a Limrun lease fingerprint covers only the leased platform and the account ).toBe(ios(rotatedAndroid)); }); +/** The inventory the daemon publishes: the built-ins claim their ids, then the store loads. */ +async function storeInventory(env: Record) { + const { claimProviderIds, resolveProviderPlugins } = + await import('@agent-device/plugins/registry'); + const { storePluginCandidates } = await import('@agent-device/plugins/store'); + const resolved = await resolveProviderPlugins([ + ...claimProviderIds(BUILTIN_PROVIDER_IDS), + ...(await storePluginCandidates(env)), + ]); + return resolved.inventory(); +} + function pluginWithCredentialVariables(credentialVariables?: string[], provider = 'example') { const { home, env } = pluginHome(); - selectPluginManifest(home, { - name: '@example/provider', - version: '1.2.3', - agentDevicePlugin: { apiVersion: 1, provider, entry: './plugin.js', credentialVariables }, - }); - return env; + selectV2Plugin( + home, + '@example/provider', + v2RegistrationSource(provider, { + credentials: `{ variables: ${JSON.stringify(credentialVariables ?? [])} }`, + }), + ); + return { env: env as Record, home }; } -test('a plugin provider fingerprint hashes the variables its manifest declares', () => { - const home = pluginWithCredentialVariables(['EXAMPLE_USER', 'EXAMPLE_KEY']); +test('a plugin provider fingerprint hashes the variables its factory declares', async () => { + const { env: home } = pluginWithCredentialVariables(['EXAMPLE_USER', 'EXAMPLE_KEY']); + const inventory = await storeInventory(home); const env = { ...home, EXAMPLE_USER: 'user', EXAMPLE_KEY: 'key-1' }; - const fingerprint = providerCredentialFingerprint('example', env); + const fingerprint = providerCredentialFingerprint('example', env, undefined, inventory); expect(fingerprint).toMatch(/^v1:[0-9a-f]{16}$/); - expect(providerCredentialFingerprint('example', { ...env, UNRELATED: 'x' })).toBe(fingerprint); - expect(providerCredentialFingerprint('example', { ...env, EXAMPLE_KEY: 'key-2' })).not.toBe( - fingerprint, - ); - expect(providerCredentialFingerprint('example', { ...env, EXAMPLE_KEY: 'key-1 ' })).not.toBe( - fingerprint, - ); - expect(providerCredentialFingerprint('example', { ...home, EXAMPLE_USER: ' ' })).toBe(undefined); - expect(readDaemonProviderCredentials(env, '/state').fingerprint('example')).toBe(fingerprint); + expect( + providerCredentialFingerprint('example', { ...env, UNRELATED: 'x' }, undefined, inventory), + ).toBe(fingerprint); + expect( + providerCredentialFingerprint( + 'example', + { ...env, EXAMPLE_KEY: 'key-2' }, + undefined, + inventory, + ), + ).not.toBe(fingerprint); + expect( + providerCredentialFingerprint( + 'example', + { ...env, EXAMPLE_KEY: 'key-1 ' }, + undefined, + inventory, + ), + ).not.toBe(fingerprint); + expect( + providerCredentialFingerprint('example', { ...home, EXAMPLE_USER: ' ' }, undefined, inventory), + ).toBe(undefined); }); -test('a plugin provider without declared credential variables has no fingerprint', () => { - const env = { ...pluginWithCredentialVariables(), EXAMPLE_USER: 'user' }; - expect(providerCredentialFingerprint('example', env)).toBe(undefined); - expect(providerCredentialFingerprint('other', env)).toBe(undefined); +test('a plugin provider without declared credential variables has no fingerprint', async () => { + const { env: home } = pluginWithCredentialVariables(); + const inventory = await storeInventory(home); + const env = { ...home, EXAMPLE_USER: 'user' }; + expect(providerCredentialFingerprint('example', env, undefined, inventory)).toBe(undefined); + expect(providerCredentialFingerprint('other', env, undefined, inventory)).toBe(undefined); }); -test('a plugin declaration never adds a fingerprint to a bundled provider', () => { - const env = { - ...pluginWithCredentialVariables(['AWS_ACCESS_KEY_ID'], 'aws-device-farm'), - AWS_ACCESS_KEY_ID: 'id', - }; +test('a plugin declaration never adds a fingerprint to a bundled provider', async () => { + const { env: home } = pluginWithCredentialVariables(['AWS_ACCESS_KEY_ID'], 'aws-device-farm'); + const inventory = await storeInventory(home); + const env = { ...home, AWS_ACCESS_KEY_ID: 'id' }; + expect(providerCredentialFingerprint('aws-device-farm', env, undefined, inventory)).toBe( + undefined, + ); + // The built-in's own answer is unchanged by the store package that claims its id. expect(providerCredentialFingerprint('aws-device-farm', env)).toBe(undefined); }); -function testMuPluginEnv(): Record { - const manifest = path.resolve(import.meta.dirname, '../packages/provider-testmu/package.json'); +test('a store plugin declares per-backend credential variables in code', async () => { const { home, env } = pluginHome(); - selectPluginManifest(home, JSON.parse(fs.readFileSync(manifest, 'utf8'))); - return env; -} - -test('the bundled TestMu AI plugin manifest fingerprints its LT credentials', () => { - const home = testMuPluginEnv(); - const env = { ...home, LT_USERNAME: 'user', LT_ACCESS_KEY: 'key-1' }; - const fingerprint = providerCredentialFingerprint('testmu', env); - - expect(fingerprint).toMatch(/^v1:[0-9a-f]{16}$/); - expect(providerCredentialFingerprint('testmu', { ...env })).toBe(fingerprint); - expect(providerCredentialFingerprint('testmu', { ...env, LT_ACCESS_KEY: 'key-2' })).not.toBe( - fingerprint, + selectV2Plugin( + home, + '@example/backend', + v2RegistrationSource('example', { + credentials: + '{ variables: ["EXAMPLE_ACCOUNT"], byBackend: { "shared-session": ["EXAMPLE_POOL"] } }', + }), + ); + const inventory = await storeInventory(env as Record); + const envMap = { ...env, EXAMPLE_ACCOUNT: 'acct', EXAMPLE_POOL: 'pool-1' }; + const fingerprint = (values: Record, leaseBackend?: string) => + providerCredentialFingerprint('example', values, leaseBackend, inventory); + + // Without a backend the common variables answer; the pool belongs to one backend only. + expect(fingerprint(envMap)).toMatch(/^v1:[0-9a-f]{16}$/); + expect(fingerprint({ ...envMap, EXAMPLE_POOL: 'pool-2' })).toBe(fingerprint(envMap)); + expect(fingerprint({ ...envMap, EXAMPLE_POOL: 'pool-2' }, 'shared-session')).not.toBe( + fingerprint(envMap, 'shared-session'), ); - expect(providerCredentialFingerprint('testmu', home)).toBe(undefined); - expect(readDaemonProviderCredentials(env, '/state').fingerprint('testmu')).toBe(fingerprint); - expect(readDaemonProviderCredentials(home, '/state').fingerprint('testmu')).toBe(undefined); + expect(fingerprint({ EXAMPLE_ACCOUNT: 'acct' }, 'shared-session')).toBe(undefined); }); diff --git a/src/provider-plugin-policy.test.ts b/src/provider-plugin-policy.test.ts index 8e0c4f8776..7112f36bb2 100644 --- a/src/provider-plugin-policy.test.ts +++ b/src/provider-plugin-policy.test.ts @@ -8,7 +8,7 @@ import { startProviderRegistry, } from '@agent-device/plugins/registry'; import { storePluginCandidates } from '@agent-device/plugins/store'; -import { pluginHome, selectPlugin, webDriverPluginSource } from '@agent-device/test-kit'; +import { pluginHome, selectV2Plugin, webDriverPluginSource } from '@agent-device/test-kit'; import { PROVIDER_PLUGIN_POLICY } from './provider-plugin-policy.ts'; const realFetch = globalThis.fetch; @@ -39,7 +39,7 @@ afterEach(() => { test('a WebDriver plugin allocates through the shared engine under the process policy', async () => { const { home, env } = pluginHome(); - selectPlugin(home, 'example', 'example', webDriverPluginSource('example', ['awsProjectArn'])); + selectV2Plugin(home, 'example', webDriverPluginSource('example', ['awsProjectArn'])); const registry = await startStoreRegistry(env); const { runtime, platformModule } = registry.registrations[0]!; assert.equal(runtime.provider, 'example'); @@ -71,11 +71,13 @@ test('a WebDriver plugin allocates through the shared engine under the process p test('a WebDriver descriptor missing what the engine needs is listed as an invalid plugin', async () => { const { home, env } = pluginHome(); - selectPlugin( + selectV2Plugin( home, 'example', - 'example', - "export default () => ({ webDriver: { provider: 'example' } });", + `export default () => ({ + apiVersion: 2, provider: 'example', credentials: { variables: [] }, + setup: async () => ({ webDriver: { provider: 'example' } }), + });`, ); const registry = await startStoreRegistry(env); assert.deepEqual(registry.registrations, []); diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index d98f2cd4d1..72fa20b2e9 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -132,14 +132,31 @@ connection: { ### Package for installation -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. +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`. -## Version 1 plugins +## Migrating from a version 1 manifest -Packages that declare `agentDevicePlugin` with `apiVersion: 1` in `package.json` keep working. The host reads the manifest's `provider`, `entry`, `connection`, and `credentialVariables` before running any plugin code, then calls the default export with `ProviderPluginHost` and registers the `{ runtime, platformModule }` or `{ webDriver, connection? }` it returns. Support for this form ends in a later release; move to the `./agent-device` factory. +Earlier plugin packages declared `agentDevicePlugin` with `apiVersion: 1` in `package.json`, and the host read `provider`, `entry`, `connection`, and `credentialVariables` from it before loading any code. That form is no longer supported: a store package is loaded only through its exports, and everything it declares comes from the object its factory returns. -```json -{"agentDevicePlugin": {"apiVersion": 1, "provider": "example", "entry": "./dist/plugin.mjs"}} +To move a package: + +1. Export the factory from `./agent-device` instead of naming an entry file in the manifest, and drop `agentDevicePlugin` from `package.json`. +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`. +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. + +```diff +-{"agentDevicePlugin": {"apiVersion": 1, "provider": "example", "entry": "./dist/plugin.mjs"}} ++{"exports": {"./agent-device": { "import": "./dist/plugin.mjs" }}} +``` + +```diff +-export default async (host) => ({ runtime, platformModule }); ++export default () => ({ ++ apiVersion: 2, ++ provider: 'example', ++ credentials: { variables: ['EXAMPLE_API_KEY'] }, ++ setup: async (host) => ({ runtime, platformModule }), ++}); ``` -A package that exports `./agent-device` is loaded as a version 2 plugin even if it also keeps the manifest, so one package can serve both old and new hosts. +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.