@adhd/apigen-core-client 0.2.2 → 0.3.1

package/lib/batch.d.ts

@@ -45,21 +45,6 @@ export interface BatchKindSchema {
     /** Present only when ≥2 operations share this kind (a 1-branch `oneOf` is not a union). */
     discriminator?: InlineDiscriminator;
 }
-/**
- * Build the input/output schema pair for one `_batch/<kind>` mount (F1).
- *
- * - **≥2 ops of that kind:** a real `oneOf` + `InlineDiscriminator` union,
- *   using the same-document JSON-Pointer mechanism (`morph-walk.ts`), never
- *   `union.ts`'s $ref/nominal mechanism (§1.1).
- * - **Exactly 1 op of that kind:** the single branch's shape directly, no
- *   `oneOf` wrapper — `detectDiscriminator` itself refuses below 2 variants
- *   (§1.1's "edge case the 0.0.1 draft missed"), and a one-variant `oneOf`
- *   is not a union.
- *
- * Throws if `ops` is empty — callers (mount-building) must never invoke this
- * for a kind with zero operations; `groupBatchableOperationsByKind` never
- * produces an empty group.
- */
 export declare function buildBatchKindSchema(ops: readonly Operation[]): BatchKindSchema;
 /**
  * One synthetic `_batch/<kind>` operation shape, minus `handler` — mounting

package/lib/esm-require.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A `require` bound to this module's own location — the ESM-safe replacement
+ * for a bare `require(...)` in code bundled to BOTH `dist/index.js` (CJS) and
+ * `dist/index.mjs` (ESM). Resolves bare specifiers from this package's
+ * `node_modules` exactly as the CJS build's native `require` does, and (like
+ * the native `require`) exposes `.resolve`, so it is a drop-in for both
+ * `require(x)` and `require.resolve(x)` call sites.
+ *
+ * The `@ts-ignore` below suppresses TS1343 in DOWNSTREAM packages only.
+ * `apigen-core-client` is the base of the apigen family, so every consumer's
+ * `vite-plugin-dts` type-check follows this package's SOURCE through the
+ * tsconfig path mapping — and each consumer pins `module: commonjs` in its own
+ * `tsconfig.json`, where `import.meta` is rejected (TS1343). This file is only
+ * ever TYPE-CHECKED downstream, never emitted by it (the consumer emits its
+ * own declarations; the JS here is bundled by Rollup, which shims
+ * `import.meta.url` per output format) — so suppressing the diagnostic is
+ * scoped and safe. `@ts-ignore` (not `@ts-expect-error`) is deliberate: this
+ * package's own build runs `module: esnext`, where no diagnostic exists, so an
+ * expect-error directive would itself fail as unused. The rule-disable above
+ * the `@ts-ignore` is the established repo pattern for this exact suppression
+ * (see packages/data/data-query-engine/src/lib/expressions.ts).
+ */
+export declare const lazyRequire: NodeRequire;

package/lib/extract-invoker.d.ts

