diff --git a/.changeset/managed-plugin-artifact.md b/.changeset/managed-plugin-artifact.md new file mode 100644 index 0000000000..9e9f534f30 --- /dev/null +++ b/.changeset/managed-plugin-artifact.md @@ -0,0 +1,5 @@ +--- +'agent-device': minor +--- + +Install local plugin tarballs with `plugins add-artifact` or the plugin manager API. Artifact selections record their version and SHA-512 integrity. To replace one, run `plugins remove ` and then `plugins add-artifact `. Close active sessions and restart the daemon to apply the changed selection. diff --git a/packages/command-surface/src/schema/command-overrides.ts b/packages/command-surface/src/schema/command-overrides.ts index 691b1dd020..46ebdf954a 100644 --- a/packages/command-surface/src/schema/command-overrides.ts +++ b/packages/command-surface/src/schema/command-overrides.ts @@ -15,13 +15,13 @@ const SCHEMA_ONLY_CLI_COMMAND_SCHEMAS = { text: { summary: 'Manage installed provider plugins', description: - 'Install, list, update, or remove npm provider plugins in AGENT_DEVICE_HOME (default ~/.agent-device). Changes take effect after restarting the local daemon. list works offline and, when a daemon is running for --state-dir, also reports the providers it registered. Use --json for structured results.', + 'Install, list, update, or remove provider plugins in AGENT_DEVICE_HOME (default ~/.agent-device). Changes take effect after restarting the local daemon. list works offline and, when a daemon is running for --state-dir, also reports the providers it registered. Use --json for structured results.', }, usageOverride: - 'plugins list [--state-dir ]|add |update |remove ', + 'plugins list [--state-dir ]|add |add-artifact |update |remove ', listUsageOverride: 'plugins', - positionalArgs: ['list|add|update|remove', 'package?'], - flagsByAction: { list: ['stateDir'], add: [], update: [], remove: [] }, + positionalArgs: ['list|add|add-artifact|update|remove', 'package-or-path?'], + flagsByAction: { list: ['stateDir'], add: [], 'add-artifact': [], update: [], remove: [] }, supportedFlags: ['stateDir'], }, cdp: { diff --git a/packages/plugins/src/store-artifact.test.ts b/packages/plugins/src/store-artifact.test.ts new file mode 100644 index 0000000000..209ecd9ec7 --- /dev/null +++ b/packages/plugins/src/store-artifact.test.ts @@ -0,0 +1,263 @@ +import assert from 'node:assert/strict'; +import crypto from 'node:crypto'; +import fs from 'node:fs'; +import path from 'node:path'; +import { test, vi } from 'vitest'; +import * as command from '@agent-device/host-kit/command'; +import { mkdtempForTestSync, pluginHome, v2RegistrationSource } from '@agent-device/test-kit'; +import { + addPluginArtifact, + changePlugin, + createPluginSelectionGuard, + listPlugins, + storePluginCandidates, +} from './store.ts'; + +function packFixture( + root: string, + name: string, + exportsField: unknown = { './agent-device': './plugin.mjs' }, + factoryGate?: string, +) { + const source = path.join(root, name); + fs.mkdirSync(source, { recursive: true }); + const sentinel = path.join(root, `${name}-executed`); + fs.writeFileSync( + path.join(source, 'package.json'), + JSON.stringify({ + name, + version: '1.2.3', + type: 'module', + exports: exportsField, + scripts: { + preinstall: `node sentinel.cjs`, + install: `node sentinel.cjs`, + postinstall: `node sentinel.cjs`, + }, + }), + ); + fs.writeFileSync( + path.join(source, 'sentinel.cjs'), + `require('node:fs').writeFileSync(${JSON.stringify(sentinel)}, 'script')`, + ); + let pluginSource = v2RegistrationSource(name).replace( + 'export default (options = {}) => (', + `export default (options = {}) => (fs.writeFileSync(${JSON.stringify(sentinel)}, 'factory'), `, + ); + if (factoryGate) { + pluginSource = pluginSource.replace('export default ', 'const createPlugin = '); + pluginSource += `\nexport default async (options) => { + const gate = globalThis[Symbol.for(${JSON.stringify(factoryGate)})]; + gate.enter(); + await gate.resume; + return createPlugin(options); + };`; + } + fs.writeFileSync(path.join(source, 'plugin.mjs'), pluginSource); + const packed = command.runCmdSync( + 'npm', + ['pack', '--ignore-scripts', '--json', '--pack-destination', root], + { cwd: source }, + ); + assert.equal(packed.exitCode, 0, packed.stderr); + return { archive: path.join(root, JSON.parse(packed.stdout)[0].filename), sentinel }; +} + +test('artifact installation preserves immutable identity, isolation, collision and stale guard', async () => { + const root = mkdtempForTestSync('plugin-artifact-'); + const fixture = packFixture(root, 'fixture-provider'); + const { home, env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + const other = pluginHome(); + const expected = `sha512-${crypto.createHash('sha512').update(fs.readFileSync(fixture.archive)).digest('base64')}`; + const result = await addPluginArtifact(path.basename(fixture.archive), { cwd: root, env }); + assert.equal(result.integrity, expected); + assert.equal(result.name, 'fixture-provider'); + assert.equal(result.version, '1.2.3'); + assert.equal(fs.existsSync(fixture.sentinel), false); + assert.ok(fs.existsSync(fixture.archive)); + assert.deepEqual(await listPlugins(other.env, []), []); + const guard = createPluginSelectionGuard(await storePluginCandidates(env), env); + const configPath = path.join(home, 'config.json'); + const before = fs.readFileSync(configPath, 'utf8'); + await assert.rejects(addPluginArtifact(fixture.archive, { cwd: root, env }), { + code: 'INVALID_ARGS', + }); + await assert.rejects(changePlugin('update', result.name, env), { code: 'INVALID_ARGS' }); + await assert.rejects(changePlugin('add', result.name, env), { code: 'INVALID_ARGS' }); + assert.equal(fs.readFileSync(configPath, 'utf8'), before); + assert.equal(fs.readdirSync(path.join(home, 'plugins')).length, 1); + const [listed] = await listPlugins(env, []); + assert.equal(listed?.version, '1.2.3'); + assert.equal(listed?.integrity, expected); + assert.equal(listed?.installation, result.installation); + assert.equal(fs.readFileSync(fixture.sentinel, 'utf8'), 'factory'); + const config = JSON.parse(before); + config.plugins[result.name].artifact.integrity = + `sha512-${Buffer.alloc(64, 1).toString('base64')}`; + fs.writeFileSync(configPath, JSON.stringify(config)); + assert.throws( + () => guard(result.name), + (error: unknown) => + (error as { details?: { reason?: string } }).details?.reason === 'daemon-plugin-set-stale', + ); +}); + +test('invalid artifact and missing export roll back without disturbing selections', async () => { + const root = mkdtempForTestSync('plugin-artifact-invalid-'); + const { home, env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + const valid = packFixture(root, 'fixture-valid'); + await addPluginArtifact(valid.archive, { cwd: root, env }); + const before = fs.readFileSync(path.join(home, 'config.json'), 'utf8'); + const missing = packFixture(root, 'fixture-missing', { '.': './plugin.mjs' }); + await assert.rejects(addPluginArtifact(missing.archive, { cwd: root, env })); + const bad = path.join(root, 'bad.tgz'); + fs.writeFileSync(bad, 'not an archive'); + await assert.rejects(addPluginArtifact(bad, { cwd: root, env })); + assert.equal(fs.readFileSync(path.join(home, 'config.json'), 'utf8'), before); + assert.equal(fs.readdirSync(path.join(home, 'plugins')).length, 1); + assert.equal(fs.existsSync(missing.sentinel), false); +}); + +test('concurrent artifact additions preserve both selections', async () => { + const root = mkdtempForTestSync('plugin-artifact-concurrent-'); + const one = packFixture(root, 'fixture-one'); + const two = packFixture(root, 'fixture-two'); + const { env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + await Promise.all( + [one, two].map(({ archive }) => addPluginArtifact(archive, { cwd: root, env })), + ); + assert.deepEqual( + (await listPlugins(env, [])).map((plugin) => plugin.name), + ['fixture-one', 'fixture-two'], + ); + assert.equal(fs.existsSync(one.sentinel), true); +}); + +test('npm staging rejects an escaping symlink entry and leaves external files untouched', async () => { + const { default: tar } = await import('tar-stream'); + const { gzipSync } = await import('node:zlib'); + const root = mkdtempForTestSync('plugin-artifact-symlink-'); + const outside = path.join(root, 'outside.mjs'); + fs.writeFileSync(outside, 'outside'); + const archive = path.join(root, 'malicious.tgz'); + const stream = tar.pack(); + const chunks: Buffer[] = []; + stream.on('data', (chunk: Buffer) => chunks.push(chunk)); + stream.entry( + { name: 'package/package.json' }, + JSON.stringify({ + name: 'fixture-escape', + version: '1.0.0', + exports: { './agent-device': './plugin.mjs' }, + }), + ); + stream.entry({ name: 'package/plugin.mjs', type: 'symlink', linkname: outside }); + stream.entry({ name: 'package/../../escape' }, 'escaped'); + const finished = new Promise((resolve, reject) => { + stream.on('end', resolve); + stream.on('error', reject); + }); + stream.finalize(); + await finished; + fs.writeFileSync(archive, gzipSync(Buffer.concat(chunks))); + const { home, env: isolated } = pluginHome(); + await assert.rejects( + addPluginArtifact(archive, { cwd: root, env: { ...process.env, ...isolated } }), + ); + assert.equal(fs.readFileSync(outside, 'utf8'), 'outside'); + assert.equal(fs.existsSync(path.join(home, 'escape')), false); + assert.equal(fs.existsSync(path.join(home, 'config.json')), false); +}); + +test('artifact installation rejects replacement bytes consumed by npm', async () => { + const root = mkdtempForTestSync('plugin-artifact-replaced-'); + const originalRoot = path.join(root, 'original'); + const replacementRoot = path.join(root, 'replacement'); + const original = packFixture(originalRoot, 'fixture-replaced'); + const replacement = packFixture(replacementRoot, 'fixture-replaced'); + assert.notDeepEqual(fs.readFileSync(original.archive), fs.readFileSync(replacement.archive)); + const { home, env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + const runCmd = command.runCmd; + let replaced = false; + const spy = vi.spyOn(command, 'runCmd').mockImplementation(async (program, args, options) => { + if (program === 'npm' && args[0] === 'install' && args.at(-2) === '--') { + fs.copyFileSync(replacement.archive, args.at(-1)!); + replaced = true; + } + return runCmd(program, args, options); + }); + try { + await assert.rejects(addPluginArtifact(original.archive, { cwd: root, env }), { + code: 'INVALID_ARGS', + details: { reason: 'artifact_integrity_mismatch' }, + }); + assert.equal(replaced, true); + assert.equal(fs.existsSync(path.join(home, 'config.json')), false); + assert.deepEqual(fs.readdirSync(path.join(home, 'plugins')), []); + assert.equal(fs.existsSync(replacement.sentinel), false); + } finally { + spy.mockRestore(); + } +}); + +test('inventory retains one selection snapshot while a factory awaits', async () => { + const root = mkdtempForTestSync('plugin-artifact-inventory-'); + const key = `agent-device.artifact-inventory.${crypto.randomUUID()}`; + const first = packFixture(path.join(root, 'first'), 'fixture-inventory', undefined, key); + const second = packFixture(path.join(root, 'second'), 'fixture-inventory'); + const { env: isolated } = pluginHome(); + const env = { ...process.env, ...isolated }; + const original = await addPluginArtifact(first.archive, { cwd: root, env }); + let enter!: () => void; + let continueListing!: () => void; + const entered = new Promise((resolve) => { + enter = resolve; + }); + const resume = new Promise((resolve) => { + continueListing = resolve; + }); + const gates = globalThis as typeof globalThis & Record; + gates[Symbol.for(key)] = { enter, resume }; + const listing = listPlugins(env, []); + try { + await entered; + await changePlugin('remove', original.name, env); + const replacement = await addPluginArtifact(second.archive, { cwd: root, env }); + assert.notEqual(replacement.integrity, original.integrity); + continueListing(); + const [entry] = await listing; + assert.deepEqual(entry, { + name: original.name, + installation: original.installation, + integrity: original.integrity, + version: original.version, + provider: 'fixture-inventory', + compatible: true, + }); + const [current] = await listPlugins(env, []); + assert.equal(current?.installation, replacement.installation); + assert.equal(current?.integrity, replacement.integrity); + } finally { + continueListing(); + await listing; + delete gates[Symbol.for(key)]; + } +}); + +test.each([undefined, '~/plugin-store'])( + 'missing HOME does not preempt archive validation (%s)', + async (override) => { + const root = mkdtempForTestSync('plugin-artifact-home-'); + await assert.rejects( + addPluginArtifact(path.join(root, 'missing.tgz'), { + cwd: root, + env: { HOME: undefined, AGENT_DEVICE_HOME: override }, + }), + { code: 'ENOENT' }, + ); + }, +); diff --git a/packages/plugins/src/store.test.ts b/packages/plugins/src/store.test.ts index 756ac1ee30..ee9c13568b 100644 --- a/packages/plugins/src/store.test.ts +++ b/packages/plugins/src/store.test.ts @@ -317,3 +317,26 @@ test('equivalent nested option key order keeps the daemon selection current', as }, ); }); + +test.each([ + ['1.2.3-01', false], + ['1.2.3-rc.01', false], + ['1.2.3-00', false], + ['1.2.3-0', true], + ['1.2.3-01a', true], + ['1.2.3-1a.0+001', true], + ['1.2.3+01', true], +] as const)('artifact selection validates exact SemVer %s', async (version, valid) => { + const { home, env } = pluginHome(); + selectV2Plugin(home, 'example', v2RegistrationSource('example'), { manifest: { version } }); + const config = readPluginConfig(env); + config.plugins.example.artifact = { + version, + integrity: `sha512-${Buffer.alloc(64).toString('base64')}`, + }; + fs.writeFileSync(path.join(home, 'config.json'), JSON.stringify(config)); + const [entry] = await listPlugins(env, []); + assert.equal(entry?.compatible, valid); + if (valid) assert.equal(entry?.version, version); + assert.equal(vi.mocked(runCmd).mock.calls.length, 0); +}); diff --git a/packages/plugins/src/store.ts b/packages/plugins/src/store.ts index 635e1a8bea..80556c8a73 100644 --- a/packages/plugins/src/store.ts +++ b/packages/plugins/src/store.ts @@ -18,6 +18,7 @@ export type PluginSelection = { installation: string; version?: string; options?: Record; + artifact?: { integrity: string; version: string }; }; type PluginConfig = Record & { plugins?: Record }; @@ -43,7 +44,12 @@ function validatePluginSelection(name: string, selection: PluginSelection): void typeof selection.installation !== 'string' || !/^[a-f0-9-]{36}$/.test(selection.installation) || (selection.version !== undefined && !isVersionSelector(selection.version)) || - (selection.options !== undefined && !isRecord(selection.options)) + (selection.options !== undefined && !isRecord(selection.options)) || + (selection.artifact !== undefined && + (!isRecord(selection.artifact) || + typeof selection.artifact.integrity !== 'string' || + !/^sha512-[A-Za-z0-9+/]{86}==$/.test(selection.artifact.integrity) || + !isExactVersion(selection.artifact.version))) ) { throw new AppError('INVALID_ARGS', `Invalid plugin selection: ${name}`); } @@ -110,6 +116,16 @@ function isVersionSelector(value: unknown): value is string { ); } +function isExactVersion(value: unknown): value is string { + if (typeof value !== 'string') return false; + const match = + /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec( + value, + ); + if (!match) return false; + return match[4]?.split('.').every((identifier) => !/^0\d+$/.test(identifier)) ?? true; +} + type StoreInstallation = { name: string; version: string; @@ -133,6 +149,15 @@ async function describeInstallation( reason: 'invalid_plugin', }); } + if ( + selection.artifact && + (version !== selection.artifact.version || + !isRecord(packageJson.exports) || + !Object.hasOwn(packageJson.exports, './agent-device')) + ) + throw new AppError('INVALID_ARGS', `Invalid artifact plugin metadata: ${name}`, { + reason: 'invalid_plugin', + }); return { name, version, directory, selection, entry: discoverPluginEntry(directory) }; } @@ -161,15 +186,22 @@ async function loadInstallation({ name, entry, selection }: StoreInstallation) { * only once its factory runs, and the registry settles a duplicate then. */ export async function storePluginCandidates(env: NodeJS.ProcessEnv): Promise { + return (await readPluginSnapshot(env)).candidates; +} + +async function readPluginSnapshot(env: NodeJS.ProcessEnv): Promise<{ + candidates: PluginCandidate[]; + selections: Record; +}> { const home = storeHome(env); let selections: [string, PluginSelection][]; try { selections = Object.entries(readPluginConfig(env).plugins ?? {}); } catch (error) { - return [{ source: 'store', load: () => Promise.reject(error) }]; + return { candidates: [{ source: 'store', load: () => Promise.reject(error) }], selections: {} }; } const ordered = selections.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)); - return await Promise.all( + const candidates = await Promise.all( ordered.map(async ([name, selection]): Promise => { try { const installation = await readInstallation(home, name, selection); @@ -192,6 +224,7 @@ export async function storePluginCandidates(env: NodeJS.ProcessEnv): Promise ({ name: entry.package, + ...(entry.package && selections[entry.package]?.artifact + ? { + installation: selections[entry.package]!.installation, + integrity: selections[entry.package]!.artifact!.integrity, + } + : {}), ...(entry.version !== undefined ? { version: entry.version } : {}), ...(entry.provider !== undefined ? { provider: entry.provider } : {}), ...(entry.backend !== undefined ? { backend: entry.backend } : {}), @@ -245,6 +285,25 @@ function parsePluginRequest(action: PluginAction, input: string) { return { name: match[1], version: match[2] }; } +async function installInProject(project: string, env: NodeJS.ProcessEnv, artifact?: string) { + await runCmd( + 'npm', + [ + 'install', + '--ignore-scripts', + '--no-audit', + '--no-fund', + '--global=false', + '--prefix', + project, + '--workspaces=false', + '--package-lock=true', + ...(artifact ? ['--', artifact] : []), + ], + { cwd: project, env, timeoutMs: 120_000 }, + ); +} + async function stagePlugin( home: string, name: string, @@ -259,21 +318,7 @@ async function stagePlugin( path.join(project, 'package.json'), JSON.stringify({ private: true, dependencies: { [name]: version ?? 'latest' } }), ); - await runCmd( - 'npm', - [ - 'install', - '--ignore-scripts', - '--no-audit', - '--no-fund', - '--global=false', - '--prefix', - project, - '--workspaces=false', - '--package-lock=true', - ], - { cwd: project, env, timeoutMs: 120_000 }, - ); + await installInProject(project, env); const staged = await describeInstallation( name, installationDirectory(home, name, installation), @@ -315,6 +360,12 @@ export async function changePlugin( const previous = Object.hasOwn(selections, name) ? selections[name] : undefined; if (action !== 'add' && !Object.hasOwn(selections, name)) throw new AppError('INVALID_ARGS', `Plugin is not installed: ${name}`); + if (action !== 'remove' && previous?.artifact) + throw new AppError( + 'INVALID_ARGS', + `Artifact plugin cannot be updated from the registry: ${name}`, + { reason: 'artifact_update_requires_remove' }, + ); if (action === 'remove') delete selections[name]; else { const requested = @@ -338,3 +389,84 @@ export async function changePlugin( await release(); } } + +/** Install immutable local package bytes through the managed store. */ +export async function addPluginArtifact( + input: string, + host: { env: Record; cwd: string }, +): Promise<{ name: string; version: string; installation: string; integrity: string }> { + if (!input.endsWith('.tgz') || !path.isAbsolute(host.cwd)) + throw new AppError('INVALID_ARGS', 'Expected a local .tgz path and an absolute host cwd'); + const bytes = fs.readFileSync(path.resolve(host.cwd, input)); + const integrity = `sha512-${crypto.createHash('sha512').update(bytes).digest('base64')}`; + const configPath = resolveUserConfigPath(host.env); + fs.mkdirSync(path.dirname(configPath), { recursive: true, mode: 0o700 }); + const home = fs.realpathSync(path.dirname(configPath)); + const release = await acquireProcessLock({ + lockDirPath: path.join(home, 'plugins.lock'), + owner: { ...readCurrentOwnerIdentity(), acquiredAtMs: Date.now() }, + description: 'plugin installation', + }); + const installation = crypto.randomUUID(); + const project = path.join(home, 'plugins', installation); + let published = false; + try { + fs.mkdirSync(project, { recursive: true, mode: 0o700 }); + const artifact = path.join(project, 'artifact.tgz'); + fs.writeFileSync(artifact, bytes, { mode: 0o600, flag: 'wx' }); + fs.writeFileSync(path.join(project, 'package.json'), JSON.stringify({ private: true })); + await installInProject(project, host.env, artifact); + const lock = JSON.parse(fs.readFileSync(path.join(project, 'package-lock.json'), 'utf8')); + const names = Object.keys(lock.packages?.['']?.dependencies ?? {}); + if (names.length !== 1 || !isPackageName(names[0]!)) + throw new AppError('INVALID_ARGS', 'Artifact has an invalid package name', { + reason: 'invalid_plugin', + }); + const name = names[0]!; + if (lock.packages?.[`node_modules/${name}`]?.integrity !== integrity) + throw new AppError('INVALID_ARGS', 'Artifact contents changed during installation', { + reason: 'artifact_integrity_mismatch', + }); + const directory = installationDirectory(home, name, installation); + const root = fs.realpathSync(project); + const actualDirectory = fs.realpathSync(directory); + if (!actualDirectory.startsWith(`${root}${path.sep}`)) + throw new AppError('INVALID_ARGS', 'Artifact package escaped its installation', { + reason: 'invalid_plugin', + }); + const manifestPath = fs.realpathSync(path.join(directory, 'package.json')); + if (!manifestPath.startsWith(`${actualDirectory}${path.sep}`)) + throw new AppError('INVALID_ARGS', 'Artifact manifest escaped its package', { + reason: 'invalid_plugin', + }); + const { readPackageJson } = await import('./discovery.ts'); + const manifest = readPackageJson(directory); + if (manifest.name !== name || !isExactVersion(manifest.version)) + throw new AppError('INVALID_ARGS', `Invalid artifact package identity: ${name}`, { + reason: 'invalid_plugin', + }); + const selection: PluginSelection = { + installation, + version: manifest.version, + artifact: { integrity, version: manifest.version }, + }; + await describeInstallation(name, directory, selection); + const config = readPluginConfig(host.env); + const selections = { ...config.plugins }; + if (Object.hasOwn(selections, name)) + throw new AppError('INVALID_ARGS', `Plugin is already installed: ${name}`, { + reason: 'plugin_already_installed', + }); + selections[name] = selection; + publishFileSync({ + destination: configPath, + contents: `${JSON.stringify({ ...config, plugins: selections }, null, 2)}\n`, + mode: 0o600, + }); + published = true; + return { name, version: manifest.version, installation, integrity }; + } finally { + if (!published) fs.rmSync(project, { recursive: true, force: true }); + await release(); + } +} diff --git a/src/cli/commands/__tests__/plugins.test.ts b/src/cli/commands/__tests__/plugins.test.ts index 207589a32d..eecc23864f 100644 --- a/src/cli/commands/__tests__/plugins.test.ts +++ b/src/cli/commands/__tests__/plugins.test.ts @@ -1,8 +1,10 @@ import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; +import { runCmdSync } from '@agent-device/host-kit/command'; import { afterEach, test, vi } from 'vitest'; import { runCli } from '../../../cli.ts'; +import * as pluginStore from '@agent-device/plugins/store'; import { readCurrentOwnerIdentity } from '@agent-device/host-kit/process'; import { pluginHome, @@ -66,6 +68,11 @@ test('plugin schema exposes operator help and preserves scoped npm package specs const help = await usageForCommand('plugins'); assert.ok(help); assert.match(help, /plugins list \[--state-dir \]\|add/); + assert.match(help, /add-artifact /); + assert.deepEqual( + parseRawArgs(['plugins', 'add-artifact', './plugin.tgz', '--json']).positionals, + ['add-artifact', './plugin.tgz'], + ); }); test('plugins list reports the running daemon inventory next to the store selections', async () => { @@ -184,3 +191,108 @@ test('plugins list says when the daemon record cannot be used instead of hiding assert.match(text, /No provider plugins installed\./); assert.match(text, /daemon record for .* is invalid, so its providers are unknown/); }); + +test('plugins add-artifact installs without loading the factory', 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 source = path.join(home, 'source'); + fs.mkdirSync(source); + const marker = path.join(home, 'executed'); + fs.writeFileSync( + path.join(source, 'package.json'), + JSON.stringify({ + name: 'cli-artifact', + version: '1.0.0', + type: 'module', + exports: { './agent-device': './plugin.mjs' }, + scripts: { preinstall: 'node sentinel.cjs' }, + }), + ); + fs.writeFileSync( + path.join(source, 'sentinel.cjs'), + `require('node:fs').writeFileSync(${JSON.stringify(marker)}, 'script')`, + ); + fs.writeFileSync( + path.join(source, 'plugin.mjs'), + `import fs from 'node:fs'; fs.writeFileSync(${JSON.stringify(marker)}, 'factory'); export default () => ({});`, + ); + const packedResult = runCmdSync( + 'npm', + ['pack', '--ignore-scripts', '--json', '--pack-destination', home], + { cwd: source }, + ); + assert.equal(packedResult.exitCode, 0, packedResult.stderr); + const packed = JSON.parse(packedResult.stdout); + const archive = path.join(home, packed[0].filename); + const capture = beginStdoutCapture(); + try { + await runCli(['plugins', 'add-artifact', archive, '--json'], { sendToDaemon: vi.fn() }); + const { data } = JSON.parse(capture.read()); + assert.equal(data.artifact.name, 'cli-artifact'); + assert.equal(data.artifact.version, '1.0.0'); + assert.match(data.artifact.integrity, /^sha512-/); + assert.equal(data.artifact.compatibility, 'unchecked'); + assert.equal('plugins' in data, false); + assert.equal(data.restartRequired, true); + assert.equal(fs.existsSync(marker), false); + } finally { + capture.restore(); + } +}); + +test.each([false, true])('artifact receipt uses the executing CLI host (json=%s)', async (json) => { + const { home, env } = pluginHome(); + const cwd = path.join(home, 'workspace'); + const stateDir = path.join(home, 'state'); + fs.mkdirSync(cwd); + fs.mkdirSync(stateDir); + fs.writeFileSync(path.join(stateDir, 'daemon.json'), '{invalid'); + const host = { + cwd, + env: { + ...env, + AGENT_DEVICE_STATE_DIR: stateDir, + AGENT_DEVICE_NO_UPDATE_NOTIFIER: '1', + }, + }; + const artifact = { + name: 'cli-artifact', + version: '1.0.0', + installation: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa', + integrity: `sha512-${Buffer.alloc(64).toString('base64')}`, + }; + const install = vi.spyOn(pluginStore, 'addPluginArtifact').mockResolvedValue(artifact); + const sendToDaemon = vi.fn(async () => { + throw new Error('unexpected daemon access'); + }); + const capture = beginStdoutCapture(); + try { + await runCli( + ['plugins', 'add-artifact', './fixture.tgz', ...(json ? ['--json'] : [])], + { sendToDaemon }, + host, + ); + assert.equal(install.mock.calls.length, 1); + assert.equal(install.mock.calls[0]?.[0], './fixture.tgz'); + const installedHost = install.mock.calls[0]![1]; + assert.equal(installedHost.cwd, cwd); + assert.deepEqual(Object.keys(installedHost.env).sort(), Object.keys(host.env).sort()); + for (const [key, value] of Object.entries(host.env)) + assert.equal(installedHost.env[key], value); + assert.equal(sendToDaemon.mock.calls.length, 0); + const output = capture.read(); + if (json) { + const { data } = JSON.parse(output); + assert.deepEqual(data.artifact, { ...artifact, compatibility: 'unchecked' }); + assert.equal('plugins' in data, false); + assert.equal(data.daemonRecord, 'invalid'); + } else { + assert.match(output, /compatibility unchecked/i); + assert.match(output, /plugins list/); + } + } finally { + capture.restore(); + } +}); diff --git a/src/cli/commands/plugins.ts b/src/cli/commands/plugins.ts index dea8b696f6..dc0a6cfc8e 100644 --- a/src/cli/commands/plugins.ts +++ b/src/cli/commands/plugins.ts @@ -5,32 +5,34 @@ import { readDaemonStatus, } from '@agent-device/daemon-contracts/daemon-registration'; import { AppError } from '@agent-device/kernel/errors'; -import { changePlugin, listPlugins } from '@agent-device/plugins/store'; +import { addPluginArtifact, changePlugin, listPlugins } from '@agent-device/plugins/store'; import { BUILTIN_PROVIDER_IDS } from '../../builtin-provider-ids.ts'; import { writeCommandOutput } from './shared.ts'; import type { ClientCommandHandler } from './router-types.ts'; -export const pluginsCommand: ClientCommandHandler = async ({ positionals, flags }) => { +export const pluginsCommand: ClientCommandHandler = async ({ host, positionals, flags }) => { const [action = 'list', name, extra] = positionals; if ( extra || - !['add', 'update', 'remove', 'list'].includes(action) || + !['add', 'add-artifact', 'update', 'remove', 'list'].includes(action) || (action === 'list' ? name !== undefined : !name) ) { throw new AppError( 'INVALID_ARGS', - 'Use plugins list, add , update , or remove ', + 'Use plugins list, add , add-artifact , update , or remove ', ); } - if (action !== 'list' && name) { - await changePlugin(action as 'add' | 'update' | 'remove', name, process.env); + const artifact = + action === 'add-artifact' && name ? await addPluginArtifact(name, host) : undefined; + if (action !== 'list' && action !== 'add-artifact' && name) { + await changePlugin(action as 'add' | 'update' | 'remove', name, host.env); } - const plugins = await listPlugins(process.env, BUILTIN_PROVIDER_IDS); - const daemon = readDaemonStatus(resolveDaemonPaths(flags.stateDir)); + const plugins = artifact ? [] : await listPlugins(host.env, BUILTIN_PROVIDER_IDS); + const daemon = readDaemonStatus(resolveDaemonPaths(flags.stateDir, host)); const daemonPlugins = readPluginInventory(daemon.plugins); const failedInDaemon = daemonPlugins.filter(({ state }) => state === 'failed'); const data = { - plugins, + ...(artifact ? { artifact: { ...artifact, compatibility: 'unchecked' } } : { plugins }), ...(daemon.state === 'running' ? { daemon: { pid: daemon.pid, stateDir: daemon.stateDir, plugins: daemonPlugins } } : {}), @@ -39,17 +41,21 @@ export const pluginsCommand: ClientCommandHandler = async ({ positionals, flags }; await writeCommandOutput(flags, data, () => [ - ...plugins.map((plugin) => - plugin.compatible - ? `${plugin.name}@${plugin.version} (${plugin.provider ?? plugin.backend})` - : plugin.name === undefined - ? `Plugin config unavailable: ${plugin.error?.message}` - : `${plugin.name}: unavailable; run plugins update ${plugin.name} or plugins remove ${plugin.name}`, - ), + ...(artifact + ? [ + `${artifact.name}@${artifact.version}: installed; compatibility unchecked. Run agent-device plugins list.`, + ] + : plugins.map((plugin) => + plugin.compatible + ? `${plugin.name}@${plugin.version} (${plugin.provider ?? plugin.backend})` + : plugin.name === undefined + ? `Plugin config unavailable: ${plugin.error?.message}` + : `${plugin.name}: unavailable; run plugins update ${plugin.name} or plugins remove ${plugin.name}`, + )), ...(action !== 'list' ? ['Restart the local daemon after closing active sessions to use the changed plugin set.'] : []), - ...(plugins.length === 0 ? ['No provider plugins installed.'] : []), + ...(!artifact && plugins.length === 0 ? ['No provider plugins installed.'] : []), ...(isUnusableRecord(daemon) ? [ `The daemon record for ${daemon.stateDir} is ${daemon.state}, so its providers are unknown.`, diff --git a/src/core/interactors/limrun-ios-runner.fixtures.ts b/src/core/interactors/limrun-ios-runner.fixtures.ts index 6fc4eba525..a893808ab0 100644 --- a/src/core/interactors/limrun-ios-runner.fixtures.ts +++ b/src/core/interactors/limrun-ios-runner.fixtures.ts @@ -15,6 +15,18 @@ afterEach(async () => { cleanups.length = 0; }); +async function readRequestBody(request: IncomingMessage): Promise { + const chunks: Buffer[] = []; + try { + for await (const chunk of request) chunks.push(Buffer.from(chunk)); + } catch (error) { + if (request.destroyed && (error as NodeJS.ErrnoException).code === 'ECONNRESET') + return undefined; + throw error; + } + return Buffer.concat(chunks); +} + type Session = Parameters[0]; type Manifest = { files: Array<{ path: string; mode: number }>; @@ -195,9 +207,8 @@ export async function fixture( response.writeHead(401).end(); return; } - const chunks: Buffer[] = []; - for await (const chunk of request) chunks.push(Buffer.from(chunk)); - let body = Buffer.concat(chunks); + let body = await readRequestBody(request); + if (body === undefined) return; if (request.headers['content-encoding'] === 'gzip') body = gunzipSync(body); if (storage.serve(request, response, body)) return; if (request.url === '/v1/ios_test/api/sync') { diff --git a/src/core/interactors/limrun-ios-runner.test.ts b/src/core/interactors/limrun-ios-runner.test.ts index 62c85c4519..da34e8238b 100644 --- a/src/core/interactors/limrun-ios-runner.test.ts +++ b/src/core/interactors/limrun-ios-runner.test.ts @@ -1,5 +1,6 @@ import { promises as fs } from 'node:fs'; import path from 'node:path'; +import { request as httpRequest } from 'node:http'; import { registerRequestAbort, markRequestCanceled, @@ -802,3 +803,18 @@ test('a new cache waiter retries after the canceled preparation finishes cleanup cleanup.mockRestore(); } }); + +test('an interrupted upload does not prevent the fixture from serving a later request', async () => { + const f = await fixture(); + const request = httpRequest(`${f.apiUrl}/sync`, { + method: 'POST', + headers: { authorization: 'Bearer instance-token', 'content-length': '100' }, + }); + request.on('error', () => {}); + request.write('partial'); + await vi.waitFor(() => expect(f.requests).toContain('/v1/ios_test/api/sync')); + request.destroy(); + await new Promise((resolve) => request.once('close', resolve)); + await f.runner.applicationTools.prewarmRunnerCache(f.device, {}, new AbortController().signal); + expect(f.uploads).toHaveLength(1); +}); diff --git a/src/sdk/plugins.ts b/src/sdk/plugins.ts index 411bccad5a..56aabad01b 100644 --- a/src/sdk/plugins.ts +++ b/src/sdk/plugins.ts @@ -34,3 +34,5 @@ export type { ReplayExecutionPlugin, ReplayExecutionResolver, } from '@agent-device/contracts/replay-execution'; + +export { addPluginArtifact } from '@agent-device/plugins/store'; diff --git a/test/integration/installed-package-metro.test.ts b/test/integration/installed-package-metro.test.ts index 1ffa91b772..fab3651dd0 100644 --- a/test/integration/installed-package-metro.test.ts +++ b/test/integration/installed-package-metro.test.ts @@ -108,11 +108,15 @@ async function typeCheckInstalledPluginContract(consumerRoot: string): Promise }) { + return await addPluginArtifact(archive, host); +} + export async function hostConsumer(host: NonNullable) { const options: StartAgentDeviceOptions = { stateDir: './state', host, plugins: [await example(), maestro(), replay()] }; const running: AgentDeviceHost = await startAgentDevice(options); @@ -323,6 +327,38 @@ test('installed package exposes Node APIs and packaged companion tunnel entrypoi ); } await typeCheckInstalledPluginContract(consumerRoot); + const managedHome = path.join(consumerRoot, 'managed-plugin-home'); + const replayArchive = path.join(consumerRoot, 'replay.tgz'); + const expectedIntegrity = `sha512-${crypto.createHash('sha512').update(fs.readFileSync(replayArchive)).digest('base64')}`; + const selection = await runNodeModuleJson( + consumerRoot, + ['--input-type=module', '-e'], + `import { addPluginArtifact } from 'agent-device/plugins'; + const selected = await addPluginArtifact(${JSON.stringify(replayArchive)}, { + cwd: process.cwd(), + env: { ...process.env, HOME: ${JSON.stringify(managedHome)}, AGENT_DEVICE_HOME: ${JSON.stringify(managedHome)} }, + }); + console.log(JSON.stringify(selected));`, + ); + assert.equal(selection.name, '@agent-device/replay'); + assert.equal(selection.integrity, expectedIntegrity); + const inventory = await runCmd( + process.execPath, + [path.join(installedPackageRoot, 'bin/agent-device.mjs'), 'plugins', 'list', '--json'], + { + cwd: consumerRoot, + env: { ...process.env, HOME: managedHome, AGENT_DEVICE_HOME: managedHome }, + timeoutMs: SUBPROCESS_TIMEOUT_MS, + }, + ); + const selectedPlugin = readJson(inventory.stdout).data.plugins.find( + (plugin: { name?: string }) => plugin.name === '@agent-device/replay', + ); + assert.equal(selectedPlugin?.installation, selection.installation); + assert.equal(selectedPlugin?.integrity, expectedIntegrity); + assert.equal(selectedPlugin?.version, selection.version); + assert.equal(selectedPlugin?.backend, 'ad'); + assert.equal(selectedPlugin?.compatible, true); fs.writeFileSync( path.join(consumerRoot, 'fixture-plugin.mjs'), String.raw` @@ -634,7 +670,7 @@ assert.equal(fs.existsSync(path.join(cwd, 'host-a', 'daemon.json')), false); return runtime.provider; }, './metro': (mod) => mod.buildBundleUrl('https://public.example.test', 'ios'), - './plugins': (mod) => Object.keys(mod).length === 0, + './plugins': (mod) => Object.keys(mod).length === 1 && typeof mod.addPluginArtifact === 'function', './plugins/webdriver': (mod) => Object.keys(mod).length === 0, './remote-config': (mod) => typeof mod, './selectors': (mod) => diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index 78f316481b..e8f4f51f41 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -196,3 +196,22 @@ For a format backend such as `maestro`, setup returns `{ replayBackend: { create For the native `ad` backend, setup returns `{ execution: { create() }, dispose? }`. The object returned by `create()` implements `inspectAdReplay`, `runAdReplay`, and `runReplayTestSuite`. Return only the factory for your backend: the host rejects a native setup that provides `replayBackend`, or a format setup that provides `execution`. The daemon owns sessions, policy, selector/ref authority, and device cleanup. `dispose` runs once after requests drain. Client-side source collection and export dispose their scoped plugin registry when the operation ends. + + +## Install a local plugin artifact + +On each host that needs the plugin, install its `.tgz` file: + +```sh +agent-device plugins add-artifact ./provider-plugin.tgz --json +agent-device plugins list --json +``` + +The archive must contain an npm package with a name, an exact version, and an `./agent-device` export. Installation does not run package lifecycle scripts or load the plugin factory. The list command loads the factory to check compatibility. The installation returns an `artifact` receipt with compatibility marked `unchecked`. Run `plugins list --json` for the checked `plugins` inventory, including the artifact's installation ID and SHA-512 integrity. If the package is already selected, remove it before adding the artifact. `plugins update` does not update artifacts from the registry; remove the selection and add the replacement artifact. Finish active sessions and restart the daemon after changing the selection. + +A Node.js host can call the same manager with an explicit environment and working directory: + +```js +import { addPluginArtifact } from 'agent-device/plugins'; +await addPluginArtifact('./provider-plugin.tgz', { env: process.env, cwd: process.cwd() }); +```