@adhd/apigen-plugin-health 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+## 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:** externalize real npm deps in vite builds — 10 packages shipped broken dist bundles (__filename/timeOrigin crash)
+
+
+### ❤️  Thank You
+
+- pseudosky

package/README.md

@@ -1,13 +1,123 @@
 # @adhd/apigen-plugin-health
 
-apigen **mount plugin** — adds a health endpoint to a generated server. Activate with `--use`.
+**Mount plugin** — adds a `GET /_meta/health` endpoint to any apigen server. Reports runtime readiness for load balancers, orchestrators, and the apigen gateway (§13).
 
-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 adds
+
+When loaded via `--use`, the health plugin contributes a synthetic `_meta/health` operation that returns:
+
+```json
+GET /_meta/health
+→ {"status":"ok","host":"ts"}
+```
+
+The gateway (§13.1) routes a host's operations only after this endpoint reports `ready`. For an in-process runtime (non-gateway), it always reports `ok` — if the handler can respond, the runtime is alive.
+
+---
+
+## CLI usage
+
+```bash
+# Fastify with health check
+npx @adhd/apigen-cli run --source api.ts --type api-fastify --opt port=3000 --use health
+
+# MCP with health check (SSE transport)
+npx @adhd/apigen-cli run --source api.ts --type mcp --opt transport=sse --opt port=3000 --use health
+
+# With custom metadata in the response
+npx @adhd/apigen-cli run --source api.ts --type api-fastify --use health \
+  --opt 'useOptions={"health":{"meta":{"version":"1.0","region":"us-east"}}}'
+```
+
+After startup:
 
 ```bash
-npx @adhd/apigen-cli run --source ./api.ts --type api-fastify --use @adhd/apigen-plugin-health
+curl http://localhost:3000/_meta/health
+# → {"status":"ok","host":"ts","meta":{"version":"1.0","region":"us-east"}}
+```
+
+---
+
+## Programmatic usage
+
+```ts
+import { extract, composeSchemas } from '@adhd/apigen-core-client';
+import { apiFastifyPlugin } from '@adhd/apigen-plugin-api-fastify';
+import { healthPlugin } from '@adhd/apigen-plugin-health';
+
+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,
+    host: '0.0.0.0',
+    usePlugins: [
+      healthPlugin,   // ← mounts GET /_meta/health
+    ],
+    // With custom metadata:
+    // useOptions: { health: { meta: { version: '1.0', region: 'us-east' } } },
+  },
+  signal: abort.signal,
+  operations: ops,
+});
+```
+
+---
+
+## Options
+
+```ts
+import { type HealthOptions } from '@adhd/apigen-plugin-health';
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `meta` | `Record<string, string \| number \| boolean \| null>` | `undefined` | Extra metadata included in every health response payload |
+
+---
+
+## Response shape
+
+```ts
+interface HealthResponse {
+  status: 'ok';
+  host: string;                          // language runtime tag (e.g. 'ts')
+  meta?: Record<string, string | number | boolean | null>;
+}
+```
+
+---
+
+## Exports
+
+| Export | Kind |
+|--------|------|
+| `healthPlugin` | v2 `Plugin<HealthOptions>` — mount capability only |
+| `HealthOptions` | TypeScript interface |
+| `HealthResponse` | TypeScript interface |
+
 ```ts
-import { healthPlugin, type HealthOptions } from '@adhd/apigen-plugin-health'
+import { healthPlugin, type HealthOptions, type HealthResponse } from '@adhd/apigen-plugin-health';
 ```

package/index.js

@@ -1 +1 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});function s(e){return{raw:e,words:[e]}}function n(e,t={}){return[{id:"_meta/health",host:e.host,namespace:s("meta"),path:[s("health")],kind:"query",async:!1,streaming:!1,safe:!0,input:{},output:{type:"object",required:["status","host"],properties:{status:{const:"ok"},host:{type:"string"},meta:{type:"object"}}},envelope:{},typeText:null,transports:["http","grpc"],handler:i=>{const a={status:"ok",host:e.host};return t.meta!==void 0&&Object.keys(t.meta).length>0&&(a.meta=t.meta),a}}]}const o={id:"health",description:"Mount plugin: exposes GET /meta/health for gateway readiness (SPEC §13.1)",optionsSchema:{type:"object",properties:{meta:{type:"object",description:"Extra metadata included in the health response"}},additionalProperties:!1},capabilities:{mount:{operations(e,t){return n(e,t)}}}};exports.default=o;exports.healthPlugin=o;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});function s(e){return{raw:e,words:[e]}}function o(e,t={}){return[{id:"_meta/health",host:e.host,namespace:s("meta"),path:[s("health")],kind:"query",async:!1,streaming:!1,safe:!0,input:{},output:{type:"object",required:["status","host"],properties:{status:{const:"ok"},host:{type:"string"},meta:{type:"object"}}},envelope:{},typeText:null,transports:["http","grpc"],handler:i=>{const a={status:"ok",host:e.host};return t.meta!==void 0&&Object.keys(t.meta).length>0&&(a.meta=t.meta),a}}]}const n={id:"health",description:"Mount plugin: exposes GET /meta/health for gateway readiness (SPEC §13.1)",language:"ts",optionsSchema:{type:"object",properties:{meta:{type:"object",description:"Extra metadata included in the health response"}},additionalProperties:!1},capabilities:{mount:{operations(e,t){return o(e,t)}}}};exports.default=n;exports.healthPlugin=n;

package/index.mjs

@@ -45,17 +45,24 @@ function n(t, e = {}) {
 const r = {
   id: "health",
   description: "Mount plugin: exposes GET /meta/health for gateway readiness (SPEC §13.1)",
+  language: "ts",
   optionsSchema: {
     type: "object",
     properties: {
-      meta: { type: "object", description: "Extra metadata included in the health response" }
+      meta: {
+        type: "object",
+        description: "Extra metadata included in the health response"
+      }
     },
     additionalProperties: !1
   },
   capabilities: {
     mount: {
       operations(t, e) {
-        return n(t, e);
+        return n(
+          t,
+          e
+        );
       }
     }
   }

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 health mount plugin. */
 export interface HealthOptions {

package/package.json

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