@agent-relay/cli-surface 12.2.2 → 12.2.4

package/dist/compose.d.ts

@@ -0,0 +1,35 @@
+import { type RelayCliSurface } from './types.js';
+/** Inputs for {@link composeSurfaces}. */
+export interface ComposeSurfacesOptions {
+    /** Identifier for the combined surface, e.g. `relayhistory`. */
+    id: string;
+    /** Version reported for the combined surface. */
+    version: string;
+    /**
+     * Surfaces to merge, in precedence order for error messages.
+     *
+     * Their top-level command names must be disjoint: two parts claiming the same
+     * name would make dispatch ambiguous, and silently picking one would route
+     * some invocations to the wrong implementation.
+     */
+    parts: readonly RelayCliSurface[];
+}
+/**
+ * Merge several surfaces into one command tree.
+ *
+ * `agent-relay sessions` spans local history (`ai-hist`), a cloud client, and
+ * Relay's own session replay. Presenting those as three mounted groups would
+ * leak our package boundaries into the user's command line; composing them
+ * keeps one coherent tree while each half stays owned by its repo.
+ *
+ * Dispatch routes on the first token: the part that declared that top-level
+ * command receives the full argv unchanged, so a part cannot tell whether it
+ * was composed or mounted directly.
+ *
+ * @param options - Combined identity and the parts to merge.
+ * @returns A surface whose commands are the concatenation of its parts'.
+ * @throws When two parts claim the same top-level name (as a command or an
+ *   alias), or when a part does not itself conform to the contract.
+ */
+export declare function composeSurfaces(options: ComposeSurfacesOptions): RelayCliSurface;
+//# sourceMappingURL=compose.d.ts.map

package/dist/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAEpB,0CAA0C;AAC1C,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAoDhF"}

package/dist/compose.js

@@ -0,0 +1,62 @@
+import { assertSurfaceConforms } from './conformance.js';
+import { RELAY_CLI_CONTRACT_VERSION, } from './types.js';
+/**
+ * Merge several surfaces into one command tree.
+ *
+ * `agent-relay sessions` spans local history (`ai-hist`), a cloud client, and
+ * Relay's own session replay. Presenting those as three mounted groups would
+ * leak our package boundaries into the user's command line; composing them
+ * keeps one coherent tree while each half stays owned by its repo.
+ *
+ * Dispatch routes on the first token: the part that declared that top-level
+ * command receives the full argv unchanged, so a part cannot tell whether it
+ * was composed or mounted directly.
+ *
+ * @param options - Combined identity and the parts to merge.
+ * @returns A surface whose commands are the concatenation of its parts'.
+ * @throws When two parts claim the same top-level name (as a command or an
+ *   alias), or when a part does not itself conform to the contract.
+ */
+export function composeSurfaces(options) {
+    const owners = new Map();
+    const commands = [];
+    const claim = (name, kind, part) => {
+        const existing = owners.get(name);
+        if (existing) {
+            const describe = (c) => `${c.kind} '${name}' from '${c.surface.id}'`;
+            throw new Error(`cannot compose surface '${options.id}': ${describe({ surface: part, kind })} ` +
+                `collides with ${describe(existing)}`);
+        }
+        owners.set(name, { surface: part, kind });
+    };
+    for (const part of options.parts) {
+        // Catch a malformed part here rather than at first invocation: a composed
+        // surface is usually built at mount time, so this fails fast and names the
+        // offending part.
+        assertSurfaceConforms(part);
+        for (const command of part.commands) {
+            claim(command.name, 'command', part);
+            for (const alias of command.aliases ?? [])
+                claim(alias, 'alias', part);
+            commands.push(command);
+        }
+    }
+    return {
+        id: options.id,
+        version: options.version,
+        contract: RELAY_CLI_CONTRACT_VERSION,
+        commands,
+        async run(argv, io) {
+            const first = argv[0];
+            const owner = first === undefined ? undefined : owners.get(first)?.surface;
+            if (!owner) {
+                // The host renders help and unknown-command errors from `commands`, so
+                // reaching here means it dispatched something the spec does not cover.
+                io.stderr(`error: '${first ?? ''}' is not a command of ${options.id}\n`);
+                return 2;
+            }
+            return owner.run(argv, io);
+        },
+    };
+}
+//# sourceMappingURL=compose.js.map

