@farmslot/recipe-cli 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to `@farmslot/recipe-cli` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.7.0 - 2026-10-06
+
+- Add `createHarnessCli({ host, adapters, libraries, commands, help, beforeDispatch, catalog, adopt, configuredLibraries, replacedOptions })` to `@farmslot/recipe-cli/harness`, the generic front door a product harness presets. `main(argv)` returns `{ exitCode, exit }` and `run()` exits with it.
+  - It provides the grouped help (the host's intro, groups and footer, the `<PREFIX>_BIN` dev override line and the prepared-slot line), per-command `--help`, `-v/--version`, which prints the host's package version as one line (a host `package.json` without a version is a startup error), and `--version --verbose`, which adds `@farmslot/recipe-cli <version>` (one line when the host is recipe-cli itself).
+  - Each public command carries its `contract`, so the command list and the grammar can't drift apart. Hidden commands keep their private grammar.
+  - Order per invocation: `beforeDispatch` (unless the command sets `nudge: false`); help for no arguments; `raw` commands; the public grammar; `libraries.hydrate(--target)`; `ensureAdapterLoaded` for the adapter the command selects (`selectedAdapterId`), with the `--library` entries, the host's `configuredLibraries()` and `adopt`, and the environment the operator started the command with (libraries that `libraries.hydrate` adds never load plugins) (a refused plugin, `AdapterPluginError` or the import fence's `RECIPE_SOURCE_INVALID`, prints its code and next step, or the NDJSON `error` and `complete` events under `--json-stream`, exit 2); `--help` after `--` handed to the command; `call <action> --help` through the `catalog`; commander.
+  - One error mapper: a command that throws exits with the error's `exitCode` (a `CliError`), else 1. A public command sets `process.exitCode` by default and a hidden one exits at once; `exit` overrides either.
+- Add the public command contract to `@farmslot/recipe-cli/harness`: `validatePublicInvocation(argv, commands, { replacedOptions })` returns a stable `CLI_*` usage error naming the host, or null.
+  - Option builders: `booleanOption`, `valueOption`, `optionalValueOption`, `contractOptions`. `OptionSpec.choices` can be a function of the tokens after the command, read at validation time (for example `(tokens) => adapterChoices(optionValues(tokens, '--library'))`). `optionValues(tokens, option)` returns every value an option takes before `--`.
+  - Command hooks: `bypass` (a sub-grammar another tool checks), `refine` (command rules, given `ContractFailures`) and `missingPositionalAction`.
+  - `publicCommandTokens(commands)` lists every name and alias.
+- Publish with adapter-sdk 0.5.1, agent-runtime 0.17.0, protocol 0.34.0 and recipe-runner 0.26.0.
+
+## 0.6.0 - 2026-10-06
+
+- **BREAKING:** a run plans with a runner that has no trusted mutation. `createRunner` no longer receives the mutation `trustedMutation.load` returned for the runner that computes the plan; only the mutation `authorize` returns reaches a runner. A host whose runner reads `options.trustedMutation` during construction or preflight now sees `undefined` there; move that check to `authorize`, which receives the loaded mutation and the plan.
+- `RecipeEngine.trustedMutation` hooks receive the adapter the command resolved (`--adapter`, a `--platform` target, or the detected one): `load` gets an `adapter` field, and `authorize` a third argument `{ adapter }`. Both input types are exported from `@farmslot/recipe-cli/harness` as `TrustedMutationLoadInput` and `TrustedMutationAuthorizeContext`, so a host can gate a mutation on the platform without resolving the adapter again.
+  - `authorize`'s third argument is required in the type: a host that calls `engine.trustedMutation.authorize(base, plan)` itself must pass `{ adapter }`. An implementation that declares two parameters still type-checks.
+  - `authorize` may return `undefined`: nothing to bind for this plan. The run then keeps the runner it planned with and executes with no trusted mutation, instead of building a second runner.
+- `run` with a task dir (`RECIPE_TASK_DIR` / `FARMSLOT_TASK_DIR`) writes the task's acceptance ledger, `artifacts/acceptance-status.json` (ADR-060), from the recipe's `proofTargets`, through agent-runtime's ledger module, the one `farmslot-agent ac` uses. A target is `proven` when every node proving it passed and `missing` when one failed or did not run; `AC1` maps to the handoff's `AC-1`. Evidence is the run's `trace.json` plus the proving nodes' artifacts inside the task dir. `AC1` and `AC-1` targets count as one criterion. The run replaces the verdicts of the criteria it proves and leaves the others as they were. A target the handoff doesn't list is refused with a warning on stderr; the run's result and JSON output are unchanged.
+- Static validation (`run --plan`, `validateRunRecipeStatic`) warns on two `command` node patterns whose exit code cannot prove the claim: output piped into `tail` or `head` (`recipe.command_pipe_masks_exit`; the shell reports tail's exit code, so a failing command passes), and a test command with no `assert_output` on it (`recipe.test_command_exit_code_only`; `jest -t` exits 0 when no test matches). `validateCommandNodes` is exported from `@farmslot/recipe-cli/harness`.
+- Add adapter plugins to `@farmslot/recipe-cli/harness`: `ensureAdapterLoaded(id, { libraries, adopt })` loads an adapter a recipe library declares in `recipe-library.json` `adapters` when a command selects it, composes it on the adapter it `extends` (`composeAdapter`: the child's members replace the parent's; manifests, in-code action implementations and doctor checks append) and registers it with the host's adapters. `adapterChoices(libraries)` lists every id `--adapter` accepts without importing anything. A refused plugin throws `AdapterPluginError` with `ADAPTER_SDK_UNSUPPORTED`, `ADAPTER_PLUGIN_INVALID`, `ADAPTER_PLUGIN_LOAD_FAILED`, `ADAPTER_ID_CONFLICT` or `ADAPTER_EXTENDS_UNKNOWN`; `adapterSelectionFailureOut` prints it, or the library reader's `RECIPE_SOURCE_INVALID`, as the `--json` envelope.
+  - Plugins load only from the operator's libraries: `--library` entries, then the `RECIPE_LIBRARY_PATH` entries they don't rename (else the personal library), then the libraries the host passes as `configured`; never from a task-local library. A host that extends `RECIPE_LIBRARY_PATH` with libraries it discovers passes the operator's environment as `env` to both `adapterChoices` and `ensureAdapterLoaded`.
+  - A plugin may import from disk only the files its digest covers (its module's directory and the library's `actions/`): a `module.registerHooks` resolve hook refuses any other file with `RECIPE_SOURCE_INVALID`, while the plugin loads and while it runs. Plugin code is the module's directory plus the `actions/` files it reaches; an `actions/` file the host imports by itself isn't fenced. `node:` builtins are allowed, and a bare package resolves from the host's install (`HarnessHost.packageRoot`), never from the library's location; a package the host doesn't install, or one in a `node_modules` beside or above the library that isn't on the host's own lookup chain, is refused (a library in the host's project imports the host's packages). Loading a plugin needs Node.js 22.15 or later (`ADAPTER_PLUGIN_LOAD_FAILED` otherwise).
+  - `adapterPlugin(id)` and `loadedAdapterPlugins()` describe each loaded plugin (`LoadedAdapterPlugin`: library, root, module, `extends`, and a `digest` over its library, the files under its module's directory and its parent plugin's digest), so a host can bind the actions the plugin ships in code to what a recipe approves. `adapterPluginChecks()` gives `doctor` one check per loaded plugin naming its library and digest.
+  - Live action scripts follow the adapter's `extends` chain: every file of an adapter that extends another (`<actions>/<child>/<family>/<name>.mjs`, its short name, its `<family>.mjs` dispatcher) comes before any of its parent's within each actions root, and the adapter at the top of the chain keeps a built-in's order with `shared/`. Built-in adapters, which extend nothing, try exactly the files they did before, in the same order. Recipe variants don't follow `extends`.
+  - `selectedAdapterId(tokens)` is the adapter a command selects, the way commands resolve it: the last `--adapter`, else the adapter of the last `--platform`. `declaredAdapterIds(sources)` reads the ids libraries declare without importing anything.
+- Export `resolveTsxBin(tsxCandidates, projectRoot)` from `@farmslot/recipe-cli/harness`, the tsx lookup live adapter scripts run under (`TSX_BIN`, the checkout's tsx, the host package's tsx, the caller's candidates), so a host's readiness check can ask the same question.
+- **BREAKING:** `runRecipe` and `preflightRecipe` no longer activate the run environment themselves; call them inside an `activateRecipeRuntimeEnvironment` scope.
+- `run` and `call` open one `activateRecipeRuntimeEnvironment` scope around preflight, the platform's `runtimeCheck`, the observers and the execution. All of them see the same ports (the slot's, then `--cdp-port`/`--watcher-port`) and the platform's run environment, and the scope restores the environment on every exit. Network and performance observers keep a copy of that environment taken as they start.
+- Publish with adapter-sdk 0.5.0, agent-runtime 0.17.0, protocol 0.34.0 and recipe-runner 0.25.0.
+
 ## 0.5.0 - 2026-10-05
 
 - Add `run` and `call` to `@farmslot/recipe-cli/harness`, moved from mm-harness: `handleRun(argv, options)`, `handleCall(argv, options)` and `handleCallHelp(argv, genericHelp, { catalog })`. The host passes a `RecipeEngine` (`RecipeCatalog`: its bundled library, action manifest resolver and validator, and bundled action risk; plus `createRunner`, an optional `trustedMutation` loaded from the command line and bound to the run's plan, the `console` classifier and `runnerIncludes`), and per command `targetDevice`, the `run --plan` host steps and launch wording, and `exampleAction`. `run --list`, `run <recipe> --describe` and `call --list` read the catalog themselves. Messages name the host (`<name> call`, `<product>-checkout`).

package/README.md

@@ -29,17 +29,17 @@ Docs: https://farmslot.io/docs/reference/recipe-discovery
 
 ## Source layout
 
-| path                                                | owns                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `src/cli.ts`                                        | the `farmslot-recipe` program: the runner's `run`/`validate` plus discovery                                                                                                                                                                                                                                                                                                                                                                                              |
-| `src/commands.ts`                                   | discovery command registration, JSON envelopes and errors                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `src/libraries.ts`                                  | library resolution: precedence, overrides, digests, `requires` checks                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `src/discovery-index.ts`                            | the recipe and action index for one platform view                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `src/composition.ts`                                | composition, callers and `explain`                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `src/search.ts`, `src/template.ts`, `src/render.ts` | search ranking, skeletons, text output                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `src/types.ts`                                      | the documented `--json` schema                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `src/harness/`                                      | generic harness support (`@farmslot/recipe-cli/harness`): host identity, adapter registry, runtime paths, journal, checkout lock, JSON stream, colour, option parsing, leaf spawning, bounded healing, run evidence (execution provenance, framed recording, run diagnostics, run report, live adapter scripts, run options, trust input, behavioral proof), and the run engine (`RecipeEngine`, recipe library, static validation, action catalog, network observation) |
-| `src/harness/commands/`                             | commands a host CLI dispatches to: `run`, `call`, the lifecycle (`launch`, `reload`, `stop`, `last`), and discovery (`discover.ts`: `actions`, `run --list`, `run --describe`, `call --list`); `overlay.ts` is `install`/`verify`/`cleanup`                                                                                                                                                                                                                              |
+| path                                                | owns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/cli.ts`                                        | the `farmslot-recipe` program: the runner's `run`/`validate` plus discovery                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `src/commands.ts`                                   | discovery command registration, JSON envelopes and errors                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `src/libraries.ts`                                  | library resolution: precedence, overrides, digests, `requires` checks                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `src/discovery-index.ts`                            | the recipe and action index for one platform view                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `src/composition.ts`                                | composition, callers and `explain`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `src/search.ts`, `src/template.ts`, `src/render.ts` | search ranking, skeletons, text output                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `src/types.ts`                                      | the documented `--json` schema                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `src/harness/`                                      | generic harness support (`@farmslot/recipe-cli/harness`): host identity, adapter registry and library adapter plugins, runtime paths, journal, checkout lock, JSON stream, colour, option parsing, leaf spawning, bounded healing, run evidence (execution provenance, framed recording, run diagnostics, run report, live adapter scripts, run options, trust input, behavioral proof), and the run engine (`RecipeEngine`, recipe library, static validation, action catalog, network observation) |
+| `src/harness/commands/`                             | commands a host CLI dispatches to: `run`, `call`, the lifecycle (`launch`, `reload`, `stop`, `last`), and discovery (`discover.ts`: `actions`, `run --list`, `run --describe`, `call --list`); `overlay.ts` is `install`/`verify`/`cleanup`                                                                                                                                                                                                                                                          |
 
 ## Maintenance rules
 

package/dist/harness/acceptance-ledger.d.ts

@@ -0,0 +1,18 @@
+export interface RecipeAcceptanceVerdict {
+    id: string;
+    verdict: 'proven' | 'missing';
+    recipeNodes: string[];
+    evidence: string[];
+}
+export interface RecipeAcceptanceRecord {
+    recorded: RecipeAcceptanceVerdict[];
+    /** Targets the ledger refused (e.g. no such criterion in the handoff), with why. */
+    refused: string[];
+}
+/** `AC1` and `AC-1` both name the handoff's first criterion; anything else is not an AC. */
+export declare function acceptanceIdForProofTarget(target: string): string | null;
+export declare function recordRecipeAcceptance(taskDir: string, target: string, result: {
+    recipePath: string;
+    tracePath: string;
+}): RecipeAcceptanceRecord;
+//# sourceMappingURL=acceptance-ledger.d.ts.map

package/dist/harness/acceptance-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceptance-ledger.d.ts","sourceRoot":"","sources":["../../src/harness/acceptance-ledger.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,uBAAuB,EAAE,CAAC;IACpC,oFAAoF;IACpF,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,4FAA4F;AAC5F,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGxE;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChD,sBAAsB,CA2DxB"}

package/dist/harness/acceptance-ledger.js

@@ -0,0 +1,119 @@
+// After a run with a task dir, the recipe's proof targets become verdicts in the
+// task's acceptance ledger (artifacts/acceptance-status.json, ADR-060), written by
+// the same code `farmslot-agent ac` uses, so a Farmslot run and a skill run record
+// the same file. A target is `proven` when every node proving it passed, `missing`
+// when one failed or did not run. A target no node proves, and a criterion no
+// target names, stay unrecorded: the run says nothing about them.
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { isRecord } from './parse-args.js';
+const require = createRequire(import.meta.url);
+const ledger = require('@farmslot/agent-runtime/scripts/acceptance-ledger.cjs');
+/** `AC1` and `AC-1` both name the handoff's first criterion; anything else is not an AC. */
+export function acceptanceIdForProofTarget(target) {
+    const match = /^AC-?([1-9][0-9]*)$/iu.exec(target.trim());
+    return match ? `AC-${match[1]}` : null;
+}
+export function recordRecipeAcceptance(taskDir, target, result) {
+    const record = { recorded: [], refused: [] };
+    if (ledger.handoffAcceptanceCriteria(taskDir).length === 0)
+        return record;
+    const recipe = readJson(result.recipePath);
+    const trace = readJson(result.tracePath);
+    // The protocol allows a bare array of entries or `{ entries }`.
+    const entries = Array.isArray(trace)
+        ? trace
+        : isRecord(trace) && Array.isArray(trace.entries)
+            ? trace.entries
+            : [];
+    // The last entry per node is its outcome (a retried node may appear twice).
+    const outcome = new Map();
+    for (const entry of entries) {
+        if (isRecord(entry) && typeof entry.nodeId === 'string')
+            outcome.set(entry.nodeId, entry);
+    }
+    const workflow = isRecord(recipe) && isRecord(recipe.workflow) ? recipe.workflow : {};
+    const nodes = isRecord(workflow.nodes) ? workflow.nodes : {};
+    // AC1 and AC-1 name the same criterion: its provers are the nodes proving either.
+    const provers = new Map();
+    for (const proofTarget of proofTargetIds(recipe)) {
+        const id = acceptanceIdForProofTarget(proofTarget);
+        if (!id)
+            continue;
+        const ids = new Set(provers.get(id));
+        for (const [nodeId, node] of Object.entries(nodes)) {
+            if (isRecord(node) && Array.isArray(node.proves) && node.proves.includes(proofTarget)) {
+                ids.add(nodeId);
+            }
+        }
+        provers.set(id, [...ids]);
+    }
+    const artifactsDir = path.dirname(result.tracePath);
+    const realTaskDir = fs.realpathSync(taskDir);
+    for (const [id, recipeNodes] of provers) {
+        if (recipeNodes.length === 0)
+            continue;
+        const verdict = recipeNodes.every((nodeId) => outcome.get(nodeId)?.ok === true)
+            ? 'proven'
+            : 'missing';
+        const evidence = [
+            ...new Set([
+                result.tracePath,
+                ...recipeNodes.flatMap((nodeId) => nodeArtifactPaths(outcome.get(nodeId), artifactsDir, target)),
+            ]
+                .map((file) => taskRelative(realTaskDir, file))
+                .filter((file) => file !== null)),
+        ];
+        try {
+            ledger.setAcceptanceVerdict(taskDir, { id, verdict, evidence, recipeNodes });
+            record.recorded.push({ id, verdict, evidence, recipeNodes });
+        }
+        catch (error) {
+            if (!(error instanceof ledger.AcceptanceRefusal))
+                throw error;
+            record.refused.push(`${id}: ${error.message}`);
+        }
+    }
+    return record;
+}
+// Proof targets are `{ id, claim }` objects (the recipe contract rejects any other shape).
+function proofTargetIds(recipe) {
+    const targets = isRecord(recipe) && Array.isArray(recipe.proofTargets) ? recipe.proofTargets : [];
+    return targets
+        .map((target) => (isRecord(target) ? target.id : null))
+        .filter((id) => typeof id === 'string');
+}
+// A node's artifact paths are relative to the run's artifacts dir or to the checkout;
+// the first that exists is the file.
+function nodeArtifactPaths(entry, artifactsDir, target) {
+    const artifacts = Array.isArray(entry?.artifacts) ? entry.artifacts : [];
+    return artifacts
+        .map((artifact) => isRecord(artifact) && typeof artifact.path === 'string' ? artifact.path : null)
+        .filter((file) => file !== null)
+        .map((file) => path.isAbsolute(file)
+        ? file
+        : [path.resolve(artifactsDir, file), path.resolve(target, file)].find((candidate) => fs.existsSync(candidate)))
+        .filter((file) => typeof file === 'string');
+}
+// The ledger keeps task-dir relative paths only. Both sides are resolved first, so a
+// symlink can't carry evidence from outside the task dir in, nor a symlinked checkout
+// path drop evidence that is inside.
+function taskRelative(realTaskDir, file) {
+    // A file the run didn't leave isn't evidence; any other error reaches the run's warning.
+    if (!fs.existsSync(file))
+        return null;
+    const real = fs.realpathSync(file);
+    const relative = path.relative(realTaskDir, real);
+    if (!relative ||
+        relative === '..' ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        return null;
+    }
+    return relative.split(path.sep).join('/');
+}
+function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+//# sourceMappingURL=acceptance-ledger.js.map

package/dist/harness/acceptance-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceptance-ledger.js","sourceRoot":"","sources":["../../src/harness/acceptance-ledger.ts"],"names":[],"mappings":"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"}

package/dist/harness/adapter-plugins.d.ts

@@ -0,0 +1,105 @@
+import { type AdapterDoctorCheck, type PlatformAdapter } from '@farmslot/adapter-sdk';
+import { type RecipeLibraryAdapterDeclaration, type RecipeLibrarySource } from '@farmslot/recipe-runner';
+import { CliError } from './parse-args.js';
+export type AdapterPluginErrorCode = 'ADAPTER_SDK_UNSUPPORTED' | 'ADAPTER_PLUGIN_INVALID' | 'ADAPTER_PLUGIN_LOAD_FAILED' | 'ADAPTER_ID_CONFLICT' | 'ADAPTER_EXTENDS_UNKNOWN';
+/** A declared adapter that cannot be selected. */
+export declare class AdapterPluginError extends CliError {
+    readonly code: AdapterPluginErrorCode;
+    readonly userAction: string;
+    constructor(code: AdapterPluginErrorCode, message: string, userAction: string);
+}
+/** One `adapters` entry and the library that declares it. */
+export interface DeclaredAdapter extends RecipeLibraryAdapterDeclaration {
+    id: string;
+    library: string;
+    root: string;
+}
+/** A plugin the loader registered: where it came from and the digest of its code. */
+export interface LoadedAdapterPlugin {
+    id: string;
+    library: string;
+    root: string;
+    module: string;
+    extends?: string;
+    /**
+     * sha256 over the declaring library's name and real root, the plugin's files
+     * (`digestLibraryAdapter`: the module's directory) and, with `extends`, the
+     * parent plugin's digest. Taken before the module is imported.
+     */
+    digest: string;
+}
+export interface AdapterLibraryOptions {
+    /** The command's `--library` entries; RECIPE_LIBRARY_PATH and the personal library follow. */
+    libraries?: readonly string[];
+    /**
+     * Libraries the host configures (e.g. a config file), after those. A source
+     * whose name or root is already present is skipped, so an earlier one wins.
+     */
+    configured?: readonly RecipeLibrarySource[];
+    /**
+     * The environment the operator started the command with (RECIPE_LIBRARY_PATH,
+     * the personal library's home), before the host's own library discovery
+     * extended it: plugins load only from the operator's libraries. Defaults to
+     * process.env; pass the same value to `adapterChoices` and `ensureAdapterLoaded`.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+export interface AdapterLoadOptions extends AdapterLibraryOptions {
+    /**
+     * Turns a loaded adapter into the host's adapter, e.g. defaults for members
+     * the host's registry requires beyond the SDK. Called before registration.
+     */
+    adopt?(adapter: PlatformAdapter): PlatformAdapter;
+}
+/**
+ * Every adapter id `--adapter` accepts: the registered adapters, then the ids
+ * the libraries declare (`declaredAdapterIds`). Reads recipe-library.json only;
+ * imports nothing. The libraries are resolved as recipes resolve them: `libraries`
+ * (--library), then RECIPE_LIBRARY_PATH entries they don't rename, else the
+ * personal library; then `configured`.
+ */
+export declare function adapterChoices(libraries?: readonly string[], options?: Pick<AdapterLibraryOptions, 'configured' | 'env'>): string[];
+/**
+ * The adapter ids these libraries declare in recipe-library.json `adapters`,
+ * read without importing anything. A library without a readable manifest
+ * declares nothing here; selecting one of its adapters reports the error.
+ */
+export declare function declaredAdapterIds(sources: readonly RecipeLibrarySource[]): string[];
+/**
+ * The adapter a command's tokens select, the way commands resolve it: the last
+ * `--adapter`, else the adapter of the last `--platform`. Tokens after `--` are
+ * passthrough and select nothing.
+ */
+export declare function selectedAdapterId(tokens: readonly string[]): string | undefined;
+/** The plugin the loader registered under `id` in the host's registry, if any. */
+export declare function adapterPlugin(id: string): LoadedAdapterPlugin | undefined;
+/** Every plugin the loader registered in the host's registry, in load order. */
+export declare function loadedAdapterPlugins(): LoadedAdapterPlugin[];
+/**
+ * One passing, non-required doctor check per loaded plugin, naming its library,
+ * module and digest, so the report shows which plugin code this process runs.
+ */
+export declare function adapterPluginChecks(): AdapterDoctorCheck[];
+/**
+ * Make `id` resolvable: a no-op for an absent id or a registered one, else load
+ * the one declaration for it (and what it extends) and register it. A built-in
+ * id that a library also declares is a conflict.
+ */
+export declare function ensureAdapterLoaded(id: string | undefined, options?: AdapterLoadOptions): Promise<void>;
+/**
+ * `child` on top of `parent`: the child's members replace the parent's, except
+ * three that append, parent first: the action manifests (`actions.manifestPaths`),
+ * the action implementations (`actions.adapters`) and the doctor checks (`doctor`).
+ */
+export declare function composeAdapter(parent: PlatformAdapter, child: PlatformAdapter): PlatformAdapter;
+/**
+ * Print a refused adapter selection: the `--json` envelope or the human line.
+ * Takes any error with a `code` and `userAction` (the loader's, and the library
+ * reader's RECIPE_SOURCE_INVALID); returns the exit code.
+ */
+export declare function adapterSelectionFailureOut(json: boolean, command: string, error: {
+    code: string;
+    message: string;
+    userAction: string;
+}): number;
+//# sourceMappingURL=adapter-plugins.d.ts.map

package/dist/harness/adapter-plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-plugins.d.ts","sourceRoot":"","sources":["../../src/harness/adapter-plugins.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAOL,KAAK,+BAA+B,EACpC,KAAK,mBAAmB,EAGzB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAAE,QAAQ,EAAY,MAAM,iBAAiB,CAAC;AAIrD,MAAM,MAAM,sBAAsB,GAC9B,yBAAyB,GACzB,wBAAwB,GACxB,4BAA4B,GAC5B,qBAAqB,GACrB,yBAAyB,CAAC;AAE9B,kDAAkD;AAClD,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAChB,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAM9E;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAgB,SAAQ,+BAA+B;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,8FAA8F;IAC9F,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC5C;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D;;;OAGG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAAC;CACnD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,SAAS,GAAE,SAAS,MAAM,EAAO,EACjC,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,YAAY,GAAG,KAAK,CAAM,GAC9D,MAAM,EAAE,CAGV;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAK/E;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAEzE;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,IAAI,mBAAmB,EAAE,CAE5D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,kBAAkB,EAAE,CAQ1D;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,MAAM,GAAG,SAAS,EACtB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAcf;AA2JD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,eAAe,CA6B/F;AAuJD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,MAAM,EACf,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3D,MAAM,CAqBR"}