@adhd/apigen-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog — `@adhd/apigen-*`
+
+All notable changes to the apigen toolchain (`@adhd/apigen-cli`, `-core`, `-runtime`,
+`-logical`, plugins, and generators). Format based on
+[Keep a Changelog](https://keepachangelog.com/); this project uses
+[Semantic Versioning](https://semver.org/).
+
+Open/actionable work lives in [`/BACKLOG.md`](../../BACKLOG.md); plan-level design in
+[`docs/plan/apigen-logical-types/DESIGN.md`](../../docs/plan/apigen-logical-types/DESIGN.md).
+
+---
+
+## [Unreleased] — apigen-logical-types (PENDING)
+
+> Cross-language serialization of non-JSON-native types and custom classes. Tracked by the
+> `apigen-logical-types` plan-state-machine plan (DESIGN.md §1–§18). **Not yet released** —
+> gated on the plan reaching its Definition of Done + publishing the apigen v2 packages.
+
+### Added
+- **Rich types now round-trip through `run`/`generate` with no new flags.** Functions whose
+  signatures use **`Date`, `int64`/`BigInt`, `Decimal`, `bytes`, `UUID`, `Map`, `Set`,
+  tuples**, or **user-defined classes** are exposed and (de)serialized correctly across
+  MCP / HTTP / CLI. Previously these silently broke (e.g. `Date` extracted as `{}`, inputs
+  never rehydrated). *(dod.1/dod.2)*
+- **Custom-class round-trips, including cross-host.** A `User` class survives
+  `TS → wire → Python → wire → TS` and is reconstructed as a **real instance on both hosts**
+  (not a prototype-stripped object). Discriminated unions (`Dog | Cat`) dispatch by wire
+  discriminator. *(dod.3/dod.4)*
+- **Meaningful MCP/OpenAPI schemas.** `tools/list` and the OpenAPI emitter now carry proper
+  `format` (`date-time`, `int64`, `uuid`, `byte`, …) and named `$ref` for classes instead of
+  empty `{}` — so MCP clients (and the driving model) and generated OpenAPI clients in any
+  language get real, validatable types.
+- **Idiomatic generated clients.** Generated TS clients emit `Date`, Python clients emit
+  `datetime` (via `x-apigen-*` codegen hints) — consumers get typed values, not raw ISO
+  strings to hand-parse.
+- **Cross-host interop for rich types.** Expose a TS function, call it from a Python client
+  (or vice versa), with Date/Decimal/classes preserved — guaranteed **byte-equal** by a
+  conformance-vector matrix (a TCK every host must pass). *(dod.5)*
+- **New developer tooling:** an `apigen-nx` **`host` generator** to scaffold a new host
+  language (a template column + conformance harness), and a workspace
+  **`nx run …:conformance`** target that verifies the cross-host matrix.
+- **New package `@adhd/apigen-logical`** — the single source of truth: canonical wire table +
+  per-language native-hook template columns + generate-time emitter + run-mode closure builder.
+- **Optional knob `--opt logical.decimal=branded|lib`** — zero-dependency branded-string mode
+  vs a real `Decimal` runtime type.
+
+### Changed
+- `generate` emits a **standalone-runnable** `package.json`: rich-type deps (e.g. `decimal.js`)
+  are added per-surface (only the types actually used), so generated output runs after a plain
+  `npm install` — `--link-workspace` no longer required for the publish path.
+  *(dod.10 — resolves BUG-APIGEN-002 dep-manifest slice)*
+- Validation actually enforces formats — the validate-Layer wires `ajv-formats`, so a malformed
+  `date-time` (`2099-02-30`) is rejected instead of silently passing. *(dod.6)*
+
+### Fixed
+- **BUG-APIGEN-005** — language-specific serializable types (`Date → {}`, lost precision,
+  un-rehydrated inputs) and custom-class identity loss. *(this feature)*
+- **BUG-APIGEN-004** — `run`/`generate` now **fail fast** with an actionable message on 0
+  extracted functions and on a used rich type whose optional dependency is missing
+  (e.g. *"function `quote` takes a Decimal; install `decimal.js`"*), instead of a cryptic
+  `ERR_MODULE_NOT_FOUND`. *(dod.9)*
+
+### Engineering notes
+- Codegen-first design: encode uses each language's **native hook**
+  (`toJSON` / `JSONEncoder.default` / serde / Jackson / `MarshalJSON`); decode is schema-driven
+  glue emitted once by the generator — **no per-host runtime interpreter**.
+- Languages with native-hook mappings resolved: **TypeScript/JS, Python, Rust, Go, Java**.
+  3rd-party deps introduced: Python 0, Java 1, TS 1, Go 2, Rust ~6 (all pinned, minimal-per-surface).
+
+---
+
+## [1.0.0] — apigen v2 (released to disk, publish pending)
+
+### Added
+- apigen v2 — an 18-package TypeScript→API toolchain. Takes any unmodified `.ts` file and
+  exposes its exports as an **MCP server, HTTP API, or CLI** without source changes
+  (`apigen-cli run/generate`). Canonical Operation descriptor (JSON-Schema-2020-12 IR),
+  symbol/class extractor (ts-morph), v2 plugin interface, Layer harness + streaming + single
+  canonical dispatch path, `mcp`/`api-fastify`/`api-express`/`cli` plugins, `apigen-nx`
+  generator, and a real Python host passing the conformance vectors.
+  Plan: `docs/plan/apigen-client-generation` (46/46 states, final audit 117/117, DoD confirmed).
+
+### Fixed
+- **BUG-APIGEN-001** — ctx-param functions returned wrong results via generated servers
+  (`hasCtx` now threaded through extraction→dispatch).
+- **BUG-APIGEN-002** — generated output portability via the Option-A publish model + default-off
+  `--link-workspace` (dep-manifest extension for rich types tracked in Unreleased above).
+- **BUG-APIGEN-003** — MCP SSE transport reachable (stdio + streaming-http + sse); probe
+  hardened (`waitForPort` 15s→60s for cold compiles).

package/README.md

@@ -0,0 +1,146 @@
+# @adhd/apigen-cli
+
+The user-facing CLI for **apigen** — take any `.ts` file and expose its exports as an
+**MCP server, HTTP API (Fastify/Express), CLI, or JSON Schema**, with **zero changes to
+the source**. Functions are the single source of truth; everything is derived.
+
+> This documents the **v1** (TypeScript-only) implementation that ships today. The
+> transport-neutral, polyglot **v2** standard is specified in
+> [`docs/apigen/SPEC.md`](../../../docs/apigen/SPEC.md) and is in active build-out.
+
+---
+
+## Install / launch
+
+The CLI is not bundled to `dist` by default. Use whichever fits:
+
+```bash
+cd <repo-root>
+
+# A) Dev — run the TypeScript entry directly (no build):
+alias apigen='npx tsx packages/apigen/cli/src/index.ts'
+
+# B) Bundled bin — build once, then run dist (bin name: apigen-cli):
+npx nx build apigen-cli
+#   → node packages/apigen/cli/dist/index.js
+```
+
+**Commands:** `run`, `generate`, `run-registry`, `generate-registry`
+**`--type` (target plugin):** `mcp` · `api-fastify` · `api-express` · `cli` · `jsonschema`
+**Server knobs:** passed through repeatable `--opt key=value`.
+
+A ready fixture lives at `packages/apigen/cli/src/test/fixtures/api.ts` (`getUser`, `sendEmail`),
+used in the examples below.
+
+---
+
+## Run a live server — `run`
+
+```bash
+# MCP over stdio (default transport)
+apigen run --source packages/apigen/cli/src/test/fixtures/api.ts --type mcp
+
+# MCP over HTTP transports
+apigen run --source .../api.ts --type mcp --opt transport=sse             --opt port=3000
+apigen run --source .../api.ts --type mcp --opt transport=streaming-http  --opt port=3000
+
+# HTTP API (Fastify or Express) — --namespace sets the route prefix segment
+apigen run --source packages/apigen/cli/src/test/fixtures/api.ts \
+  --type api-fastify --namespace api --opt port=3000
+```
+
+Call an HTTP server — **method must be uppercase `POST`**, arguments wrapped in
+`{"data":{…}}` (the request envelope), route is `/<namespace>/<fn>`:
+
+```bash
+curl -X POST http://127.0.0.1:3000/api/getUser \
+  -H 'content-type: application/json' \
+  -d '{"data":{"userId":"abc"}}'
+# → {"id":"abc"}
+```
+
+### `--opt` keys read by the server plugins
+
+| key | targets | default | meaning |
+|---|---|---|---|
+| `transport` | `mcp` | `stdio` | `stdio` \| `sse` \| `streaming-http` |
+| `port` | `mcp` (http transports), `api-fastify`, `api-express` | `3000` | listen port |
+| `host` | `mcp` (http), `api-fastify`, `api-express` | `127.0.0.1` | bind host |
+| `routePrefix` | `api-fastify`, `api-express` | `""` | path prefix before `/<namespace>/<fn>` |
+
+`mcp` over `stdio` keeps **stdout** clean for the JSON-RPC channel — all logs go to stderr.
+
+---
+
+## Generate to disk — `generate`
+
+```bash
+# MCP server source
+apigen generate --source packages/apigen/cli/src/test/fixtures/api.ts \
+  --type mcp --out-dir /tmp/apigen-out
+node /tmp/apigen-out/server.ts          # or: npx tsx /tmp/apigen-out/server.ts
+
+apigen generate --source .../api.ts --type api-fastify --out-dir /tmp/out-http    # routes.ts
+apigen generate --source .../api.ts --type cli         --out-dir /tmp/out-cli     # cli.ts
+apigen generate --source .../api.ts --type jsonschema  --out-dir /tmp/out-schema  # *.json
+```
+
+Generated servers import `dispatch`/`buildFnTable` from `@adhd/apigen-runtime` — no inlined
+dispatch logic — so disk output behaves identically to `run`.
+
+---
+
+## Multi-package — `run-registry` / `generate-registry`
+
+Discover packages in a directory by **nx tag** and wire them into one surface:
+
+```bash
+apigen run-registry --packages-dir packages/apigen/cli/src/test/fixtures/registry \
+  --tag api --type mcp
+apigen generate-registry --packages-dir <dir> --tag api --type mcp --out-dir /tmp/reg-out
+```
+
+`--tag` / `--exclude-tag` are repeatable; untagged exports stay out of the surface.
+
+---
+
+## Flags
+
+### Export shapes — `--export`
+- *(omit)* — named exports (`export function f`, `export const f = …`).
+- `--export default` — a default-exported function/object.
+- `--export <objName>` — a named object whose properties are the operations.
+
+> **Known v1 limitations (tracked, fixed by v2):** `export { x as y }` aliases,
+> anonymous default exports, and CJS-source files mis-name routes because v1 names by the
+> *declaration* identifier rather than the *exported symbol*. v2 (`docs/apigen/SPEC.md`)
+> names by exported symbol and closes these.
+
+### Resolution
+- `--tsconfig <path>` — explicit tsconfig; otherwise the nearest one, else a builtin default.
+- `--namespace <name>` — the package id / route prefix segment. Defaults to the tsconfig
+  folder name, falling back to the source file's folder.
+
+### Plugin options
+- `--opt key=value` — repeatable; forwarded to the target plugin (see table above).
+
+### Logging (stderr — stdout stays protocol-clean)
+- `--log-level trace|debug|info|warn|error|fatal|silent` (env `APIGEN_LOG_LEVEL`)
+- `--log-format json|pretty` (env `APIGEN_LOG_FORMAT`)
+- `--log-file <path>` — write logs to a file instead of stderr (env `APIGEN_LOG_FILE`)
+
+Lifecycle logged: compile → server start → host/port → route/tool list → per-request → shutdown.
+
+---
+
+## Nx integration
+
+- Cache-aware generate target: `@adhd/apigen-nx:generate` (see [`../nx`](../nx)).
+- Scaffold a new output plugin: `nx g @adhd/apigen-nx:plugin <name>`.
+
+## Develop
+
+```bash
+npx nx build apigen-cli      # bundle
+npx nx test  apigen-cli      # Vitest (unit + integration)
+```

package/default-tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}

package/index.d.ts

@@ -0,0 +1 @@
+export {};