@adhd/apigen-engine-runtime 0.2.2 → 0.2.4

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/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/lib/tool-description.d.ts

@@ -1,6 +1,8 @@
-/** The minimal shape this module reads off a composed schema entry. */
+import { JsonSchemaLike } from '@adhd/apigen-base-logical';
+
+/** The minimal shape this module reads off a composed (or mount) schema entry. */
 export interface ToolDescriptionSchema {
-    input?: {
+    input?: JsonSchemaLike & {
         description?: unknown;
     };
 }
@@ -9,9 +11,10 @@ export interface ToolDescriptionSchema {
  * response.
  *
  * @param name - The MCP tool name (used as the final fallback).
- * @param schema - The function's composed schema (as produced by
- *   `composeSchemas`); `input.description` carries the auto-generated
- *   envelope/data-wrapper documentation.
+ * @param schema - The function's composed (or mount) schema; `input` is
+ *   read both for the envelope/data-wrapper documentation
+ *   (`input.description`, when present) and for synthesizing a concrete
+ *   worked example off its actual shape.
  * @param override - An optional caller-supplied description (e.g. from the
  *   `toolDescriptions` plugin option), prepended when present.
  */

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@adhd/apigen-engine-runtime",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "dependencies": {
     "ajv": "^8.20.0",
     "ajv-formats": "2.1.1",
     "pino": "10.3.1",
-    "@adhd/apigen-core-client": "^0.2.2",
-    "@adhd/apigen-base-logical": "^0.1.0",
-    "@adhd/apigen-base-errors": "^0.2.0",
-    "@adhd/apigen-engine-naming": "^0.2.1",
+    "@adhd/apigen-core-client": "^0.3.1",
+    "@adhd/apigen-base-logical": "^0.1.2",
+    "@adhd/apigen-base-errors": "^0.2.1",
+    "@adhd/apigen-engine-naming": "^0.2.3",
     "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"
   }
 }

package/test-support/parity-harness.d.ts

@@ -88,6 +88,43 @@ export interface NegativeControlOptions {
  * only mutation performed, and it is always undone in a `finally`.
  */
 export declare function proveNegativeControl(runner: () => void | Promise<void>, patchPath: string, opts?: NegativeControlOptions): Promise<void>;
+/**
+ * Runs `git <args>` scoped to `cwd` via `-C` (never relying on the child's
+ * inherited working directory alone), with every `GIT_*` environment
+ * variable stripped so an ambient `GIT_DIR`/`GIT_WORK_TREE`/`GIT_INDEX_FILE`
+ * (as git sets when invoking hooks — see above) cannot silently redirect the
+ * command at a different repository than `cwd`.
+ */
+export declare function runGit(args: readonly string[], opts: {
+    cwd: string;
+}): string;
+/**
+ * Proves `dir` is itself a git repository root — not merely a subdirectory
+ * of some OTHER repository (which `git rev-parse --show-toplevel` would
+ * silently resolve to instead). Throws loudly on any mismatch, missing
+ * repo, or git failure — this is the assertion that turns "we assume the
+ * scratch repo is isolated" into "we proved it before touching it".
+ */
+export declare function assertIsolatedRepoRoot(dir: string): void;
+/**
+ * Creates a throwaway, PROVABLY isolated git repository for tests that need
+ * to exercise real `git` mutations (init/config/add/commit) without any
+ * possibility of touching the enclosing repository.
+ *
+ * Isolation is structural, not incidental:
+ *   - The scratch repo lives under `os.tmpdir()` (never nested inside any
+ *     tracked working tree), so nothing that walks up looking for an
+ *     enclosing `.git` can land on the real repo.
+ *   - `git init` and every subsequent call go through {@link runGit}, which
+ *     strips `GIT_*` env so ambient hook variables cannot redirect it.
+ *   - {@link assertIsolatedRepoRoot} is run immediately after `init` and
+ *     BEFORE this function returns — the caller only ever receives a dir
+ *     that has already been proven isolated; a failure to isolate throws
+ *     here rather than silently degrading into "isolated most of the time".
+ */
+export declare function createIsolatedScratchRepo(prefix: string): {
+    dir: string;
+};
 /**
  * Bulletproof teardown for a spawned test server (`flask_server.py`,
  * `grpc_server.py`, …): sends `SIGTERM`, waits for the process's real `exit`