@adea-ai/plugins 1.0.0

package/src/agent-plugins-harness.test.ts

@@ -0,0 +1,272 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, symlink, rm, realpath } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { compileAgentPackage } from './agent-plugins-catalog.js'
+import {
+  PLUGIN_SCHEMA_ID,
+  MCP_SCHEMA_ID,
+  type HarnessProfile,
+  type McpServer,
+} from './agent-plugins-schema.js'
+import {
+  createInstallationPlan,
+  resolveMcpBinding,
+  expandPluginPaths,
+  verifyBindingPaths,
+} from './agent-plugins-harness.js'
+
+function profile(overrides: Partial<HarnessProfile> = {}): HarnessProfile {
+  return {
+    profileVersion: 1,
+    harness: 'example-harness',
+    runtimeVersion: 'fixture-1',
+    adapterVersion: 'fixture-1',
+    agentPlugins: {
+      versions: ['1.0.0'],
+      skills: true,
+      mcpTransports: ['stdio', 'streamable-http'],
+    },
+    components: { skillDirectories: true, mcpTransports: ['stdio', 'streamable-http'] },
+    ...overrides,
+  }
+}
+function packageFixture(extra: Record<string, string> = {}) {
+  const files = new Map(
+    Object.entries({
+      'plugin.json': JSON.stringify({ $schema: PLUGIN_SCHEMA_ID, name: 'issues' }),
+      'skills/issues/SKILL.md':
+        '---\nname: issues\ndescription: Work with issues.\n---\nInstructions.',
+      'mcp.json': JSON.stringify({
+        $schema: MCP_SCHEMA_ID,
+        mcpServers: {
+          api: { type: 'streamable-http', url: 'https://example.test/mcp' },
+          local: { type: 'stdio', command: 'node' },
+        },
+      }),
+      ...extra,
+    }).map(([path, text]) => [path, new TextEncoder().encode(text)])
+  )
+  return compileAgentPackage({ files, name: 'issues' })
+}
+function input(pkg = packageFixture()) {
+  return {
+    pluginId: 'plugin:test:issues',
+    releaseId: `release:${'a'.repeat(64)}`,
+    instanceId: 'workspace-a/user-a',
+    source: {
+      repositoryUrl: 'https://github.com/example/issues',
+      commitSha: 'b'.repeat(40),
+      pluginSubdirectory: '.',
+      contentDigest: pkg.sourceDigest,
+    },
+    package: pkg,
+    profile: profile(),
+  }
+}
+
+describe('Control Plane installation plan v2', () => {
+  it('selects a single native package root without copying into harness-specific directories', () => {
+    const plan = createInstallationPlan(input())
+    assert.equal(plan.planVersion, 2)
+    assert.equal(plan.strategy, 'native-agent-plugin')
+    assert.equal(plan.compatibility, 'full')
+    assert.deepEqual(plan.selection.skillDirectories, ['skills/issues'])
+    assert.equal(plan.allowedToActivate, false)
+    assert.equal(plan.approvalRequired, true)
+    assert.ok(plan.packageKey.startsWith('packages/'))
+  })
+  it('uses component bindings for a non-native harness without changing package bytes', () => {
+    const original = input()
+    const native = createInstallationPlan(original)
+    const adapted = createInstallationPlan({
+      ...original,
+      profile: profile({ agentPlugins: { versions: [], skills: false, mcpTransports: [] } }),
+    })
+    assert.equal(adapted.strategy, 'component-adapter')
+    assert.equal(adapted.package.packageDigest, native.package.packageDigest)
+    assert.deepEqual(adapted.selection, native.selection)
+  })
+  it('does not treat a harness name as proof of support', () => {
+    const plan = createInstallationPlan({
+      ...input(),
+      profile: profile({
+        harness: 'codex',
+        agentPlugins: { versions: [], skills: false, mcpTransports: [] },
+        components: { skillDirectories: false, mcpTransports: [] },
+      }),
+    })
+    assert.equal(plan.compatibility, 'unsupported')
+    assert.equal(plan.strategy, 'unavailable')
+  })
+  it('supports explicit partial adoption but requires opt-in before selecting components', () => {
+    const p = profile({
+      agentPlugins: { versions: ['1.0.0'], skills: true, mcpTransports: [] },
+      components: { skillDirectories: false, mcpTransports: [] },
+    })
+    const blocked = createInstallationPlan({ ...input(), profile: p })
+    assert.equal(blocked.compatibility, 'partial')
+    assert.equal(blocked.strategy, 'unavailable')
+    assert.deepEqual(blocked.selection.skillDirectories, [])
+    const accepted = createInstallationPlan({ ...input(), profile: p, allowPartial: true })
+    assert.equal(accepted.strategy, 'native-agent-plugin')
+    assert.deepEqual(accepted.selection.skillDirectories, ['skills/issues'])
+    assert.equal(accepted.disabled.length, 2)
+  })
+  it('chooses a complete component adapter over a native loader with weaker capabilities', () => {
+    const plan = createInstallationPlan({
+      ...input(),
+      profile: profile({ agentPlugins: { versions: ['1.0.0'], skills: true, mcpTransports: [] } }),
+    })
+    assert.equal(plan.strategy, 'component-adapter')
+    assert.equal(plan.compatibility, 'full')
+  })
+  it('does not activate proprietary extras accidentally through a native loader', () => {
+    const pkg = packageFixture({ 'hooks/hooks.json': '{}' })
+    const plan = createInstallationPlan({ ...input(pkg), allowPartial: true })
+    assert.equal(plan.strategy, 'component-adapter')
+    assert.equal(plan.compatibility, 'partial')
+    assert.ok(plan.disabled.some((item) => item.component === 'hooks'))
+  })
+  it('preserves instance data across releases and harnesses but isolates other instances', () => {
+    const first = createInstallationPlan(input())
+    const updatedPkg = packageFixture({ 'CHANGELOG.md': 'A new release.' })
+    const updated = createInstallationPlan({
+      ...input(updatedPkg),
+      releaseId: `release:${'c'.repeat(64)}`,
+      profile: profile({ harness: 'another-harness' }),
+    })
+    assert.equal(first.dataKey, updated.dataKey)
+    assert.notEqual(first.packageKey, updated.packageKey)
+    assert.notEqual(
+      first.dataKey,
+      createInstallationPlan({ ...input(), instanceId: 'workspace-b/user-a' }).dataKey
+    )
+    assert.notEqual(
+      first.dataKey,
+      createInstallationPlan({ ...input(), pluginId: 'plugin:other:issues' }).dataKey
+    )
+  })
+  it('does not reuse a package cache across source commits with potentially different file modes', () => {
+    const original = input()
+    const other = { ...original, source: { ...original.source, commitSha: 'c'.repeat(40) } }
+    assert.notEqual(
+      createInstallationPlan(original).packageKey,
+      createInstallationPlan(other).packageKey
+    )
+    assert.equal(createInstallationPlan(original).dataKey, createInstallationPlan(other).dataKey)
+  })
+  it('rejects mismatched source provenance and unversioned capability claims', () => {
+    const args = input()
+    assert.throws(() =>
+      createInstallationPlan({
+        ...args,
+        source: { ...args.source, contentDigest: `sha256:${'f'.repeat(64)}` },
+      })
+    )
+    assert.throws(() =>
+      createInstallationPlan({ ...args, profile: { ...args.profile, runtimeVersion: '' } })
+    )
+  })
+})
+
+describe('MCP binding preparation', () => {
+  const roots = { pluginRoot: '/packages/with spaces', pluginData: '/data/with spaces' }
+  it('keeps command and arguments separate and overrides reserved variables last', () => {
+    const server: McpServer = {
+      type: 'stdio',
+      command: 'node',
+      args: ['${PLUGIN_ROOT}/run.mjs', '${UNRECOGNIZED}', '${PLUGIN_DATA}'],
+      env: { CONFIG: '${PLUGIN_ROOT}/config.json' },
+    }
+    const binding = resolveMcpBinding(server, roots, {
+      PLUGIN_ROOT: 'wrong',
+      PLUGIN_DATA: 'wrong',
+      SAFE: 'yes',
+    })
+    assert.equal(binding.type, 'stdio')
+    if (binding.type !== 'stdio') return
+    assert.equal(binding.command, 'node')
+    assert.equal(binding.shell, false)
+    assert.equal(binding.cwd, roots.pluginRoot)
+    assert.deepEqual(binding.args, [
+      '/packages/with spaces/run.mjs',
+      '${UNRECOGNIZED}',
+      '/data/with spaces',
+    ])
+    assert.equal(binding.env.PLUGIN_ROOT, roots.pluginRoot)
+    assert.equal(binding.env.PLUGIN_DATA, roots.pluginData)
+    assert.equal(binding.env.SAFE, 'yes')
+  })
+  it('expands once, leaving replacement text and unrelated placeholders literal', () => {
+    assert.equal(
+      expandPluginPaths('${PLUGIN_ROOT}/${PLUGIN_DATA}/${HOME}', {
+        pluginRoot: '/root/${PLUGIN_DATA}',
+        pluginData: '/state',
+      }),
+      '/root/${PLUGIN_DATA}//state/${HOME}'
+    )
+  })
+  it('handles case-insensitive environment overlays without reserved-name shadowing', () => {
+    const binding = resolveMcpBinding(
+      { type: 'stdio', command: 'node', env: { Path: '/safe' } },
+      roots,
+      { PATH: '/old', plugin_root: 'wrong', Plugin_Data: 'wrong' },
+      'win32'
+    )
+    assert.equal(binding.type, 'stdio')
+    if (binding.type !== 'stdio') return
+    assert.equal(binding.env.PATH, undefined)
+    assert.equal(binding.env.Path, '/safe')
+    assert.equal(binding.env.plugin_root, undefined)
+    assert.equal(binding.env.Plugin_Data, undefined)
+    assert.equal(binding.env.PLUGIN_ROOT, roots.pluginRoot)
+  })
+  it('never expands remote URLs or headers and requires same-origin redirects', () => {
+    const binding = resolveMcpBinding(
+      {
+        type: 'streamable-http',
+        url: 'https://example.test/mcp',
+        headers: { 'X-Literal': '${PLUGIN_DATA}' },
+      },
+      roots
+    )
+    assert.deepEqual(binding, {
+      type: 'streamable-http',
+      url: 'https://example.test/mcp',
+      headers: { 'X-Literal': '${PLUGIN_DATA}' },
+      redirectPolicy: 'same-origin',
+      authorization: 'control-plane',
+    })
+  })
+  it('rejects filesystem-resolved escapes before activation', async () => {
+    const temporary = await mkdtemp(join(tmpdir(), 'adea-binding-'))
+    try {
+      const pluginRoot = join(temporary, 'package')
+      const pluginData = join(temporary, 'data')
+      await mkdir(pluginRoot)
+      await mkdir(pluginData)
+      await writeFile(join(temporary, 'outside'), 'never execute')
+      await symlink(join(temporary, 'outside'), join(pluginRoot, 'server'))
+      const canonical = {
+        pluginRoot: await realpath(pluginRoot),
+        pluginData: await realpath(pluginData),
+      }
+      await assert.rejects(
+        verifyBindingPaths({ type: 'stdio', command: './server' }, canonical),
+        /outside/
+      )
+      await symlink(temporary, join(pluginData, 'escape'))
+      await assert.rejects(
+        verifyBindingPaths(
+          { type: 'stdio', command: 'node', cwd: '${PLUGIN_DATA}/escape' },
+          canonical
+        ),
+        /outside/
+      )
+    } finally {
+      await rm(temporary, { recursive: true, force: true })
+    }
+  })
+})

