@adhd/apigen-plugin-openapi 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+## 0.1.3 (2026-07-23)
+
+
+### 🚀 Features
+
+- session batch — dispatch tool-exec + provider routing, publish hygiene, agent/env/apigen fixes
+
+- **release:** nx release independent versioning + verify-dist-load publish gate (Agent 2)
+
+
+### 🩹 Fixes
+
+- resolve build errors from workspace-cleanup merge — unterminated strings, path mappings, lint
+
+- **apigen:** update remaining stale @adhd/apigen-errors, core, logical refs
+
+- **environment:** correct agent-mcp plugins at: classification (build->runtime)
+
+- **apigen:** complete FEAT-APIGEN-022 test coverage — primitive→GET + complex→POST
+
+- **apigen:** externalize real npm deps in vite builds — 10 packages shipped broken dist bundles (__filename/timeOrigin crash)
+
+- **apigen-plugin-openapi:** sync @adhd/apigen-codegen-openapi range to installed 0.1.2
+
+
+### ❤️  Thank You
+
+- pseudosky

package/README.md

@@ -1,14 +1,141 @@
 # @adhd/apigen-plugin-openapi
 
-apigen plugin — emits an **OpenAPI** document for a source file's exports, built on
-[`@adhd/apigen-codegen-openapi`](../../codegen/openapi).
+**Mount plugin** — serves a **live OpenAPI 3.1 document** at `GET /_meta/openapi`. The document is derived from the extracted operations at request time, so it always reflects the current service definition.
 
-Part of [apigen](../../README.md). Driven via [`@adhd/apigen-cli`](../../cli).
+Part of [apigen](../README.md). Driven via [`@adhd/apigen-cli`](../../../entrypoint/apigen-cli/README.md).
+
+---
+
+## What it does
+
+When loaded via `--use` on any HTTP target plugin (`api-fastify`, `api-express`), the openapi plugin contributes a synthetic `_meta/openapi` operation. Hitting `GET /_meta/openapi` returns a full OpenAPI 3.1 spec derived from your operations at request time — every endpoint, parameter type, and response shape, all inferred from your TypeScript types.
+
+**No code generation, no build step.** The spec is always current with your running service.
 
 ```bash
-npx @adhd/apigen-cli generate --source ./api.ts --type openapi --out-dir ./out
+curl http://localhost:3000/_meta/openapi
+# → {
+#   "openapi": "3.1.0",
+#   "info": { "title": "My API", "version": "1.0.0" },
+#   "paths": {
+#     "/api/getUser": {
+#       "get": {
+#         "parameters": [{ "name": "id", "in": "query", "schema": { "type": "string" } }],
+#         "responses": { "200": { "description": "success" } }
+#       }
+#     }
+#   }
+# }
+```
+
+---
+
+## CLI usage
+
+```bash
+# Fastify with OpenAPI doc
+npx @adhd/apigen-cli run --source api.ts --type api-fastify --opt port=3000 --use openapi
+
+# With custom title and version
+npx @adhd/apigen-cli run --source api.ts --type api-fastify --use openapi \
+  --opt 'useOptions={"openapi":{"title":"User API","version":"2.0.0"}}'
+
+# Combined with other plugins
+npx @adhd/apigen-cli run --source api.ts --type api-fastify --use openapi --use health --use logger
 ```
 