@@ -0,0 +1,90 @@
+import { Plugin } from './plugin';
+import { Operation } from './descriptor';
+
+/**
+ * One source unit to extract. Deliberately host-neutral — describes WHAT is
+ * being extracted, not HOW (no ts-morph/ts-json-schema-generator names leak
+ * in; a future per-language subprocess extractor speaks the same shape).
+ */
+export interface ExtractCall {
+    /**
+     * Absolute path to the source artifact for this language's extractor (a
+     * `.d.ts`/`.ts` file today; a directory/module root for a future
+     * subprocess-based extractor — the contract doesn't care which).
+     */
+    source: string;
+    /** Declared owning language runtime tag, e.g. 'ts' | 'py' | 'rust' (SPEC §4 host). */
+    host: string;
+    /** Namespace segment (SPEC §4). Casing-neutral. */
+    namespace?: string;
+    /**
+     * Free-form, extractor-specific options (e.g. a tsconfig path for TS today;
+     * a venv path for Python tomorrow). Opaque to the onion — read only by the
+     * terminal extractor step (and by cache layers that need identity signals).
+     */
+    extractorOptions?: Record<string, unknown>;
+    /**
+     * Opt-in caller-supplied identity tag for cache-key purposes (e.g. a
+     * monorepo's own content-addressed build hash). Absence is fine — a cache
+     * layer must compute its own key when absent, never trust an unverified
+     * hint from an untrusted caller.
+     */
+    versionHint?: string;
+}
+/**
+ * Extraction's RESULT is already the host-neutral descriptor shape SPEC §4
+ * defines — reuse it verbatim, do not invent a parallel result type.
+ */
+export type ExtractResult = Operation[];
+/** A stage-agnostic middleware step: receives the call, owns the continuation. */
+export type ExtractMiddleware = (call: ExtractCall, next: () => Promise<ExtractResult>) => Promise<ExtractResult>;
+/**
+ * Generic right-fold onion composition around an arbitrary innermost service.
+ * Identical composition algebra to the dispatch invoker's `reduceRight`
+ * (`apigen-engine-runtime`'s `invoke.ts`): `middlewares` are composed
+ * outermost-first (index 0 runs first); a middleware that returns without
+ * calling `next` short-circuits all downstream middlewares and the core.
+ */
+export declare function composeOnion<TCall, TResult>(middlewares: readonly ((call: TCall, next: () => Promise<TResult>) => Promise<TResult>)[], core: (call: TCall) => Promise<TResult>): (call: TCall) => Promise<TResult>;
+/**
+ * Compose an extract-stage invoker: `middlewares` (e.g. a cache layer)
+ * wrapping the terminal `runExtractor` step. Mirrors the dispatch stage's
+ * `createPackageInvoker` for the extract stage — the terminal step is "run
+ * the real extractor for `call.host`" instead of "run dispatch".
+ *
+ * A cache layer sits ABOVE `runExtractor`, so a cache HIT never invokes it —
+ * which is what makes this correct whether `runExtractor` is an in-process
+ * function today or a spawned subprocess tomorrow.
+ */
+export declare function createExtractInvoker(middlewares: readonly ExtractMiddleware[], runExtractor: (call: ExtractCall) => Promise<ExtractResult>): (call: ExtractCall) => Promise<ExtractResult>;
+/**
+ * Mirrors `createPackageInvoker`'s (`apigen-engine-runtime`'s
+ * `package-invoker.ts:124`) role for the extract stage (design doc Revision 2,
+ * R2.6 item 2 / implementation spec R2-2): pulls every loaded plugin's
+ * `extractLayer` capability — in declaration order, outermost-first, the
+ * identical composition rule `--use` layer ordering already follows on the
+ * dispatch side — and wraps `runExtractor` with them via {@link createExtractInvoker}.
+ *
+ * A plugin with no `extractLayer` capability (the common case today — nothing
+ * ships one yet) is filtered out silently; passing an empty `plugins` array
+ * (or a list where none declare `extractLayer`) degrades to `runExtractor`
+ * itself, unwrapped — a pure pass-through with zero behavioural change from
+ * calling `runExtractor` directly (R2-3's "byte-identical on MISS" guarantee).
+ *
+ * @param plugins      - The loaded `--use` plugin objects (or an explicit host-
+ *                       constructed list, e.g. backlog's `extractStagePlugins()`).
+ * @param runExtractor - The terminal extraction step (today: an in-process
+ *                       ts-morph `extract()` call; SPEC §12: potentially a
+ *                       spawned per-language subprocess later).
+ * @param opts         - This invocation's flat `--opt key=value` bag (the
+ *                       SAME bag already passed to `TargetCapability.generate`
+ *                       — apigen-cli has one flat bag per invocation, not a
+ *                       per-plugin-id namespaced one). Passed to each
+ *                       plugin's `extractLayer.createLayer(opts)` when
+ *                       present (`plugin.ts`'s `ExtractLayerCapability` doc);
+ *                       a plugin with only a static `.layer` ignores it.
+ *                       Defaults to `{}` — every existing call site (and
+ *                       every plugin with no opts-dependent behaviour)
+ *                       behaves identically whether this is passed or not.
+ */
+export declare function createExtractInvokerFromPlugins(plugins: readonly Plugin[], runExtractor: (call: ExtractCall) => Promise<ExtractResult>, opts?: Record<string, unknown>): (call: ExtractCall) => Promise<ExtractResult>;

