fix(adapters): pin the cliBin layout to bin/.mjs at registration; changeset PR reference

Codex review on #419: check the supported-`cli`-without-layout invariant
before the empty-layout early return, reject a `cliBin` layout that names
any directory but `bin` or omits `.mjs` (the compiler emits the routed CLI
only there), and end the changeset summary with the PR reference.

Author: ScriptedAlchemy

.changeset/387-artifact-routed-cli.md

@@ -2,17 +2,15 @@
 "agent-bundle": minor
 ---
 
-Emit the routed CLI (`src/cli/**`) into host artifacts, not only the npm
-package build. Every target whose adapter publishes the new `cli` capability
-(all built-in targets: `claude`, `codex`, `cursor`, `portable`, `plugin`)
-now receives `bin/<plugin-name>.mjs` — the same compiled command graph as
-`dist/bin/<plugin-name>.js`, run as `node <plugin-root>/bin/<plugin-name>.mjs`
-— plus `bin/<plugin-name>-flight.mjs` when any command renders, so installed
-skills, hooks, and script routes can invoke the CLI without a separate npm
-install. Script routes reach it as the `../bin/<plugin-name>.mjs` sibling of
-their own `import.meta.url`; skills and hooks reach it through the plugin-root
-token. The artifact manifest, validation (`cliBin` layout), `inspect`
-component accounting (`cli` kind), and `inspect --bundler` all know the new
-`bin/` directory. A target without the capability omits the bin and reports
-`AB4765`; a host-emitted file colliding with the bin path is `AB4766`. The
-package build's own bin emission is unchanged.
+Emit the routed CLI (`src/cli/**`) into every host artifact as
+`<target>/bin/<plugin-name>.mjs` (plus `bin/<plugin-name>-flight.mjs` when a
+command renders), not only into the npm package build, so installed skills,
+hooks, and script routes can run it with `node <plugin-root>/bin/<plugin-name>.mjs`.
+Every built-in target publishes the new `cli` adapter capability that admits
+the bin; `inspect` accounts for it as a `cli` component, `inspect --bundler`
+and the artifact manifest list it, and artifact validation admits the `cliBin`
+layout. A target without the capability omits the bin with `AB4765`; a
+host-emitted file colliding with the bin path fails the build with `AB4766`.
+Script routes reach the bin as their `../bin/<plugin-name>.mjs` sibling;
+skills and hooks reach it through the plugin-root token. The package build's
+`dist/bin/<plugin-name>.js` is unchanged. (#419)

docs/entry-conventions.md

@@ -433,8 +433,10 @@ or skipped with the host's `cli` capability judgment), `inspect --bundler`
 dumps each target's `bin/` composition beside its scripts, and the artifact
 manifest records both files with `bundle` provenance naming every command
 route. Artifact validation admits the `bin/` layout only for adapters that
-declare it (`cliBin`); an adapter that publishes a supported `cli` capability
-without that layout is rejected at registration. A target without the
+declare it (`cliBin`); because the compiler emits the CLI at exactly
+`bin/<plugin-name>.mjs`, an adapter that publishes a supported `cli`
+capability without that layout, or with a `cliBin` layout naming another
+directory or omitting `.mjs`, is rejected at registration. A target without the
 capability omits the bin and reports `AB4765`; a host-emitted file at the
 same path (a Claude `claude.bin` directory shipping `<plugin-name>.mjs`) is
 `AB4766`. The package build's `dist/bin/<plugin-name>.js` is unchanged.

packages/agent-bundle/src/adapters/portable.ts

@@ -37,6 +37,7 @@ import pluginSchema from './schemas/portable/plugin.schema.json' with { type: 'j
 import {
   createAdapterValidator,
   payloadCopyEntries,
+  routedCliBinLayout,
   schemaDescriptorsFrom,
   sourceInputs,
   validateJsonSchemaDocument,
@@ -610,7 +611,7 @@ export const portableAdapter: TargetAdapter = Object.freeze({
   artifactValidation,
   artifactLayout: Object.freeze({
     assets: 'assets',
-    cliBin: Object.freeze({ allowedSuffixes: Object.freeze(['.mjs']), directory: 'bin' }),
+    cliBin: routedCliBinLayout,
     mcpApps: Object.freeze({ allowedSuffixes: Object.freeze(['.html']), directory: 'mcp-apps' }),
     mcpEntries: Object.freeze({ allowedSuffixes: Object.freeze(['.mjs']), directory: 'mcp' }),
     rootDocuments: Object.freeze(['INSTALL.md', 'install.mjs']),

packages/agent-bundle/src/adapters/registry.ts

@@ -16,16 +16,17 @@ import { cursorAdapter } from './cursor.ts';
 import { readStandardNativeHookCommands, type TargetHookContract } from './hook-contract.ts';
 import { portableAdapter } from './portable.ts';
 import { pluginAdapter } from './plugin.ts';
-import type {
-  TargetAdapter,
-  TargetArtifactDocumentContract,
-  TargetArtifactDocumentValidator,
-  TargetArtifactLayout,
-  TargetArtifactOutputLayout,
-  TargetArtifactSchemaContract,
-  TargetArtifactValidationContract,
-  TargetAdapterMetadata,
-  TargetSchemaDescriptor,
+import {
+  routedCliBinLayout,
+  type TargetAdapter,
+  type TargetArtifactDocumentContract,
+  type TargetArtifactDocumentValidator,
+  type TargetArtifactLayout,
+  type TargetArtifactOutputLayout,
+  type TargetArtifactSchemaContract,
+  type TargetArtifactValidationContract,
+  type TargetAdapterMetadata,
+  type TargetSchemaDescriptor,
 } from './types.ts';
 import type { TargetMcpRuntimeContract } from '../services/mcp-runtime.ts';
 import { deepFreeze } from '../core/freeze.ts';
@@ -181,12 +182,31 @@ const snapshotArtifactLayout = (
   hookContract: TargetHookContract | undefined,
   mcpRuntime: TargetMcpRuntimeContract | undefined,
 ): TargetArtifactLayout => {
+  // A supported `cli` capability promises a home for the compiled routed CLI,
+  // and the compiler emits it at exactly one place (`bin/<name>.mjs`), so the
+  // promise is checked before any early return and against that fixed layout.
+  const cliSupported = capabilityIsSupported(adapter.capabilities[cliBinCapability]);
+  const missingCliBinLayout = (): Error =>
+    new Error(`Target adapter "${adapter.name}" declares a supported ${cliBinCapability} capability without a routed CLI bin layout.`);
   const declaredLayout = adapter.artifactLayout;
-  if (declaredLayout === undefined) return emptyArtifactLayout;
+  if (declaredLayout === undefined) {
+    if (cliSupported) throw missingCliBinLayout();
+    return emptyArtifactLayout;
+  }
   const layout = record(declaredLayout);
   if (layout === undefined) throw new Error('Target adapter artifact layout must be a record.');
 
   const cliBin = layout.cliBin === undefined ? undefined : snapshotOutputLayout(layout.cliBin, 'routed CLI bin');
+  if (cliBin === undefined && cliSupported) throw missingCliBinLayout();
+  if (
+    cliBin !== undefined &&
+    (cliBin.directory !== routedCliBinLayout.directory ||
+      !routedCliBinLayout.allowedSuffixes.every((suffix) => cliBin.allowedSuffixes.includes(suffix)))
+  ) {
+    throw new Error(
+      `Target adapter "${adapter.name}" routed CLI bin layout must use directory ${JSON.stringify(routedCliBinLayout.directory)} and admit ${routedCliBinLayout.allowedSuffixes.map((suffix) => JSON.stringify(suffix)).join(', ')}; the compiler emits the routed CLI only there.`,
+    );
+  }
   const commands = layout.commands === undefined ? undefined : snapshotOutputLayout(layout.commands, 'commands');
   const hookWrappers = layout.hookWrappers === undefined
     ? undefined
@@ -235,9 +255,6 @@ const snapshotArtifactLayout = (
   if (skills !== undefined && !capabilityIsSupported(adapter.capabilities.skills)) {
     throw new Error(`Target adapter "${adapter.name}" declares Skill layout without skills capability.`);
   }
-  if (cliBin === undefined && capabilityIsSupported(adapter.capabilities[cliBinCapability])) {
-    throw new Error(`Target adapter "${adapter.name}" declares a supported ${cliBinCapability} capability without a routed CLI bin layout.`);
-  }
   return Object.freeze({
     ...(assets === undefined ? {} : { assets }),
     ...(bin === undefined ? {} : { bin }),

packages/agent-bundle/src/adapters/types.ts

@@ -435,14 +435,27 @@ export interface TargetArtifactLayout {
   readonly workflows?: string;
 }
 
+/**
+ * The one layout the compiler emits the routed CLI into (#387):
+ * `bin/<plugin-name>.mjs` plus `bin/<plugin-name>-flight.mjs`. Every adapter
+ * that publishes a supported `cli` capability must declare a `cliBin` layout
+ * naming this directory and admitting this suffix; the registry rejects any
+ * other spelling because the compiler would otherwise emit files its own
+ * artifact validation rejects.
+ */
+export const routedCliBinLayout: TargetArtifactOutputLayout = Object.freeze({
+  allowedSuffixes: Object.freeze(['.mjs']),
+  directory: 'bin',
+});
+
 /**
  * Direct-file artifact layout shared by every plugin-shaped target adapter
  * (Claude, Codex): hook wrappers, MCP apps/entries, scripts, and skills all
  * land in the same target-agnostic directories with the same suffix policy.
  */
 export const standardArtifactLayout: TargetArtifactLayout = Object.freeze({
   assets: 'assets',
-  cliBin: Object.freeze({ allowedSuffixes: Object.freeze(['.mjs']), directory: 'bin' }),
+  cliBin: routedCliBinLayout,
   hookWrappers: Object.freeze({ allowedSuffixes: Object.freeze(['.mjs']), directory: 'hooks' }),
   mcpApps: Object.freeze({ allowedSuffixes: Object.freeze(['.html']), directory: 'mcp-apps' }),
   mcpEntries: Object.freeze({ allowedSuffixes: Object.freeze(['.mjs']), directory: 'mcp' }),

packages/agent-bundle/src/build/cli-bins.ts

@@ -2,7 +2,7 @@ import { resolve } from 'node:path';
 
 import { cliBinCapability } from '../adapters/capability-state.ts';
 import type { TargetRegistry } from '../adapters/registry.ts';
-import type { TargetArtifactEntry } from '../adapters/types.ts';
+import { routedCliBinLayout, type TargetArtifactEntry } from '../adapters/types.ts';
 import type { Diagnostic } from '../core/diagnostics.ts';
 import type { AgentBundleToolsConfig, NormalizedBinEntry, NormalizedPlugin } from '../core/types.ts';
 import type { AgentBundleMeta } from '../meta.ts';
@@ -28,7 +28,8 @@ import { buildWithRslib, type RslibEntry } from './rslib.ts';
  * separate npm install. The package build's own bin emission is untouched.
  */
 
-export const cliBinDirectory = 'bin';
+/** The one directory the compiler emits the routed CLI into; the registry pins every `cliBin` layout to it. */
+export const cliBinDirectory: string = routedCliBinLayout.directory;
 
 /** The artifact-relative executable path for one routed-CLI bin. */
 export const cliBinArtifactPath = (name: string): string => `${cliBinDirectory}/${name}.mjs`;

packages/agent-bundle/tests/adapter-capability-states.test.ts

@@ -906,18 +906,38 @@ it('publishes the routed CLI bin capability with its bin layout on every built-i
   }
 
   // A supported `cli` row promises a place for the executable, so an adapter
-  // without the layout cannot register; one that publishes no row stays valid
-  // and simply hosts no bin.
+  // without the layout — or with no artifact layout at all — cannot register;
+  // one that publishes no row stays valid and simply hosts no bin.
   const cursor = registry.get('cursor');
   const { cliBin: _cliBin, ...layoutWithoutBin } = cursor.artifactLayout!;
   expect(() => new TargetRegistry().register({ ...cursor, artifactLayout: layoutWithoutBin }))
     .toThrow(/supported cli capability without a routed CLI bin layout/u);
+  const { artifactLayout: _layout, ...cursorWithoutLayout } = cursor;
+  expect(() => new TargetRegistry().register(cursorWithoutLayout))
+    .toThrow(/supported cli capability without a routed CLI bin layout/u);
   const { cli: _cli, ...capabilitiesWithoutCli } = cursor.capabilities;
   expect(() => new TargetRegistry().register({
     ...cursor,
     artifactLayout: layoutWithoutBin,
     capabilities: capabilitiesWithoutCli,
   })).not.toThrow();
+
+  // The compiler emits the routed CLI at exactly `bin/<name>.mjs`, so a
+  // `cliBin` layout naming any other directory or omitting `.mjs` is rejected
+  // instead of producing files artifact validation would reject.
+  for (const cliBin of [
+    { allowedSuffixes: ['.mjs'], directory: 'cli' },
+    { allowedSuffixes: ['.js'], directory: 'bin' },
+  ]) {
+    expect(() => new TargetRegistry().register({
+      ...cursor,
+      artifactLayout: { ...layoutWithoutBin, cliBin },
+    })).toThrow(/routed CLI bin layout must use directory "bin" and admit "\.mjs"/u);
+  }
+  expect(() => new TargetRegistry().register({
+    ...cursor,
+    artifactLayout: { ...layoutWithoutBin, cliBin: { allowedSuffixes: ['.js', '.mjs'], directory: 'bin' } },
+  })).not.toThrow();
 });
 
 it('rejects a malformed inspection component capability when the adapter registers', () => {