package/dist/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EACL,0BAA0B,GAI3B,MAAM,YAAY,CAAC;AAkBpB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAO7D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAC;IACxC,MAAM,QAAQ,GAA0B,EAAE,CAAC;IAE3C,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,IAAmB,EAAE,IAAqB,EAAQ,EAAE;QAC/E,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,QAAQ,GAAG,CAAC,CAAQ,EAAU,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,IAAI,WAAW,CAAC,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC;YACpF,MAAM,IAAI,KAAK,CACb,2BAA2B,OAAO,CAAC,EAAE,MAAM,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,GAAG;gBAC7E,iBAAiB,QAAQ,CAAC,QAAQ,CAAC,EAAE,CACxC,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACjC,0EAA0E;QAC1E,2EAA2E;QAC3E,kBAAkB;QAClB,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAE5B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;YACrC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,OAAO,IAAI,EAAE;gBAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;YACvE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,QAAQ,EAAE,0BAA0B;QACpC,QAAQ;QACR,KAAK,CAAC,GAAG,CAAC,IAAuB,EAAE,EAAc;YAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YACtB,MAAM,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;YAC3E,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,uEAAuE;gBACvE,uEAAuE;gBACvE,EAAE,CAAC,MAAM,CAAC,WAAW,KAAK,IAAI,EAAE,yBAAyB,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;gBACzE,OAAO,CAAC,CAAC;YACX,CAAC;YACD,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/conformance.d.ts

@@ -0,0 +1,37 @@
+import { type RelayCliCommandSpec, type RelayCliSurface } from './types.js';
+/** Exit code a surface returns when it cannot route the given argv. */
+export declare const RELAY_CLI_EXIT_UNKNOWN_COMMAND = 2;
+/** A conformance problem found in a surface. */
+export interface RelayCliSurfaceViolation {
+    /** Dotted path to the offending node, e.g. `commands.run.options[0]`. */
+    path: string;
+    message: string;
+}
+/**
+ * Check a surface against the structural rules in the contract.
+ *
+ * This validates the declared shape only. Each product repo pairs it with a
+ * drift test proving `commands` and `run` dispatch the same tree.
+ *
+ * @param surface - The surface to check.
+ * @returns Every violation found; empty when the surface conforms.
+ */
+export declare function findSurfaceViolations(surface: RelayCliSurface): RelayCliSurfaceViolation[];
+/**
+ * Throw unless the surface conforms to the contract.
+ *
+ * @param surface - The surface to check.
+ * @throws When any violation is found; the message lists all of them.
+ */
+export declare function assertSurfaceConforms(surface: RelayCliSurface): void;
+/**
+ * Walk every command in a surface, deepest-last, with its invocation path.
+ *
+ * @param commands - The command tree to walk.
+ * @returns Each command paired with the argv path that reaches it.
+ */
+export declare function walkCommands(commands: readonly RelayCliCommandSpec[], prefix?: readonly string[]): Generator<{
+    path: readonly string[];
+    command: RelayCliCommandSpec;
+}>;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAExG,uEAAuE;AACvE,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,gDAAgD;AAChD,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAkED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,wBAAwB,EAAE,CAyB1F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAKpE;AAED;;;;;GAKG;AACH,wBAAiB,YAAY,CAC3B,QAAQ,EAAE,SAAS,mBAAmB,EAAE,EACxC,MAAM,GAAE,SAAS,MAAM,EAAO,GAC7B,SAAS,CAAC;IAAE,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAMtE"}

package/dist/conformance.js