package/lib/extraction-session.d.ts

@@ -82,6 +82,24 @@ export declare function fileVersion(pathStr: string): string;
 export declare function persistentSchemasFor(sfPath: string, tsconfig: string | undefined, version: string): Map<string, Record<string, unknown>>;
 /** Drop the process-lifetime Project + schema caches (tests / explicit memory reclaim). */
 export declare function clearPersistentProjectCache(): void;
+/**
+ * FEAT-002: absolute paths of every LOCAL (non-`node_modules`) file
+ * transitively imported by `entryPath`, in deterministic (sorted) order.
+ *
+ * Host-neutral, path-in/paths-out — the same `collectReferencedFiles` walk the
+ * session uses for its own invalidation, exposed so a persistent IR cache can
+ * content-hash the entry file's ENTIRE dependency graph for a stable,
+ * cross-machine cache key (an imported file's content is part of what the
+ * extractor's output depends on; a key covering only the entry file would
+ * falsely HIT after a type in an imported file changed).
+ *
+ * Uses a process-lifetime singleton Project with syntactic-only module
+ * resolution (no lib.d.ts parse, no type checking) so repeated key
+ * computations stay cheap. If the entry file was loaded before and has since
+ * changed on disk it is refreshed first, matching the walk's own
+ * refresh-before-descend behavior for visited targets.
+ */
+export declare function collectLocalImportPaths(entryPath: string): string[];
 /**
  * Create a fresh {@link ExtractionSession}.
  *

package/lib/format-alias.d.ts

@@ -0,0 +1,35 @@
+import { TypeNode } from 'ts-morph';
+
+/**
+ * Detects a `@format` JSDoc annotation on a plain, non-generic reference to a
+ * user-defined scalar type alias (e.g. `/** @format decimal *\/ type X =
+ * string;` referenced as a param/return type `X`), and returns the format
+ * string if found.
+ *
+ * Deliberately narrow — returns `undefined` (never throws) for every case
+ * outside this one:
+ *   - `typeNode` absent, or not a `TypeReference` node at all (covers plain
+ *     keyword types like `string`/`number`, array/tuple/union/etc. syntax).
+ *   - A generic reference (`Array<X>`, `Foo<T>`, …) — out of scope per spec;
+ *     the RESOLVED type at the call site must still flow through the
+ *     existing `Type#getText()` path unchanged.
+ *   - A qualified name (`Foo.Bar`) — only plain identifiers are considered.
+ *   - The identifier has no resolvable symbol, or none of its declarations is
+ *     a `TypeAliasDeclaration` (this alone already excludes interfaces,
+ *     classes, enums, and generic type parameters — none of those are ever a
+ *     `TypeAliasDeclaration`).
+ *   - The alias's own underlying type is not a plain scalar (string / number
+ *     / boolean) — guards against ever attaching `format` onto a structural
+ *     / object alias.
+ *   - No `@format` JSDoc tag is present on the alias declaration.
+ *
+ * Wrapped in a try/catch: this is an enhancement to extraction, never a
+ * required path, and must never crash extraction on an unexpected ts-morph
+ * API failure.
+ *
+ * @param typeNode - The syntactic type-node for a parameter or return type
+ *   (e.g. `paramDecl?.getTypeNode()`, `sig.getDeclaration()?.getReturnTypeNode()`),
+ *   as opposed to the RESOLVED `Type` that `Type#getText()` operates on.
+ * @returns The trimmed `@format` JSDoc comment text, or `undefined`.
+ */
+export declare function detectFormatAnnotatedAlias(typeNode: TypeNode | undefined): string | undefined;