+---
+
+## Programmatic usage
+
+```ts
+import { extract, composeSchemas } from '@adhd/apigen-core-client';
+import { apiFastifyPlugin } from '@adhd/apigen-plugin-api-fastify';
+import { openapiPlugin } from '@adhd/apigen-plugin-openapi';
+
+const ops = await extract({ sourceFile: './api.ts', namespace: 'api' });
+const schemas = composeSchemas(
+  {
+    metadata: { namespace: 'api', phase: '' },
+    schemas: Object.fromEntries(
+      ops.filter(o => o.kind === 'action').map(op => [
+        op.path[op.path.length - 1].raw,
+        { input: op.input, output: op.output, hasCtx: op.hasCtx, 'x-apigen-safe': op.safe },
+      ])
+    ),
+  },
+  []
+);
+const mod = await import('./api.ts');
+
+const abort = new AbortController();
+process.on('SIGINT', () => abort.abort());
+
+await apiFastifyPlugin.run({
+  packages: [{ id: 'api', schemas, importPath: './api.ts', fns: mod, createClient: async () => ({}) }],
+  outputDir: '',
+  options: {
+    port: 3000,
+    usePlugins: [
+      openapiPlugin,  // ← mounts GET /_meta/openapi
+    ],
+    // Custom title and version:
+    // useOptions: { openapi: { title: 'User API', version: '2.0.0' } },
+  },
+  signal: abort.signal,
+  operations: ops,
+});
+```
+
+---
+
+## Options
+
+```ts
+import { type OpenapiOptions } from '@adhd/apigen-plugin-openapi';
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `title` | `string` | `'API'` | `info.title` in the generated OpenAPI document |
+| `version` | `string` | `'0.0.0'` | `info.version` in the generated OpenAPI document |
+
+---
+
+## What gets documented
+
+Every operation extracted from your source file appears in the `paths` section:
+
+- **Safe operations** (`x-apigen-safe: true`) → listed as `GET` with query parameters
+- **Unsafe operations** → listed as `POST` with `requestBody`
+
+Rich types (Date, Decimal, bigint, UUID) use their canonical JSON Schema representations with `x-apigen-*` hints so codegen tools can reconstruct the correct types.
+
+---
+
+## How it works
+
+The openapi plugin implements the **mount capability** (SPEC §7.2b). At compose time, it registers a synthetic `_meta/openapi` operation. At request time, the handler calls `toOpenApi()` from `@adhd/apigen-codegen-openapi` with the full `Operation[]` descriptor — the same one used to serve requests — and returns the live document. No caching, no staleness.
+
+This is the same function you can use independently:
+
+```ts
+import { toOpenApi } from '@adhd/apigen-codegen-openapi';
+import type { Operation } from '@adhd/apigen-core-client';
+
+const doc = toOpenApi(operations, { title: 'My API', version: '1.0.0' });
+// doc satisfies the OpenAPI 3.1 schema
+```
+
+---
+
+## Exports
+
+| Export | Kind |
+|--------|------|
+| `openapiPlugin` | v2 `Plugin<OpenapiOptions>` — mount capability only |
+| `OpenapiOptions` | TypeScript interface |
+
 ```ts