@@ -0,0 +1,118 @@
+import { RELAY_CLI_CONTRACT_VERSION } from './types.js';
+/** Exit code a surface returns when it cannot route the given argv. */
+export const RELAY_CLI_EXIT_UNKNOWN_COMMAND = 2;
+const FLAG_PATTERN = /^(-[A-Za-z0-9], )?--[a-z0-9][a-z0-9-]*( [<[][^>\]]+[>\]])?$/;
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+function checkCommand(command, path, seen, violations) {
+    if (!NAME_PATTERN.test(command.name)) {
+        violations.push({
+            path: `${path}.name`,
+            message: `command name ${JSON.stringify(command.name)} must be lowercase kebab-case`,
+        });
+    }
+    if (seen.has(command.name)) {
+        violations.push({ path: `${path}.name`, message: `duplicate command name ${command.name}` });
+    }
+    seen.add(command.name);
+    if (!command.description.trim()) {
+        violations.push({ path: `${path}.description`, message: 'description must not be empty' });
+    }
+    let sawOptional = false;
+    command.args?.forEach((arg, index) => {
+        // Commander cannot express a required positional after an optional one, and
+        // a variadic must be last or it swallows its successors.
+        if (arg.required && sawOptional) {
+            violations.push({
+                path: `${path}.args[${index}]`,
+                message: `required arg ${arg.name} cannot follow an optional arg`,
+            });
+        }
+        if (!arg.required)
+            sawOptional = true;
+        if (arg.variadic && index !== (command.args?.length ?? 0) - 1) {
+            violations.push({
+                path: `${path}.args[${index}]`,
+                message: `variadic arg ${arg.name} must be the last positional`,
+            });
+        }
+    });
+    const flags = new Set();
+    command.options?.forEach((option, index) => {
+        if (!FLAG_PATTERN.test(option.flags)) {
+            violations.push({
+                path: `${path}.options[${index}]`,
+                message: `flags ${JSON.stringify(option.flags)} is not a commander flag string`,
+            });
+        }
+        const long = option.flags.match(/--[a-z0-9][a-z0-9-]*/)?.[0];
+        if (long && flags.has(long)) {
+            violations.push({ path: `${path}.options[${index}]`, message: `duplicate flag ${long}` });
+        }
+        if (long)
+            flags.add(long);
+    });
+    const childNames = new Set();
+    command.subcommands?.forEach((child) => {
+        checkCommand(child, `${path}.${child.name}`, childNames, violations);
+    });
+}
+/**
+ * Check a surface against the structural rules in the contract.
+ *
+ * This validates the declared shape only. Each product repo pairs it with a
+ * drift test proving `commands` and `run` dispatch the same tree.
+ *
+ * @param surface - The surface to check.
+ * @returns Every violation found; empty when the surface conforms.
+ */
+export function findSurfaceViolations(surface) {
+    const violations = [];
+    if (!NAME_PATTERN.test(surface.id)) {
+        violations.push({ path: 'id', message: `surface id ${JSON.stringify(surface.id)} must be kebab-case` });
+    }
+    if (!surface.version.trim()) {
+        violations.push({ path: 'version', message: 'version must not be empty' });
+    }
+    if (surface.contract !== RELAY_CLI_CONTRACT_VERSION) {
+        violations.push({
+            path: 'contract',
+            message: `contract ${String(surface.contract)} is not supported (expected ${RELAY_CLI_CONTRACT_VERSION})`,
+        });
+    }
+    if (surface.commands.length === 0) {
+        violations.push({ path: 'commands', message: 'surface declares no commands' });
+    }
+    const seen = new Set();
+    surface.commands.forEach((command) => {
+        checkCommand(command, `commands.${command.name}`, seen, violations);
+    });
+    return violations;
+}
+/**
+ * Throw unless the surface conforms to the contract.
+ *
+ * @param surface - The surface to check.
+ * @throws When any violation is found; the message lists all of them.
+ */
+export function assertSurfaceConforms(surface) {
+    const violations = findSurfaceViolations(surface);
+    if (violations.length === 0)
+        return;
+    const detail = violations.map((violation) => `  ${violation.path}: ${violation.message}`).join('\n');
+    throw new Error(`CLI surface ${surface.id} violates contract v${RELAY_CLI_CONTRACT_VERSION}:\n${detail}`);
+}
+/**
+ * Walk every command in a surface, deepest-last, with its invocation path.
+ *
+ * @param commands - The command tree to walk.
+ * @returns Each command paired with the argv path that reaches it.
+ */
+export function* walkCommands(commands, prefix = []) {
+    for (const command of commands) {
+        const path = [...prefix, command.name];
+        yield { path, command };
+        if (command.subcommands)
+            yield* walkCommands(command.subcommands, path);
+    }
+}
+//# sourceMappingURL=conformance.js.map