package/lib/plugin.d.ts

@@ -1,3 +1,4 @@
+import { ExtractMiddleware } from './extract-invoker';
 import { PluginLanguage } from './types';
 import { Operation, OperationKind, JSONSchema, TypeText } from './descriptor';
 
@@ -248,6 +249,58 @@ export interface LayerCapability {
      */
     layer(call: Call, next: Next): Promise<Result> | AsyncIterable<Chunk>;
 }
+/**
+ * **`extractLayer`** capability — wrap the EXTRACT stage (design doc
+ * `extract-stage-onion-and-ir-cache.md` Revision 2, R2.6 item 1), not the
+ * dispatch stage `LayerCapability` above wraps.
+ *
+ * Same right-fold onion algebra as `LayerCapability.layer` — composed via
+ * {@link createExtractInvokerFromPlugins} in `extract-invoker.ts`, outermost
+ * plugin first — but typed against `ExtractCall`/`ExtractResult`
+ * (`extract-invoker.ts`), never the dispatch-shaped `Call`/`Result`. This is
+ * the deliberate, accepted "two Call shapes" asymmetry: `ExtractCall` has no
+ * `domainArgs`/`envelope`/`operation.id` to view-cast into a dispatch `Call`,
+ * so an extract-stage plugin (e.g. `@adhd/apigen-plugin-ir-cache`) declares
+ * this capability rather than reusing `layer`.
+ *
+ * A plugin may declare BOTH `layer` and `extractLayer` (they compose in their
+ * own, independent stages) or `extractLayer` alongside `target` (e.g. the
+ * ir-cache plugin: `extractLayer` for RUNTIME CACHE mode via `--use`,
+ * `target` for ARTIFACT mode via `--type`).
+ *
+ * **`createLayer` vs `layer` — the `--opt` gap fix.** A `Plugin` object is a
+ * static value with no per-invocation lifecycle hook, so a plain `layer`
+ * middleware built once at module-import time can never see a caller's
+ * `--use <id> --opt cache=<path>` value (unlike `TargetCapability.generate`/
+ * `MountCapability.operations`, which already receive `opts` as an explicit
+ * call-time parameter). `createLayer`, when present, is called ONCE per
+ * plugin at invoker-construction time (`createExtractInvokerFromPlugins`)
+ * with that invocation's flat `--opt` bag (the same bag already threaded to
+ * `TargetCapability.generate`'s `opts` — apigen-cli has exactly one flat
+ * `--opt` bag per invocation, not a per-plugin-id namespaced one; see
+ * `readUseOptions`'s `UseOptions` bag in `apigen-engine-runtime` for the
+ * dispatch-side per-plugin-id shape, which nothing in apigen-cli populates
+ * today, so this deliberately does not invent that infrastructure) and takes
+ * precedence over the static `layer`, which stays as the fallback for a
+ * plugin with no opts-dependent behaviour (or as an already-configured
+ * middleware a HOST builds directly via a factory, e.g.
+ * `entrypoint/backlog/src/server.ts`'s `backlogIrCachePlugin()`).
+ */
+export interface ExtractLayerCapability {
+    /**
+     * A ready-to-use extract-stage middleware — same short-circuit rule as
+     * `LayerCapability.layer`. Used when `createLayer` is absent, or by a host
+     * that constructs its own already-configured `Plugin` object directly
+     * (bypassing `--opt` entirely).
+     */
+    layer?: ExtractMiddleware;
+    /**
+     * Opts-aware factory: builds the middleware from this invocation's `--opt`
+     * bag. Preferred over `layer` by `createExtractInvokerFromPlugins` when
+     * both are present.
+     */
+    createLayer?: (opts: Record<string, unknown>) => ExtractMiddleware;
+}
 /**
  * Runtime dispatch options a {@link MountHostBridge} hands back to a mount
  * plugin's handler — structurally equivalent to `apigen-engine-runtime`'s
@@ -536,5 +589,15 @@ export interface Plugin<Opts = Record<string, unknown>> {
          * fields it needs and *read/write* them in its layer function.
          */
         envelope?: EnvelopeCapability;
