@contractkit/plugin-typescript 0.33.0 → 0.33.1

package/.turbo/turbo-build$colon$ci.log

@@ -7,7 +7,7 @@ $ tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly
 ESM Build start
 ESM dist/index.js     210.74 KB
 ESM dist/index.js.map 480.07 KB
-ESM ⚡️ Build success in 478ms
+ESM ⚡️ Build success in 359ms
 DTS Build start
-DTS ⚡️ Build success in 3983ms
+DTS ⚡️ Build success in 6133ms
 DTS dist/index.d.ts 5.14 KB

package/.turbo/turbo-test$colon$ci.log

@@ -3,19 +3,19 @@ $ vitest run --coverage
  RUN  v4.1.5 /home/runner/work/ContractKit/ContractKit/packages/plugin-typescript
       Coverage enabled with v8
 
- ✓ tests/codegen-contract.test.ts (140 tests) 214ms
- ✓ tests/codegen-operation.test.ts (155 tests) 270ms
- ✓ tests/codegen-sdk.test.ts (159 tests) 239ms
- ✓ tests/codegen-server.test.ts (30 tests) 84ms
- ✓ tests/codegen-plain-types.test.ts (66 tests) 82ms
- ✓ tests/pipeline.test.ts (30 tests) 279ms
- ✓ tests/codegen-mcp.test.ts (24 tests) 31ms
- ✓ tests/escaping-security.test.ts (18 tests) 21ms
+ ✓ tests/codegen-contract.test.ts (140 tests) 154ms
+ ✓ tests/codegen-operation.test.ts (155 tests) 220ms
+ ✓ tests/codegen-sdk.test.ts (159 tests) 227ms
+ ✓ tests/codegen-plain-types.test.ts (66 tests) 61ms
+ ✓ tests/codegen-server.test.ts (30 tests) 143ms
+ ✓ tests/pipeline.test.ts (30 tests) 269ms
+ ✓ tests/codegen-mcp.test.ts (24 tests) 57ms
+ ✓ tests/escaping-security.test.ts (18 tests) 24ms
 
  Test Files  8 passed (8)
       Tests  622 passed (622)
-   Start at  17:30:03
-   Duration  8.38s (transform 4.61s, setup 0ms, import 16.31s, tests 1.22s, environment 1ms)
+   Start at  18:42:58
+   Duration  10.53s (transform 7.47s, setup 0ms, import 19.72s, tests 1.15s, environment 1ms)
 
  % Coverage report from v8
 -------------------|---------|----------|---------|---------|-------------------

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @contractkit/contractkit-plugin-typescript
 
+## 0.33.1
+
+### Patch Changes
+
+- ffb2ec6: Ship an `llms.txt` in every package, so an AI assistant reading the package out of `node_modules` gets its exact name, a config block with real key names, the full option table, the programmatic API, and the mistakes specific to it — without needing the repo checked out.
+
+    Correct several documented snippets that could not work as written. The five plugin READMEs named packages that do not exist (`@contractkit/contractkit-plugin-*`, and `-python-sdk` for the Python plugin) in both their install commands and their `contractkit.config.json` keys. `@contractkit/core`'s README exported `Diagnostics` and `validateOperation`, which are really `DiagnosticCollector` and `validateOp`, and gave the wrong signatures for three validation passes. `@contractkit/cli`'s README documented the OpenAPI importer as `contractkit openapi-to-ck --input <spec>`; it is `contractkit import-openapi <spec>`, with the path positional. `@contractkit/plugin-openapi` described its output as OpenAPI 3.0, but it emits 3.1.
+
+- Updated dependencies [ffb2ec6]
+    - @contractkit/core@0.28.1
+
 ## 0.33.0
 
 ### Minor Changes

package/README.md

@@ -1,11 +1,11 @@
-# @contractkit/contractkit-plugin-typescript
+# @contractkit/plugin-typescript
 
 ContractKit plugin that generates TypeScript output from `.ck` contract files. Covers all server-side and client-side TypeScript needs: Koa routers, SDK clients, Zod schemas, and plain TypeScript interfaces.
 
 ## Installation
 
 ```bash
-pnpm add @contractkit/contractkit-plugin-typescript
+pnpm add @contractkit/plugin-typescript
 ```
 
 ## Configuration
@@ -15,7 +15,7 @@ Add the plugin to `contractkit.config.json`. Each sub-config is independent —
 ```json
 {
   "plugins": {
-    "@contractkit/contractkit-plugin-typescript": {
+    "@contractkit/plugin-typescript": {
       "server": {
         "baseDir": "apps/api/",
         "zod": true,
@@ -170,7 +170,7 @@ statuses fall into which set.
 ## Programmatic use
 
 ```typescript