package/dist/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAkD,MAAM,YAAY,CAAC;AAExG,uEAAuE;AACvE,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAShD,MAAM,YAAY,GAAG,6DAA6D,CAAC;AACnF,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAE5C,SAAS,YAAY,CACnB,OAA4B,EAC5B,IAAY,EACZ,IAAiB,EACjB,UAAsC;IAEtC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,GAAG,IAAI,OAAO;YACpB,OAAO,EAAE,gBAAgB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,+BAA+B;SACrF,CAAC,CAAC;IACL,CAAC;IACD,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,IAAI,OAAO,EAAE,OAAO,EAAE,0BAA0B,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;QAChC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,IAAI,cAAc,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACnC,4EAA4E;QAC5E,yDAAyD;QACzD,IAAI,GAAG,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC;YAChC,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,GAAG,IAAI,SAAS,KAAK,GAAG;gBAC9B,OAAO,EAAE,gBAAgB,GAAG,CAAC,IAAI,gCAAgC;aAClE,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,QAAQ;YAAE,WAAW,GAAG,IAAI,CAAC;QACtC,IAAI,GAAG,CAAC,QAAQ,IAAI,KAAK,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9D,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,GAAG,IAAI,SAAS,KAAK,GAAG;gBAC9B,OAAO,EAAE,gBAAgB,GAAG,CAAC,IAAI,8BAA8B;aAChE,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;QACzC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACrC,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,GAAG,IAAI,YAAY,KAAK,GAAG;gBACjC,OAAO,EAAE,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC;aAChF,CAAC,CAAC;QACL,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7D,IAAI,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,IAAI,YAAY,KAAK,GAAG,EAAE,OAAO,EAAE,kBAAkB,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,IAAI;YAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QACrC,YAAY,CAAC,KAAK,EAAE,GAAG,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAwB;IAC5D,MAAM,UAAU,GAA+B,EAAE,CAAC;IAElD,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;QACnC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,qBAAqB,EAAE,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5B,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,2BAA2B,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,KAAK,0BAA0B,EAAE,CAAC;QACpD,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,YAAY,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,+BAA+B,0BAA0B,GAAG;SAC1G,CAAC,CAAC;IACL,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QACnC,YAAY,CAAC,OAAO,EAAE,YAAY,OAAO,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;IAEH,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAwB;IAC5D,MAAM,UAAU,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACpC,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,KAAK,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrG,MAAM,IAAI,KAAK,CAAC,eAAe,OAAO,CAAC,EAAE,uBAAuB,0BAA0B,MAAM,MAAM,EAAE,CAAC,CAAC;AAC5G,CAAC;AAED;;;;;GAKG;AACH,MAAM,SAAS,CAAC,CAAC,YAAY,CAC3B,QAAwC,EACxC,SAA4B,EAAE;IAE9B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QACxB,IAAI,OAAO,CAAC,WAAW;YAAE,KAAK,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './conformance.js';
+export * from './compose.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './conformance.js';
+export * from './compose.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Contract between the `agent-relay` CLI and the Relay product CLIs it mounts
+ * (`relayfile`, `relayflows`, `relayhistory`).
+ *
+ * A product repo implements {@link RelayCliSurface} and the host CLI mounts it
+ * generically. Command implementations live in the product repo and are never
+ * copied into `agent-relay`.
+ *
+ * The surface is structurally typed on purpose: a product package can satisfy
+ * it while depending on this package only as a devDependency, so mounting adds
+ * no runtime dependency on Relay to the product.
+ */
+/** Contract revision. Bumped only for a breaking change to these shapes. */
+export type RelayCliContractVersion = 1;
+/** Current contract revision. */
+export declare const RELAY_CLI_CONTRACT_VERSION: RelayCliContractVersion;
+/**
+ * Output sink supplied by the host. A surface writes here instead of touching
+ * `process.stdout` / `process.stderr` so the host can capture, prefix, or
+ * redirect product output.
+ *
+ * Chunks may be bytes as well as text. Some product commands stream binary to
+ * stdout — `relayfile export --format tar --output -` is the motivating case —
+ * and a string-only sink silently corrupts them, because the bytes round-trip
+ * through UTF-8 decoding. Passing a `Uint8Array` through untouched is the only
+ * way those commands survive being mounted.
+ *
+ * A product that only ever emits text can keep passing strings; nothing about
+ * the simple case changes.
+ */
+export interface RelayCliIo {
+    stdout(chunk: string | Uint8Array): void;
+    stderr(chunk: string | Uint8Array): void;
+}
+/** A positional argument in a product command. */
+export interface RelayCliArgSpec {
+    name: string;
+    description: string;
+    required: boolean;
+    variadic?: boolean;
+}
+/** A flag in a product command. */
+export interface RelayCliOptionSpec {
+    /** Commander-style flag string, e.g. `--json` or `-w, --workspace <id>`. */
+    flags: string;
+    description: string;
+    defaultValue?: string | boolean | number;
+}
+/** Marks a command as deprecated in favour of another. */
+export interface RelayCliDeprecation {
+    /** The command a caller should use instead, e.g. `agent-relay flows run`. */
+    replacement: string;
+    /** Version the deprecation started, when known. */
+    since?: string;
+}
+/** One node in a product command tree. */
+export interface RelayCliCommandSpec {
+    name: string;
+    description: string;
+    aliases?: readonly string[];
+    args?: readonly RelayCliArgSpec[];
+    options?: readonly RelayCliOptionSpec[];
+    subcommands?: readonly RelayCliCommandSpec[];
+    /** When present the host prints a deprecation notice naming the replacement. */
+    deprecated?: RelayCliDeprecation;
+    /** Runnable, but omitted from `--help`. */
+    hidden?: boolean;
+}
+/**
+ * A mountable product CLI.
+ *
+ * Implementations must satisfy the following, which the host relies on and the
+ * conformance helpers in this package check:
+ *
+ * - `run` resolves to a process exit code; it never calls `process.exit`.
+ * - `run` writes only through the supplied {@link RelayCliIo}.
+ * - `run` installs no global signal handlers.
+ * - `commands` describes the same tree `run` dispatches (see
+ *   `assertSurfaceSpecMatchesRouting` in each product repo's drift test).
+ * - An unknown command resolves to exit code {@link RELAY_CLI_EXIT_UNKNOWN_COMMAND}.
+ */
+export interface RelayCliSurface {
+    /** Stable identifier, e.g. `relayfile`. */
+    id: string;
+    /** Version of the package providing this surface. */
+    version: string;
+    contract: RelayCliContractVersion;
+    /** Full command tree; drives help, completions, and deprecation notices. */
+    commands: readonly RelayCliCommandSpec[];
+    /**
+     * Execute one invocation.
+     *
+     * @param argv - Arguments after the mounted group name. `agent-relay flows run a.ts`
+     *   arrives as `['run', 'a.ts']`.
+     * @param io - Host-supplied output sink.
+     * @returns The process exit code for this invocation.
+     */
+    run(argv: readonly string[], io: RelayCliIo): Promise<number>;
+}
+/** A surface module's default factory signature. */
+export type RelayCliSurfaceFactory<Options = unknown> = (options?: Options) => RelayCliSurface;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAExC,iCAAiC;AACjC,eAAO,MAAM,0BAA0B,EAAE,uBAA2B,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;IACzC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;CAC1C;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CAC1C;AAED,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAClC,OAAO,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC,WAAW,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC7C,gFAAgF;IAChF,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,2CAA2C;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,uBAAuB,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACzC;;;;;;;OAOG;IACH,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/D;AAED,oDAAoD;AACpD,MAAM,MAAM,sBAAsB,CAAC,OAAO,GAAG,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,eAAe,CAAC"}

package/dist/types.js

@@ -0,0 +1,15 @@
+/**
+ * Contract between the `agent-relay` CLI and the Relay product CLIs it mounts
+ * (`relayfile`, `relayflows`, `relayhistory`).
+ *
+ * A product repo implements {@link RelayCliSurface} and the host CLI mounts it
+ * generically. Command implementations live in the product repo and are never
+ * copied into `agent-relay`.
+ *
+ * The surface is structurally typed on purpose: a product package can satisfy
+ * it while depending on this package only as a devDependency, so mounting adds
+ * no runtime dependency on Relay to the product.
+ */
+/** Current contract revision. */
+export const RELAY_CLI_CONTRACT_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,iCAAiC;AACjC,MAAM,CAAC,MAAM,0BAA0B,GAA4B,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/cli-surface",
-  "version": "12.2.2",
+  "version": "12.2.4",
   "engines": {
     "node": ">=22.0.0"
   },
@@ -21,6 +21,7 @@
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
+    "prepack": "npm run build",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest"
   },