+        /**
+         * Extract-layer capability — wrap the EXTRACT stage (design doc Revision
+         * 2, R2.6 item 1), not the dispatch stage `layer` above wraps.
+         *
+         * Loaded by `--use <plugin>` and composed via
+         * `createExtractInvokerFromPlugins` (`extract-invoker.ts`) — the single
+         * call site is `entrypoint/apigen-cli`'s `orchestrator.ts`'s
+         * `extractSource()`.
+         */
+        extractLayer?: ExtractLayerCapability;
     };
 }

package/lib/stream-type.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Detects whether `typeText` (a return type, already `Promise<T> → T`
+ * unwrapped by the caller) is one of the recognized streaming wrappers, and
+ * if so, returns the unwrapped per-chunk element type's text.
+ *
+ * Returns `null` when `typeText` is not a full, single streaming-wrapper
+ * type — including when it's a union with a stream member (e.g.
+ * `AsyncGenerator<T> | null`), since only the outermost `<...>` closing at
+ * the very end of the string counts as "fully wrapped" (a union closes its
+ * generic early, mid-string).
+ *
+ * @param typeText - Textual return type, e.g. `'AsyncGenerator<Chunk, void, unknown>'`.
+ * @returns The element type text (e.g. `'Chunk'`), or `null` if not streaming.
+ */
+export declare function detectStreamElementType(typeText: string): string | null;

package/lib/types.d.ts

@@ -35,6 +35,18 @@ export interface PluginInput {
         importPath: string;
         fns?: Record<string, (...args: unknown[]) => unknown>;
         createClient?: (envelope: Record<string, unknown>) => Promise<unknown>;
+        /**
+         * The real, published version of THIS package (e.g. `package.json`'s own
+         * `version`, read fresh — never a compiled-in constant). Optional: most
+         * `PluginInput.packages` callers never populate it and every existing
+         * construction site across the monorepo remains valid without it.
+         * `@adhd/apigen-plugin-mcp`'s `createMcpServer` reads it (falling back to
+         * this package's own `apigen-mcp`/`1.0.0` identity when absent) so an MCP
+         * client's `initialize` handshake reports which REAL build it is talking
+         * to, instead of a hardcoded placeholder identical across every apigen
+         * host (MCP handshake identity finding, P5-cli-serve-transport).
+         */
+        version?: string;
     }>;
     outputDir: string;
     options: Record<string, unknown>;

package/package.json

@@ -1,17 +1,40 @@
 {
   "name": "@adhd/apigen-core-client",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "dependencies": {
     "ts-morph": "^23.0.0",
     "ts-json-schema-generator": "^2.3.0",
     "pino": "10.3.1",
     "typescript": "^6.0.3",
-    "@adhd/apigen-base-logical": "^0.1.0"
+    "@adhd/apigen-base-logical": "^0.1.2"
   },
   "main": "./index.js",
   "module": "./index.mjs",
   "typings": "./index.d.ts",
   "publishConfig": {
     "access": "public"
+  },
+  "description": "Code-first API generation - derive JSON Schemas from TypeScript types and live-mount to HTTP, MCP, CLI, OpenAPI, Python, and Java with zero codegen",
+  "keywords": [
+    "openapi",
+    "typescript",
+    "codegen",
+    "json-schema",
+    "swagger",
+    "api",
+    "code-first",
+    "mcp",
+    "grpc",
+    "schema"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PseudoSky/adhd.git",
+    "directory": "packages/apigen/apigen-core-client"
+  },
+  "homepage": "https://github.com/PseudoSky/adhd/tree/main/packages/apigen/apigen-core-client#readme",
+  "bugs": {
+    "url": "https://github.com/PseudoSky/adhd/issues"
   }
 }