-import { createTypescriptPlugin } from '@contractkit/contractkit-plugin-typescript';
+import { createTypescriptPlugin } from '@contractkit/plugin-typescript';
 
 const plugin = createTypescriptPlugin({
   server: {

package/llms.txt

@@ -0,0 +1,111 @@
+# @contractkit/plugin-typescript
+
+> ContractKit's TypeScript code generator. From the same `.ck` files it emits Koa routers, a
+> TypeScript SDK client, Zod schemas, plain TypeScript types, and MCP tool handlers. Five
+> independent sub-generators, each enabled by the presence of its config key.
+
+Loaded by `@contractkit/cli` through `contractkit.config.json`. It consumes the AST produced by
+`@contractkit/core`; you do not call it directly in a normal build.
+
+## Install
+
+```bash
+pnpm add -D @contractkit/cli @contractkit/plugin-typescript
+```
+
+## Configure
+
+`plugins` is an **object** keyed by package name, not an array. Each sub-config is independent —
+include only the ones you want; omitting a key disables that sub-generator entirely.
+
+```json
+{
+    "rootDir": ".",
+    "patterns": ["contracts/**/*.ck"],
+    "plugins": {
+        "@contractkit/plugin-typescript": {
+            "server": {
+                "baseDir": "apps/api/",
+                "zod": true,
+                "output": {
+                    "routes": "src/routes/{filename}.router.ts",
+                    "types": "src/modules/{area}/types/{filename}.ts"
+                },
+                "servicePathTemplate": "#modules/{module}/{module}.service.js"
+            },
+            "sdk": {
+                "baseDir": "packages/sdk/",
+                "name": "acme",
+                "zod": true,
+                "output": {
+                    "sdk": "src/{name}.sdk.ts",
+                    "types": "src/{area}/types/{filename}.ts",
+                    "clients": "src/{area}/{filename}.client.ts"
+                }
+            },
+            "zod": { "baseDir": "packages/schemas/", "output": "{filename}.schema.ts" },
+            "types": { "baseDir": "packages/types/", "output": "{filename}.types.ts" }
+        }
+    }
+}
+```
+
+Path templates accept `{filename}`, `{dir}`, `{area}`, and — in `sdk.output.sdk` — `{name}`.
+
+## Sub-configs
+
+| Key | Emits |
+| --- | --- |
+| `server` | Koa routers from `operation` declarations, plus the type or Zod files they import |
+| `sdk` | The SDK class, per-area operation clients, and their types |
+| `zod` | Standalone Zod schemas, independent of `server` and `sdk` |
+| `types` | Standalone plain TypeScript types, independent of `server` and `sdk` |
+| `mcp` | Per-file MCP tool handlers, an aggregator, and an optional `POST /mcp` route |
+
+Options worth knowing:
+
+- `server.zod` / `sdk.zod` — when true, `output.types` emits Zod schema files instead of plain
+  interfaces. Off by default.
+- `server.validateResponses` — each handler re-parses the service result through its declared
+  response schema before writing `ctx.body`. **Requires `zod: true`**; without it `output.types`
+  emits plain interfaces, which are types with no runtime value to parse through. A body that
+  transitively references a model with `format(input=…)`/`format(output=…)`, and a status whose
+  several mimes carry different body types, are left unvalidated.
+- `sdk.scaffold` — write-once starter `package.json` and `tsconfig.json` at the SDK `baseDir`, so
+  the generated output is a publishable package on its own. Never overwritten once created, so your
+  edits survive. Dependency ranges are derived from the contracts.
+- `includeInternal` on `server`/`sdk` — whether operations marked `internal` get handlers or client
+  methods. Defaults to `true` for `server`, `false` for `sdk`.
+- `types.target` — `'client'` (default) or `'server'`; decides whether `binary` renders as `Blob`
+  or `Buffer`. The `server` and `sdk` sub-generators set it themselves.
+- `mcp.output.types` must point at **Zod schema** files, not plain types — tools need a runtime
+  schema for argument validation and `z.toJSONSchema`. It falls back to `server.output.types` (when
+  `server.zod`) or the `zod` sub-config's output.
+
+## Programmatic use
+
+```typescript
+import { createTypescriptPlugin } from '@contractkit/plugin-typescript';
+
+const plugin = createTypescriptPlugin({ types: { output: '{filename}.types.ts' } }, process.cwd());
+```
+
+Prefer the default export when loading through `contractkit.config.json`; the factory is for
+building the plugin in code (tests, custom build scripts).
+
+## Gotchas
+
+- The four output sub-configs are independent. `zod: true` **inside** `server` is not the same thing
+  as the top-level `zod` sub-config: the first changes what `server.output.types` emits, the second
+  adds a separate standalone schema output.
+- `validateResponses` silently does nothing useful without `zod: true`.
+- Which statuses a router writes and which the SDK throws is decided by the contract, not by this
+  plugin — a `404(documented)` is the client's error contract, a bare `404:` is a status the service
+  produces. See the response-set helpers in `@contractkit/core`.
+
+## More
+
+- README: https://github.com/MaroonedSoftware/contractkit/blob/main/packages/plugin-typescript/README.md
+- Configuration: https://github.com/MaroonedSoftware/contractkit/blob/main/docs/config.md
+- SDK generation and subclient grouping: https://github.com/MaroonedSoftware/contractkit/blob/main/docs/tooling.md
+- Full usage guide: https://github.com/MaroonedSoftware/contractkit/blob/main/llms-full.txt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractkit/plugin-typescript",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "description": "ContractKit built-in plugin: TypeScript codegen (SDK clients, Koa routers, Zod schemas, plain types)",
   "license": "MIT",
   "author": {
@@ -27,11 +27,11 @@
     ".": "./dist/index.js"
   },
   "dependencies": {
-    "@contractkit/core": "0.28.0"
+    "@contractkit/core": "0.28.1"
   },
   "devDependencies": {
-    "@repo/config-typescript": "0.1.0",
-    "@repo/config-eslint": "0.3.1"
+    "@repo/config-eslint": "0.3.1",
+    "@repo/config-typescript": "0.1.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly --declaration",