package/src/agent-plugins-harness.ts

@@ -0,0 +1,281 @@
+import { isAbsolute, resolve, relative, sep } from 'node:path'
+import { realpath } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import {
+  HarnessProfileSchema,
+  InstallationPlanSchema,
+  type HarnessProfile,
+  type McpServer,
+  type InstallationPlan,
+} from './agent-plugins-schema.js'
+import type { Catalog } from './schema.js'
+import { verifyPortableCatalog, PACKAGE_METADATA_KEY } from './portable-catalog.js'
+import { verifyAgentPackage, validateServer } from './agent-plugins-catalog.js'
+
+export interface InstallationInput {
+  readonly pluginId: string
+  readonly releaseId: string
+  readonly instanceId: string
+  readonly source: InstallationPlan['source']
+  readonly package: unknown
+  readonly profile: HarnessProfile
+  readonly requiredCredentials?: readonly string[]
+  readonly requiredConnectors?: readonly string[]
+  readonly allowPartial?: boolean
+}
+export interface CatalogInstallationInput {
+  readonly catalog: Catalog
+  readonly pluginId: string
+  readonly releaseId?: string
+  readonly instanceId: string
+  readonly profile: HarnessProfile
+  readonly allowPartial?: boolean
+}
+
+/** Resolve the exact catalog release before planning. The caller must also authenticate
+ * the catalog publisher and verify its artifact integrity before invoking this API.
+ */
+export function createCatalogInstallationPlan(input: CatalogInstallationInput): InstallationPlan {
+  verifyPortableCatalog(input.catalog)
+  const plugin = input.catalog.plugins.find((entry) => entry.pluginId === input.pluginId)
+  if (!plugin) throw new Error(`PLUGIN_NOT_FOUND: ${input.pluginId}`)
+  const release = plugin.availableReleases.find(
+    (entry) => entry.releaseId === (input.releaseId ?? plugin.currentReleaseId)
+  )
+  if (!release) throw new Error('RELEASE_NOT_FOUND')
+  if (release.contentResolution !== 'complete') throw new Error('COMPLETE_SOURCE_REQUIRED')
+  const pkg = release.releaseMetadata[PACKAGE_METADATA_KEY]
+  if (pkg === undefined)
+    throw new Error(
+      'PORTABLE_RESYNC_REQUIRED: run a full catalog sync before planning portable installation'
+    )
+  return createInstallationPlan({
+    pluginId: plugin.pluginId,
+    releaseId: release.releaseId,
+    instanceId: input.instanceId,
+    profile: input.profile,
+    package: pkg,
+    allowPartial: input.allowPartial === true,
+    source: {
+      repositoryUrl: release.resolvedRepositoryUrl,
+      commitSha: release.resolvedCommitSha,
+      pluginSubdirectory: release.pluginSubdirectory,
+      contentDigest: release.canonicalContentDigest,
+    },
+    requiredCredentials: release.requiredCredentials,
+    requiredConnectors: release.requiredConnectors,
+  })
+}
+
+function identity(...parts: string[]): string {
+  return createHash('sha256').update(JSON.stringify(parts)).digest('hex')
+}
+/** A declarative proposal, never an execution grant. No brand-based support assumptions. */
+export function createInstallationPlan(input: InstallationInput): InstallationPlan {
+  const profile = HarnessProfileSchema.parse(input.profile)
+  const pkg = verifyAgentPackage(input.package)
+  if (pkg.sourceDigest !== input.source.contentDigest)
+    throw new Error('Package recipe does not match the selected immutable release.')
+  if (!input.instanceId || input.instanceId.length > 256)
+    throw new Error('A stable installation instanceId is required.')
+  const disabled: InstallationPlan['disabled'] = []
+  for (const item of pkg.nonPortable) disabled.push({ component: item.kind, reason: item.reason })
+  for (const item of pkg.diagnostics.filter((entry) => entry.severity === 'error'))
+    disabled.push({ component: item.path, reason: item.message })
+
+  const nativeEligible =
+    profile.agentPlugins.versions.includes(pkg.specVersion) &&
+    pkg.nonPortable.length === 0 &&
+    !Object.keys(pkg.manifest?.extensions ?? {}).length
+  const nativeCoverage =
+    (profile.agentPlugins.skills ? pkg.skills.length : 0) +
+    Object.values(pkg.mcpServers).filter((server) =>
+      profile.agentPlugins.mcpTransports.includes(server.type)
+    ).length
+  const adapterCoverage =
+    (profile.components.skillDirectories ? pkg.skills.length : 0) +
+    Object.values(pkg.mcpServers).filter((server) =>
+      profile.components.mcpTransports.includes(server.type)
+    ).length
+  const native = nativeEligible && nativeCoverage > 0 && nativeCoverage >= adapterCoverage
+  const strategy =
+    pkg.status === 'unavailable'
+      ? 'unavailable'
+      : native
+        ? 'native-agent-plugin'
+        : 'component-adapter'
+  let skillDirectories: string[] = []
+  const servers = new Map<string, McpServer>()
+  if (strategy !== 'unavailable') {
+    if (native ? profile.agentPlugins.skills : profile.components.skillDirectories)
+      skillDirectories = pkg.skills.map((skill) => skill.path)
+    else
+      for (const skill of pkg.skills)
+        disabled.push({
+          component: `skill:${skill.name}`,
+          reason: 'The selected adapter cannot expose skill directories.',
+        })
+    for (const [name, server] of Object.entries(pkg.mcpServers)) {
+      if (
+        (native ? profile.agentPlugins.mcpTransports : profile.components.mcpTransports).includes(
+          server.type
+        )
+      )
+        servers.set(name, server)
+      else
+        disabled.push({
+          component: `mcp:${name}`,
+          reason: `No ${server.type} MCP binding on this harness adapter.`,
+        })
+    }
+  }
+  const hasContent = skillDirectories.length > 0 || servers.size > 0
+  const compatibility = !hasContent ? 'unsupported' : disabled.length > 0 ? 'partial' : 'full'
+  const selectedStrategy =
+    !hasContent || (compatibility === 'partial' && !input.allowPartial) ? 'unavailable' : strategy
+  return InstallationPlanSchema.parse({
+    planVersion: 2,
+    pluginId: input.pluginId,
+    releaseId: input.releaseId,
+    instanceId: input.instanceId,
+    profile,
+    source: input.source,
+    package: pkg,
+    // Git source identity also pins executable modes, which the v1 byte snapshot omits.
+    packageKey: pkg.packageDigest
+      ? `packages/${identity(input.source.repositoryUrl, input.source.commitSha, input.source.pluginSubdirectory, pkg.packageDigest)}`
+      : '',
+    // Deliberately excludes release, package digest and harness. Switching harnesses or updating
+    // the same approved instance preserves data; distinct scopes use distinct instance IDs.
+    dataKey: `instances/${identity(input.pluginId, input.instanceId)}`,
+    preserveDataAcrossUpdates: true,
+    strategy: selectedStrategy,
+    compatibility,
+    allowedToActivate: false,
+    approvalRequired: true,
+    selection:
+      selectedStrategy === 'unavailable'
+        ? { skillDirectories: [], mcpServers: {} }
+        : { skillDirectories, mcpServers: Object.fromEntries(servers) },
+    disabled,
+    requiredCredentials: [...(input.requiredCredentials ?? [])],
+    requiredConnectors: [...(input.requiredConnectors ?? [])],
+    preconditions: [
+      'Verify catalog integrity/provenance and exact source digest before applying the package recipe.',
+      'Use an immutable package root; preserve source file modes and complete skill directories/resources.',
+      'Create a writable data directory for this instance; never key it by release or copy credentials between instances.',
+      'Control Plane must authorize activation, filesystem/network access, executables and credential bindings.',
+      'Recheck the actual harness/runtime/adapter profile and realpath containment immediately before activation.',
+      'Native mode registers exactly one package root. Component mode registers only the selected skill directories and MCP bindings, never legacy hooks/config files.',
+      'Do not install dependencies or run lifecycle scripts implicitly; review required executables and skill compatibility requirements.',
+      'Skill allowed-tools metadata is advisory and never grants permission.',
+      'Namespace registrations by installation identity; detect skill/server name collisions instead of overwriting existing harness configuration.',
+      'Remote authorization is client-managed. Do not expand remote URLs/headers or forward configured headers to another origin without authorization.',
+    ],
+  })
+}
+
+export interface RuntimeRoots {
+  readonly pluginRoot: string
+  readonly pluginData: string
+}
+/** Exact, single-pass expansion. Replacement text is never scanned recursively. */
+export function expandPluginPaths(value: string, roots: RuntimeRoots): string {
+  return value.replace(/\$\{(PLUGIN_ROOT|PLUGIN_DATA)\}/g, (_match, name: string) =>
+    name === 'PLUGIN_ROOT' ? roots.pluginRoot : roots.pluginData
+  )
+}
+function within(path: string, root: string): boolean {
+  const suffix = relative(root, path)
+  return suffix === '' || (suffix !== '..' && !suffix.startsWith(`..${sep}`) && !isAbsolute(suffix))
+}
+export type McpBinding =
+  | {
+      type: 'stdio'
+      command: string
+      args: string[]
+      cwd: string
+      env: Record<string, string>
+      shell: false
+    }
+  | {
+      type: 'streamable-http' | 'sse'
+      url: string
+      headers: Record<string, string>
+      redirectPolicy: 'same-origin'
+      authorization: 'control-plane'
+    }
+
+/** Produce concrete Control Plane launch/connect descriptors, without launching or connecting. */
+export function resolveMcpBinding(
+  input: McpServer,
+  roots: RuntimeRoots,
+  baseEnv: Readonly<Record<string, string>> = {},
+  platform: 'posix' | 'win32' = process.platform === 'win32' ? 'win32' : 'posix'
+): McpBinding {
+  const server = validateServer(input)
+  if (!isAbsolute(roots.pluginRoot) || !isAbsolute(roots.pluginData))
+    throw new Error('Runtime plugin roots must be absolute paths.')
+  if (server.type !== 'stdio')
+    return {
+      type: server.type,
+      url: server.url,
+      headers: { ...server.headers },
+      redirectPolicy: 'same-origin',
+      authorization: 'control-plane',
+    }
+  const command = server.command.startsWith('./')
+    ? resolve(roots.pluginRoot, server.command)
+    : server.command
+  if (server.command.startsWith('./') && !within(command, roots.pluginRoot))
+    throw new Error('Executable escapes the plugin root.')
+  const cwdInput = server.cwd ?? '${PLUGIN_ROOT}'
+  const cwdRoot = cwdInput.startsWith('${PLUGIN_DATA}') ? roots.pluginData : roots.pluginRoot
+  const expanded = expandPluginPaths(cwdInput, roots)
+  const cwd = resolve(roots.pluginRoot, expanded)
+  if (!within(cwd, cwdRoot)) throw new Error('Working directory escapes its declared root.')
+  const env: Record<string, string> = {}
+  const overlay = (name: string, value: string): void => {
+    if (platform === 'win32')
+      for (const existing of Object.keys(env))
+        if (existing.toUpperCase() === name.toUpperCase()) delete env[existing]
+    Object.defineProperty(env, name, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    })
+  }
+  for (const [key, value] of Object.entries(baseEnv)) overlay(key, value)
+  for (const [key, value] of Object.entries(server.env ?? {}))
+    overlay(key, expandPluginPaths(value, roots))
+  overlay('PLUGIN_ROOT', roots.pluginRoot)
+  overlay('PLUGIN_DATA', roots.pluginData)
+  return {
+    type: 'stdio',
+    command,
+    args: (server.args ?? []).map((arg) => expandPluginPaths(arg, roots)),
+    cwd,
+    env,
+    shell: false,
+  }
+}
+
+/** Mandatory filesystem preflight for Control Plane callers after safe materialization.
+ * Call immediately before activation inside the same protected installation boundary;
+ * a separate preflight is not a substitute for preventing concurrent filesystem mutation.
+ */
+export async function verifyBindingPaths(input: McpServer, roots: RuntimeRoots): Promise<void> {
+  const binding = resolveMcpBinding(input, roots)
+  if (binding.type !== 'stdio' || input.type !== 'stdio') return
+  const root = await realpath(roots.pluginRoot)
+  const data = await realpath(roots.pluginData)
+  if (root !== roots.pluginRoot || data !== roots.pluginData)
+    throw new Error('Supply canonical filesystem-resolved runtime roots.')
+  const cwd = await realpath(binding.cwd)
+  const expected = input.cwd?.startsWith('${PLUGIN_DATA}') ? data : root
+  if (!within(cwd, expected))
+    throw new Error('Working directory resolves outside its declared root.')
+  if (input.command.startsWith('./') && !within(await realpath(binding.command), root))
+    throw new Error('Executable resolves outside the package root.')
+}

package/src/agent-plugins-schema.test.ts

@@ -0,0 +1,27 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { z } from 'zod'
+import {
+  AgentPackageSchema,
+  HarnessProfileSchema,
+  InstallationPlanSchema,
+} from './agent-plugins-schema.js'
+
+// Run test commands from the repository root, like the repository's Bun scripts.
+for (const [name, schema] of [
+  ['agent-package.v1', AgentPackageSchema],
+  ['harness-profile.v1', HarnessProfileSchema],
+  ['installation-plan.v2', InstallationPlanSchema],
+] as const) {
+  it(`keeps ${name} JSON Schema synchronized with the runtime contract`, async () => {
+    const artifact = JSON.parse(
+      await readFile(join(process.cwd(), 'schemas', `${name}.json`), 'utf8')
+    )
+    assert.deepEqual(artifact, {
+      ...z.toJSONSchema(schema, { target: 'draft-2020-12' }),
+      $id: `https://adea.dev/schemas/plugins/${name}.json`,
+    })
+  })
+}