-import { openapiPlugin, type OpenapiOptions } from '@adhd/apigen-plugin-openapi'
+import { openapiPlugin, type OpenapiOptions } from '@adhd/apigen-plugin-openapi';
 ```

package/index.js

@@ -1 +1 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});function m(e){return e.words.join("-")}function g(e){return e.words.map(P).join("")}function b(e){return e.words.join("_")}function v(e,t={}){var d,h;const n=[e.namespace,...e.path],s=e.safe?"GET":"POST",r=((h=(d=t.http)==null?void 0:d.verb)==null?void 0:h[e.id])??s,o="/"+n.map(i=>m(i)).join("/"),l=n.map(i=>b(i)).join("_"),p=n.map(i=>b(i)).slice(0,-1).join("."),u=g(n[n.length-2]??n[0]),c=g(n[n.length-1]),a=n.map(i=>m(i));return{http:{verb:r,route:o},mcp:{name:l},grpc:{package:p,service:u,method:c},cli:{path:a}}}function P(e){return e.length===0?e:e[0].toUpperCase()+e.slice(1)}function O(e,t={}){const n=t.title??"API",s=t.version??"0.0.0",r={};for(const o of e){const l=v(o),{verb:f,route:p}=l.http,u=f.toLowerCase(),c={operationId:o.id,summary:o.id,responses:{200:S(o.output)}};if(o.safe)c.parameters=q(o.input);else{const a=o.input;typeof a=="object"&&a!==null&&Object.keys(a).length>0&&(c.requestBody={required:!0,content:{"application/json":{schema:a}}})}r[p]===void 0&&(r[p]={}),r[p][u]=c}return{openapi:"3.1.0",info:{title:n,version:s},paths:r}}function S(e){return typeof e=="object"&&e!==null&&Object.keys(e).length>0?{description:"Success",content:{"application/json":{schema:e}}}:{description:"Success"}}function q(e){if(typeof e!="object"||e===null||typeof e.properties!="object"||e.properties===null)return[];const t=Array.isArray(e.required)?e.required:[],n=e.properties;return Object.entries(n).map(([s,r])=>({name:s,in:"query",required:t.includes(s),schema:r}))}function y(e){return{raw:e,words:e.split(/(?=[A-Z])|[-_]/).map(t=>t.toLowerCase()).filter(Boolean)}}function A(e,t={}){return[{id:"_meta/openapi",host:e.host,namespace:y("meta"),path:[y("openapi")],kind:"query",async:!1,streaming:!1,safe:!0,input:{},output:{type:"object"},envelope:{},typeText:null,transports:["http"],handler:n=>O(e.operations,{title:t.title,version:t.version})}]}const j={id:"openapi",description:"Mount plugin: serves the OpenAPI 3.1 doc at GET /meta/openapi",optionsSchema:{type:"object",properties:{title:{type:"string",description:"OpenAPI info.title"},version:{type:"string",description:"OpenAPI info.version"}},additionalProperties:!1},capabilities:{mount:{operations(e,t){return A(e,t)}}}};exports.default=j;exports.openapiPlugin=j;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require("ts-morph");require("node:fs");require("node:path");require("ts-json-schema-generator");const d=new Set(["string","number","boolean","integer"]);function v(e){if(typeof e!="object"||e===null)return!1;const t=e;if(t.$ref!==void 0||t.oneOf||t.anyOf||t.allOf)return!1;const{type:r}=t;return typeof r=="string"?d.has(r):Array.isArray(r)?r.every(o=>d.has(o)||o==="null"):Array.isArray(t.enum)&&t.enum.length>0?t.enum.every(o=>["string","number","boolean"].includes(typeof o)):!1}function O(e){if(!e||typeof e!="object")return!1;const t=e.properties;return t===void 0||typeof t!="object"||t===null?!1:Object.values(t).every(v)}const q={"decimal.js":"Decimal"};function A(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}Object.entries(q).map(([e,t])=>({pattern:new RegExp(`import\\(["'][^"']*${A(e)}[^"']*["']\\)\\.\\w+`,"g"),key:t}));function m(e){return e.words.join("-")}function y(e){return e.words.map(w).join("")}function g(e){return e.words.join("_")}function P(e,t={}){var r,o;const n=[e.namespace,...e.path],i=e.safe||O(e.input)?"GET":"POST",c=((o=(r=t.http)==null?void 0:r.verb)==null?void 0:o[e.id])??i,l="/"+n.map(s=>m(s)).join("/"),a=n.map(s=>g(s)).join("_"),f=n.map(s=>g(s)).slice(0,-1).join("."),u=y(n[n.length-2]??n[0]),p=y(n[n.length-1]),j=n.map(s=>m(s));return{http:{verb:c,route:l},mcp:{name:a},grpc:{package:f,service:u,method:p},cli:{path:j}}}function w(e){return e.length===0?e:e[0].toUpperCase()+e.slice(1)}function S(e,t={}){const r=t.title??"API",o=t.version??"0.0.0",n={};for(const i of e){const c=P(i),{verb:l,route:a}=c.http,f=l.toLowerCase(),u={operationId:i.id,summary:i.id,responses:{200:_(i.output)}};if(l==="GET")u.parameters=k(i.input);else{const p=i.input;typeof p=="object"&&p!==null&&Object.keys(p).length>0&&(u.requestBody={required:!0,content:{"application/json":{schema:p}}})}n[a]===void 0&&(n[a]={}),n[a][f]=u}return{openapi:"3.1.0",info:{title:r,version:o},paths:n}}function _(e){return typeof e=="object"&&e!==null&&Object.keys(e).length>0?{description:"Success",content:{"application/json":{schema:e}}}:{description:"Success"}}function k(e){if(typeof e!="object"||e===null||typeof e.properties!="object"||e.properties===null)return[];const t=Array.isArray(e.required)?e.required:[],r=e.properties;return Object.entries(r).map(([o,n])=>({name:o,in:"query",required:t.includes(o),schema:n}))}function b(e){return{raw:e,words:e.split(/(?=[A-Z])|[-_]/).map(t=>t.toLowerCase()).filter(Boolean)}}function T(e,t={}){return[{id:"_meta/openapi",host:e.host,namespace:b("meta"),path:[b("openapi")],kind:"query",async:!1,streaming:!1,safe:!0,input:{},output:{type:"object"},envelope:{},typeText:null,transports:["http"],handler:r=>S(e.operations,{title:t.title,version:t.version})}]}const h={id:"openapi",description:"Mount plugin: serves the OpenAPI 3.1 doc at GET /meta/openapi",language:"ts",optionsSchema:{type:"object",properties:{title:{type:"string",description:"OpenAPI info.title"},version:{type:"string",description:"OpenAPI info.version"}},additionalProperties:!1},capabilities:{mount:{operations(e,t){return T(e,t)}}}};exports.default=h;exports.openapiPlugin=h;

package/index.mjs

@@ -1,40 +1,81 @@
-function m(e) {
+import "ts-morph";
+import "node:fs";
+import "node:path";
+import "ts-json-schema-generator";
+const m = /* @__PURE__ */ new Set(["string", "number", "boolean", "integer"]);
+function j(e) {
+  if (typeof e != "object" || e === null)
+    return !1;
+  const t = e;
+  if (t.$ref !== void 0 || t.oneOf || t.anyOf || t.allOf)
+    return !1;
+  const { type: o } = t;
+  return typeof o == "string" ? m.has(o) : Array.isArray(o) ? o.every((r) => m.has(r) || r === "null") : Array.isArray(t.enum) && t.enum.length > 0 ? t.enum.every((r) => ["string", "number", "boolean"].includes(typeof r)) : !1;
+}
+function v(e) {
+  if (!e || typeof e != "object")
+    return !1;
+  const t = e.properties;
+  return t === void 0 || typeof t != "object" || t === null ? !1 : Object.values(t).every(
+    j
+  );
+}
+const O = {
+  "decimal.js": "Decimal"
+};
+function A(e) {
+  return e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+Object.entries(O).map(([e, t]) => ({
+  // Matches: import("...{modSpec}...").<anyMemberName>  (single or double quotes)
+  // The module specifier appears inside an absolute path, so we allow any
+  // characters between the quote and the specifier, and between the specifier
+  // and the closing quote. The trailing member accessor (`.default`, `.Decimal`,
+  // …) is matched generically (`\w+`) rather than anchored to one spelling —
+  // see the doc comment above for why.
+  pattern: new RegExp(
+    `import\\(["'][^"']*${A(e)}[^"']*["']\\)\\.\\w+`,
+    "g"
+  ),
+  key: t
+}));
+function d(e) {
   return e.words.join("-");
 }
 function y(e) {
-  return e.words.map(v).join("");
+  return e.words.map(w).join("");
 }
-function b(e) {
+function h(e) {
   return e.words.join("_");
 }
-function j(e, t = {}) {
-  var f, h;
-  const n = [e.namespace, ...e.path], s = e.safe ? "GET" : "POST", r = ((h = (f = t.http) == null ? void 0 : f.verb) == null ? void 0 : h[e.id]) ?? s, o = "/" + n.map((i) => m(i)).join("/"), l = n.map((i) => b(i)).join("_"), a = n.map((i) => b(i)).slice(0, -1).join("."), u = y(n[n.length - 2] ?? n[0]), c = y(n[n.length - 1]), p = n.map((i) => m(i));
+function q(e, t = {}) {
+  var o, r;
+  const n = [e.namespace, ...e.path], i = e.safe || v(e.input) ? "GET" : "POST", l = ((r = (o = t.http) == null ? void 0 : o.verb) == null ? void 0 : r[e.id]) ?? i, c = "/" + n.map((s) => d(s)).join("/"), a = n.map((s) => h(s)).join("_"), f = n.map((s) => h(s)).slice(0, -1).join("."), u = y(n[n.length - 2] ?? n[0]), p = y(n[n.length - 1]), g = n.map((s) => d(s));
   return {
-    http: { verb: r, route: o },
-    mcp: { name: l },
-    grpc: { package: a, service: u, method: c },
-    cli: { path: p }
+    http: { verb: l, route: c },
+    mcp: { name: a },
+    grpc: { package: f, service: u, method: p },
+    cli: { path: g }
   };
 }
-function v(e) {
+function w(e) {
   return e.length === 0 ? e : e[0].toUpperCase() + e.slice(1);
 }
 function P(e, t = {}) {
-  const n = t.title ?? "API", s = t.version ?? "0.0.0", r = {};
-  for (const o of e) {
-    const l = j(o), { verb: d, route: a } = l.http, u = d.toLowerCase(), c = {
-      operationId: o.id,
-      summary: o.id,
+  const o = t.title ?? "API", r = t.version ?? "0.0.0", n = {};
+  for (const i of e) {
+    const l = q(i), { verb: c, route: a } = l.http, f = c.toLowerCase(), u = {
+      operationId: i.id,
+      summary: i.id,
       responses: {
-        200: O(o.output)
+        200: k(i.output)
       }
     };
-    if (o.safe)
-      c.parameters = q(o.input);
+    if (c === "GET")
+      u.parameters = S(i.input);
     else {
-      const p = o.input;
-      typeof p == "object" && p !== null && Object.keys(p).length > 0 && (c.requestBody = {
+      const p = i.input;
+      typeof p == "object" && p !== null && Object.keys(p).length > 0 && (u.requestBody = {
         required: !0,
         content: {
           "application/json": {
@@ -43,15 +84,15 @@ function P(e, t = {}) {
         }
       });
     }
-    r[a] === void 0 && (r[a] = {}), r[a][u] = c;
+    n[a] === void 0 && (n[a] = {}), n[a][f] = u;
   }
   return {
     openapi: "3.1.0",
-    info: { title: n, version: s },
-    paths: r
+    info: { title: o, version: r },
+    paths: n
   };
 }
-function O(e) {
+function k(e) {
   return typeof e == "object" && e !== null && Object.keys(e).length > 0 ? {
     description: "Success",
     content: {
@@ -59,28 +100,31 @@ function O(e) {
     }
   } : { description: "Success" };
 }
-function q(e) {
+function S(e) {
   if (typeof e != "object" || e === null || typeof e.properties != "object" || e.properties === null)
     return [];
-  const t = Array.isArray(e.required) ? e.required : [], n = e.properties;
-  return Object.entries(n).map(([s, r]) => ({
-    name: s,
+  const t = Array.isArray(e.required) ? e.required : [], o = e.properties;
+  return Object.entries(o).map(([r, n]) => ({
+    name: r,
     in: "query",
-    required: t.includes(s),
-    schema: r
+    required: t.includes(r),
+    schema: n
   }));
 }
-function g(e) {
-  return { raw: e, words: e.split(/(?=[A-Z])|[-_]/).map((t) => t.toLowerCase()).filter(Boolean) };
+function b(e) {
+  return {
+    raw: e,
+    words: e.split(/(?=[A-Z])|[-_]/).map((t) => t.toLowerCase()).filter(Boolean)
+  };
 }
-function A(e, t = {}) {
+function I(e, t = {}) {
   return [
     {
       // Canonical id — the `_meta` prefix is a convention for meta-endpoints.
       id: "_meta/openapi",
       host: e.host,
-      namespace: g("meta"),
-      path: [g("openapi")],
+      namespace: b("meta"),
+      path: [b("openapi")],
       // query + safe → GET /meta/openapi (SPEC §5)
       kind: "query",
       async: !1,
@@ -96,16 +140,17 @@ function A(e, t = {}) {
       // Expose only on HTTP — the doc is a tooling artefact (SPEC §7.2b).
       transports: ["http"],
       // Handler: derive the doc from the descriptor at request time.
-      handler: (n) => P(e.operations, {
+      handler: (o) => P(e.operations, {
         title: t.title,
         version: t.version
       })
     }
   ];
 }
-const S = {
+const x = {
   id: "openapi",
   description: "Mount plugin: serves the OpenAPI 3.1 doc at GET /meta/openapi",
+  language: "ts",
   optionsSchema: {
     type: "object",
     properties: {
@@ -117,12 +162,15 @@ const S = {
   capabilities: {
     mount: {
       operations(e, t) {
-        return A(e, t);
+        return I(
+          e,
+          t
+        );
       }
     }
   }
 };
 export {
-  S as default,
-  S as openapiPlugin
+  x as default,
+  x as openapiPlugin
 };

package/lib/plugin.d.ts

@@ -1,4 +1,4 @@
-import { Plugin } from '@adhd/apigen-core';
+import { Plugin } from '@adhd/apigen-core-client';
 
 /** Options accepted by the openapi mount plugin. */
 export interface OpenapiOptions {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@adhd/apigen-plugin-openapi",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "main": "./index.js",
   "dependencies": {
-    "@adhd/apigen-core": "^0.1.0",
-    "@adhd/apigen-codegen-openapi": "^0.1.0"
+    "@adhd/apigen-core-client": "^0.1.1",
+    "@adhd/apigen-codegen-openapi": "^0.1.3"
   },
   "publishConfig": {
     "access": "public"