@adhd/apigen-core-client 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,9 +1,6 @@
-# Changelog
+## 0.1.1 (2026-07-23)
 
-All notable changes to `@adhd/apigen-core-client` will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+This was a version bump only for apigen-core-client to align it with other projects, there were no code changes.
 
 ## [Unreleased]
 

package/README.md

@@ -1,19 +1,49 @@
 # @adhd/apigen-core-client
 
-> The core apigen engine — TypeScript source → JSON Schema extraction, composition, and the plugin contract every apigen target implements.
+> The core apigen engine — TypeScript source → JSON Schema extraction, composition, the plugin contract, and the programmatic API for running live servers without code generation.
 
-## What it does
-
-`@adhd/apigen-core-client` reads TypeScript source files, derives JSON Schemas for each exported function's parameters and return type, and composes them with middleware-contributed envelope fields. It defines the **v1 `OutputPlugin`** contract for code generation and the **v2 `Plugin`** capability interface (target / layer / mount / envelope) for the full plugin lifecycle. Pure TypeScript — designed for Node and the browser, though ts-morph's type resolution is Node-only. Runtime dependencies: ts-morph, ts-json-schema-generator, pino, typescript, decimal.js, and @adhd/apigen-base-logical.
+`@adhd/apigen-core-client` reads TypeScript source files, derives JSON Schemas for each exported function's parameters and return type, composes them with middleware-contributed envelope fields, and provides the `OutputPlugin` contract that every plugin implements. It's the library you import when you want to **use apigen programmatically** — start MCP servers, Fastify HTTP services, or CLI tools directly from your Node.js code, without the CLI.
 
 Part of [apigen](../README.md). See the [apigen spec](../../../docs/apigen/SPEC.md) for the full architecture.
 
+---
+
+## Two paths: CLI or library
+
+apigen serves two audiences through the same engine. Which one are you?
+
+| You want to… | Use the CLI | Use this library |
+|---|---|---|
+| Start a server with one command, no code | `npx @adhd/apigen-cli run --source ./api.ts --type mcp --opt transport=sse` | — |
+| Generate a deployable project to disk | `npx @adhd/apigen-cli generate --source ./api.ts --type api-fastify --out-dir ./out` | — |
+| Embed a live server in your own Node.js process | — | `mcpPlugin.run({…})` from `@adhd/apigen-plugin-mcp` |
+| Build a custom deploy pipeline with lifecycles | — | `extract()` → `composeSchemas()` → `plugin.run({ signal })` |
+| Create a custom output plugin | Combined CLI + library | `OutputPlugin` / `Plugin` interface |
+| Serve a multi-language polyglot front | `npx @adhd/apigen-cli serve --source ./api.ts --source ./api.py --port 8080` | — (this is a CLI-only orchestration) |
+
+**The CLI is a thin wrapper** — every `apigen run --source ./api.ts --type mcp` call internally does exactly what you'd write in five lines of library code:
+
+| CLI command | Library equivalent |
+|---|---|
+| `apigen run --source ./api.ts --type mcp` | `mcpPlugin.run({ packages: [{ id, schemas, importPath: './api.ts', fns: mod }] })` |
+| `apigen run --source ./api.ts --type api-fastify --use health --use logger` | `apiFastifyPlugin.run({ packages: [...], options: { usePlugins: [healthPlugin, loggerPlugin] } })` |
+| `apigen run --source ./api.ts --type mcp --opt transport=sse --opt port=3100` | `mcpPlugin.run({ packages: [...], options: { transport: 'sse', port: 3100 } })` |
+| `apigen generate --source ./api.ts --type jsonschema --out-dir ./schema` | `jsonschemaPlugin.generate({ packages: [...], outputDir: './schema' })` |
+
+**The rest of this document focuses on the library path.** See the [CLI README](../../../entrypoint/apigen-cli/README.md) for CLI usage, or the [How-To: Running Servers](./docs/how-to/running-servers.md) for a step-by-step walkthrough.
+
+---
+
 ## Install
 
 ```bash
 npm install @adhd/apigen-core-client
+# Plus the plugins you want to run:
+npm install @adhd/apigen-plugin-mcp @adhd/apigen-plugin-api-fastify @adhd/apigen-plugin-openapi
 ```
 
+All packages are published to npm with `access: public`.
+
 ## Quickstart
 
 Extract canonical operation descriptors from a TypeScript file, then compose them with middleware envelope fields:
@@ -84,6 +114,229 @@ sourcesForPlugin({ language: 'ts' }, ['src/api.ts', 'src/api.py', 'README.md']);
 // => ['src/api.ts']
 ```
 
+---
+
+## Run Servers Programmatically
+
+The core use case for the library path: **extract operations from your TypeScript source, then start a live server — no code generation, no CLI.**
+
+Every plugin with a `run()` method receives a `RunInput` with three things: the composed schemas (for routing and validation), the live function references (your actual module imports), and an `AbortSignal` for graceful shutdown. The `run()` starts the server and returns a `Promise<void>` that resolves when the signal fires.
+
+### Start an MCP server (SSE transport)
+
+```ts
+import { extract, composeSchemas } from '@adhd/apigen-core-client';
+import { mcpPlugin } from '@adhd/apigen-plugin-mcp';
+
+// A function — no framework imports, no decorators, no annotations
+// (this lives in, say, services/api.ts)
+export async function greet(name: string): Promise<string> {
+  return `hello, ${name}!`;
+}
+```
+
+```ts
+import { extract, composeSchemas } from '@adhd/apigen-core-client';
+import { mcpPlugin } from '@adhd/apigen-plugin-mcp';
+
+async function startMcp(sourceFile: string) {
+  // 1. Extract operations from your TypeScript source
+  const ops = await extract({ sourceFile, namespace: 'demo' });
+
+  // 2. Build generated schemas (one per exported function)
+  const generated = {
+    metadata: { namespace: 'demo', 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 },
+      ])
+    ),
+  };
+
+  // 3. Compose with middleware envelope (empty for this example)
+  const schemas = composeSchemas(generated, []);
+
+  // 4. Import the source to get live function references
+  const mod = await import(sourceFile);
+
+  // 5. Start the MCP server — no codegen, live dispatch
+  const abort = new AbortController();
+  process.on('SIGINT', () => abort.abort());
+
+  await mcpPlugin.run!({
+    packages: [{
+      id: 'demo',
+      schemas,
+      importPath: sourceFile,
+      fns: mod,           // your actual exported functions
+      createClient: async () => ({}),
+    }],
+    outputDir: '',
+    options: {
+      transport: 'sse',   // stdio | sse | streaming-http
+      port: 3100,
+      host: '0.0.0.0',
+      // Override tool descriptions per function (optional):
+      // toolDescriptions: { greet: 'Say hello to a user' },
+    },
+    signal: abort.signal,
+    operations: ops,      // needed for --use mount plugins
+  });
+}
+```
+
+The MCP server is now live at `http://localhost:3100/sse` with `POST /messages?sessionId=...`. Every exported function in your source is an MCP tool — callable from Claude Desktop, Cursor, or any MCP host. **Equivalent CLI command:** `apigen run --source <file> --type mcp --opt transport=sse --opt port=3100`
+
+### Start a Fastify HTTP server (with OpenAPI docs)
+
+Add the OpenAPI plugin as a `--use` mount plugin — it contributes a `GET /_meta/openapi` endpoint that serves a live OpenAPI 3.1 document derived from your operations at request time.
+
+```ts
+import { extract, composeSchemas } from '@adhd/apigen-core-client';
+import { apiFastifyPlugin } from '@adhd/apigen-plugin-api-fastify';
+import { openapiPlugin } from '@adhd/apigen-plugin-openapi';
+import { healthPlugin } from '@adhd/apigen-plugin-health';
+import { loggerPlugin } from '@adhd/apigen-plugin-logger';
+
+async function startFastify(sourceFile: string) {
+  const ops = await extract({ sourceFile, namespace: 'api' });
+  const generated = {
+    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 schemas = composeSchemas(generated, []);
+  const mod = await import(sourceFile);
+
+  const abort = new AbortController();
+  process.on('SIGINT', () => abort.abort());
+
+  await apiFastifyPlugin.run!({
+    packages: [{
+      id: 'api',
+      schemas,
+      importPath: sourceFile,
+      fns: mod,
+      createClient: async () => ({}),
+    }],
+    outputDir: '',
+    options: {
+      port: 3200,
+      host: '0.0.0.0',
+      routePrefix: '',
+      // Mount plugins contributed as HTTP routes:
+      usePlugins: [openapiPlugin, healthPlugin, loggerPlugin],
+      // Per-plugin options:
+      // useOptions: { openapi: { title: 'My API', version: '1.0.0' } },
+    },
+    signal: abort.signal,
+    operations: ops,
+  });
+}
+```
+
+After startup:
+- `GET /api/greet?name=ada` — safe operations are GET (query params)
+- `POST /api/greet` — unsafe operations use `{"data":{…}}` body
+- `GET /_meta/health` — contributed by `healthPlugin`
+- `GET /_meta/openapi` — contributed by `openapiPlugin`, serves a live OpenAPI 3.1 spec
+
+**Equivalent CLI command:** `apigen run --source <file> --type api-fastify --opt port=3200 --use openapi --use health --use logger`
+
+### Run both servers side by side
+
+```ts
+async function startAll(sourceFile: string) {
+  const ops = await extract({ sourceFile, namespace: 'svc' });
+  const generated = {
+    metadata: { namespace: 'svc', 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 schemas = composeSchemas(generated, []);
+  const mod = await import(sourceFile);
+  const pkg = [{
+    id: 'svc',
+    schemas,
+    importPath: sourceFile,
+    fns: mod,
+    createClient: async () => ({}),
+  }];
+
+  const abort = new AbortController();
+  process.on('SIGINT', () => abort.abort());
+
+  await Promise.all([
+    mcpPlugin.run!({ packages: pkg, outputDir: '', options: { transport: 'sse', port: 3100 }, signal: abort.signal, operations: ops }),
+    apiFastifyPlugin.run!({ packages: pkg, outputDir: '', options: { port: 3200, usePlugins: [openapiPlugin, healthPlugin] }, signal: abort.signal, operations: ops }),
+  ]);
+}
+```
+
+One source file, two servers, both live from the same import.
+
+### Integrate with your deploy system
+
+Because `run()` returns a `Promise<void>` that resolves on `signal.abort`, you can wrap it in any lifecycle model — containers, process managers, custom mesh registrations.
+
+```ts
+export async function deployService(config: {
+  source: string;
+  port: number;
+  type: 'mcp' | 'api-fastify';
+}) {
+  const ops = await extract({ sourceFile: config.source, namespace: 'deploy' });
+  /* build schemas, import module — same pattern as above */
+
+  const plugin = config.type === 'mcp' ? mcpPlugin : apiFastifyPlugin;
+  const opts = config.type === 'mcp'
+    ? { transport: 'sse', port: config.port }
+    : { port: config.port, usePlugins: [openapiPlugin, healthPlugin] };
+
+  const abort = new AbortController();
+  // Your deployer hook: register with service mesh, health probe, etc.
+  const server = plugin.run!({ packages, outputDir: '', options: opts, signal: abort.signal });
+  return { abort, running: server }; // call abort.abort() to stop gracefully
+}
+```
+
+### Options reference for `run()`
+
+The `options` object in `RunInput` accepts plugin-specific keys. Here are the common ones:
+
+| Key | Plugin(s) | Type | Default | Description |
+|-----|-----------|------|---------|-------------|
+| `transport` | `mcp` | `'stdio' \| 'sse' \| 'streaming-http'` | `'stdio'` | MCP transport protocol |
+| `port` | `mcp` (HTTP), `api-fastify` | `number` | `3000` | Listen port |
+| `host` | All | `string` | `'127.0.0.1'` | Bind address |
+| `routePrefix` | `api-fastify` | `string` | `''` | Path prefix before `/<ns>/<fn>` |
+| `usePlugins` | All `run()` targets | `Plugin[]` | `[]` | Layer/mount/envelope plugins to compose |
+| `toolDescriptions` | `mcp` | `Record<string, string>` | `{}` | Per-tool description overrides |
+
+### Plugin cheat sheet
+
+| Plugin | Package | `run()` | `generate()` | What it builds |
+|--------|---------|---------|--------------|----------------|
+| `mcpPlugin` | `@adhd/apigen-plugin-mcp` | ✓ | ✓ | MCP server (stdio/SSE/streaming-http) |
+| `apiFastifyPlugin` | `@adhd/apigen-plugin-api-fastify` | ✓ | ✓ | Fastify HTTP server |
+| `apiExpressPlugin` | `@adhd/apigen-plugin-api-express` | ✓ | ✓ | Express HTTP server |
+| `cliPlugin` | `@adhd/apigen-plugin-cli-output` | ✓ | ✓ | Commander CLI tool |
+| `jsonschemaPlugin` | `@adhd/apigen-plugin-jsonschema` | — | ✓ | JSON Schema files |
+| `openapiPlugin` | `@adhd/apigen-plugin-openapi` | — | — | Mount: `GET /_meta/openapi` |
+| `healthPlugin` | `@adhd/apigen-plugin-health` | — | — | Mount: `GET /_meta/health` |
+| `loggerPlugin` | `@adhd/apigen-plugin-logger` | — | — | Layer: per-operation logging |
+
+> See the [How-To: Running Servers](./docs/how-to/running-servers.md) for a complete walkthrough with all three transports and deployment patterns.
+
 ## Features
 
 ### v2 Symbol-Based Extraction
@@ -223,6 +476,8 @@ Recognized extensions: `.ts/.tsx/.mts/.cts` → `ts`, `.py` → `py`, `.rs` →
 
 ## How-To Guides
 
+- [Writing Source Files for apigen](./docs/how-to/writing-source-files.md) — How to structure your TypeScript source: naming, exports, types, and what makes a good API surface
+- [Running Servers Programmatically](./docs/how-to/running-servers.md) — Start MCP, Fastify, or Express servers from your own Node.js process
 - [End-to-End Extraction Pipeline](./docs/how-to/extraction-pipeline.md) — From source file to composed schemas
 - [Building apigen Plugins](./docs/how-to/building-plugins.md) — v1 OutputPlugin and v2 Plugin development
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@adhd/apigen-core-client",
-  "version": "0.1.0",
+  "version": "0.1.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.0.1"
+    "@adhd/apigen-base-logical": "^0.0.2"
   },
   "main": "./index.js",
   "module": "./index.mjs",