@adhd/apigen-engine-runtime 0.2.3 → 0.3.0

package/lib/describe-params.d.ts

@@ -4,11 +4,22 @@ export interface ParamInfo {
     required: boolean;
 }
 /**
- * Extract a composed schema entry's domain parameters for logging.
+ * Extract a composed schema entry's domain parameters for logging AND for a
+ * per-command `--help` rendering.
  *
  * Params live under `input.properties.data.properties` — the `data` envelope
  * wrapper is always present (see [def:ComposedSchemas]). Returns both a
  * structured list (for JSON logs) and a `name?: type` summary string.
+ *
+ * Every TOP-LEVEL param's type is expanded one level deep — an integer `depth`
+ * budget of 2 is passed to `typeName` (see its doc comment for the exact
+ * contract) — so an `object` with declared `properties` renders its fields and
+ * a `oneOf`/`anyOf` union renders its member shapes, e.g. `update`'s single
+ * `input` param renders as `input: { repo: string, humanId: string, patch:
+ * object, by: string }` instead of the placebo `input: object` that told a
+ * reader nothing about what the command actually accepts (the surviving half of
+ * FEAT-BACKLOG-003 / the `--help` finding in P5-cli-serve-transport). Nested
+ * unions/objects collapse to their placeholders, keeping the render bounded.
  */
 export declare function describeParams(schema: {
     input?: unknown;

package/lib/mcp-output-schema.d.ts

@@ -1,8 +1,23 @@
 /** Result of adapting a composed-schema `output` fragment for MCP's `outputSchema` field. */
 export interface McpOutputAdapter {
-    /** The MCP `Tool.outputSchema` value, or `undefined` when `output` carries no usable schema. */
+    /** The MCP `Tool.outputSchema` value, or `undefined` when the return is not
+     *  already a top-level `type:"object"` (nothing protocol-representable to
+     *  advertise — see ADR-0004). */
     outputSchema: Record<string, unknown> | undefined;
-    /** True when the output wasn't top-level `type:"object"` and had to be wrapped under `result`. */
+    /**
+     * Whether a matching `structuredContent` should be emitted for this output.
+     *
+     * `true` iff the return is already a top-level `type:"object"` — the only
+     * case in which an `outputSchema` is emitted at all; `false` for a
+     * union/array/scalar/void return, which is passed through flat on `content`
+     * alone (ADR-0004).
+     *
+     * Retained under its historical name because the generated host templates
+     * destructure `wrapped` and pass it straight to `wrapMcpStructuredContent`
+     * (as do already-generated hosts out in the wild). Since ADR-0004 it no
+     * longer means "the schema was wrapped under `result`" — nothing is ever
+     * wrapped. Read it as `emitStructuredContent`.
+     */
     wrapped: boolean;
 }
 /**
@@ -14,8 +29,13 @@ export interface McpOutputAdapter {
  */
 export declare function buildMcpOutputSchema(output: unknown): McpOutputAdapter;
 /**
- * Wraps a tool's actual return value to match the `outputSchema` shape built by
- * `buildMcpOutputSchema` for the SAME `output` fragment, for use as MCP's
- * `structuredContent` (also constrained to a plain object by the SDK).
+ * Returns the MCP `structuredContent` for a tool's actual return value.
+ *
+ * `emit` is `McpOutputAdapter.wrapped` for the SAME `output` fragment: only an
+ * already-object return emits `structuredContent`, and it is the value itself
+ * — never wrapped under `result` (ADR-0004). A non-plain-object value (or an
+ * `emit:false` non-object return) yields `undefined`: `structuredContent`
+ * (like `outputSchema`) is constrained to a plain object by the SDK, so an
+ * array/scalar must not be emitted there.
  */
-export declare function wrapMcpStructuredContent(wrapped: boolean, value: unknown): Record<string, unknown> | undefined;
+export declare function wrapMcpStructuredContent(emit: boolean, value: unknown): Record<string, unknown> | undefined;

package/lib/op-plan.d.ts

@@ -30,6 +30,13 @@ export interface OpPlanCliFlag {
     valueKind: 'boolean' | 'json' | 'string';
     /** (envelope only) `APIGEN_<PLUGINID>_<FIELD>` fallback when the flag is absent. */
     envVar?: string;
+    /**
+     * Set ONLY on a camelCase alias entry, naming the canonical kebab-case key it
+     * resolves to (BUG-BACKLOG-CLI-FLAG-CASE-MISMATCH-001). Transports must
+     * exclude aliased entries when LISTING available flags — kebab-case remains
+     * the single advertised spelling — while still accepting them on input.
+     */
+    aliasOf?: string;
 }
 /**
  * A fully-resolved, transport-complete plan for one `Operation` (proposal §3a).

package/lib/package-invoker.d.ts

@@ -47,6 +47,23 @@ export type UseOptions = Record<string, Record<string, unknown>>;
  * carries no dedicated field, so they ride on `options.usePlugins`).
  */
 export declare function readUsePlugins(options: Record<string, unknown>): UsePlugin[];
+/**
+ * Optional `options.exitCode` hook: maps a SUCCESSFULLY-RETURNED result to a
+ * process exit code.
+ *
+ * A host whose operations return a result-shaped outcome (`{ok:false, error}`)
+ * rather than throwing looks like unqualified success to a transport, so the
+ * CLI exits 0 on a reported failure — a caller's `&&` chain then proceeds and
+ * `set -e` never trips. This hook is the seam that lets such a host state its
+ * own mapping without apigen having to know the envelope shape.
+ *
+ * Opt-in and absent by default: a host that does not pass it keeps the
+ * existing "returned normally ⇒ exit 0" behaviour exactly.
+ *
+ * Thrown `ApiError`s are unaffected — those already map through
+ * `CLI_EXIT_CODE`.
+ */
+export declare function readExitCodeHook(options: Record<string, unknown>): ((result: unknown) => number | undefined) | undefined;
 export declare function readUseOptions(options: Record<string, unknown>): UseOptions;
 /**
  * Adapt a core `LayerCapability.layer` (which receives the SPEC §7.1 `Call`

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@adhd/apigen-engine-runtime",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "dependencies": {
     "ajv": "^8.20.0",
     "ajv-formats": "2.1.1",
     "pino": "10.3.1",
-    "@adhd/apigen-core-client": "^0.3.0",
-    "@adhd/apigen-base-logical": "^0.1.1",
-    "@adhd/apigen-base-errors": "^0.2.0",
-    "@adhd/apigen-engine-naming": "^0.2.2",
+    "@adhd/apigen-core-client": "^0.3.2",
+    "@adhd/apigen-base-logical": "^0.1.3",
+    "@adhd/apigen-base-errors": "^0.2.2",
+    "@adhd/apigen-engine-naming": "^0.2.4",
     "better-sqlite3": "12.10.0"
   },
   "main": "./index.js",
@@ -16,5 +16,25 @@
   "typings": "./index.d.ts",
   "publishConfig": {
     "access": "public"
+  },
+  "description": "Runtime executor for apigen - dispatch derived operations with pluggable concurrency and transports",
+  "keywords": [
+    "api",
+    "runtime",
+    "typescript",
+    "schema",
+    "dispatch",
+    "concurrency",
+    "codegen"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PseudoSky/adhd.git",
+    "directory": "packages/apigen/apigen-engine-runtime"
+  },
+  "homepage": "https://github.com/PseudoSky/adhd/tree/main/packages/apigen/apigen-engine-runtime#readme",
+  "bugs": {
+    "url": "https://github.com/PseudoSky/adhd/issues"
   }
 }