@luckystack/devkit 0.10.2 → 0.11.0

package/docs/type-map-generation.md

@@ -1,422 +1,9 @@
-# Type Map Generation (`generateTypeMapFile` + emitters)
+# Type-map generation
 
-> Dev-only. `generateTypeMapFile()` runs at build time and during hot reload. The generated artifacts (`apiTypes.generated.ts`, `apiInputSchemas.generated.ts`, `apiDocs.generated.json`) ship with the project source; production servers read them as compiled TypeScript / JSON, never re-running the emitter.
+Generated route types, runtime schemas and API documentation must describe the same source route contract. TypeScript source is the authority; generated files are artifacts, not independent hand-maintained interfaces. Transport contracts must reject unsafe shapes rather than implying values can cross JSON or socket boundaries unchanged. A source missing from the compiler Program or an unresolved symbol deserves an explicit diagnostic, not a silent fallback that widens validation.
 
-The type-map generator is the canonical source of truth for typed `apiRequest` / `syncRequest` calls. It walks every `_api/` and `_sync/` file under `srcDir`, runs the TypeChecker-backed extractors to produce fully-expanded inline types, emits a single typed map plus a Zod schema file plus a docs JSON, and validates that no unresolved type identifiers leaked through.
+The emitter detects ambiguous route names before writing contradictory maps. Deep type expansion is bounded so pathological types cannot stall every generation. Development may report a loose schema when strict conversion is impossible, but its diagnostic must remain visible to the developer. Consult the emitter implementation for artifact names, current extraction rules, and schema policy. See `ts-program-cache.md` for the reason caches are reused and invalidated.
 
-`generateTypeMapFile(options?)` is the only public entry point; the helpers under `typeMap/` are internal building blocks.
+**An absent optional sync side is not a fallback.** The client handler of a sync route is optional by design (it runs once per recipient, so a pass-through one should not exist), and an absent side produces the same default text as a present side that declares no shape. Counting it as degraded extraction made the diagnostics gate push authors toward handlers the architecture forbids, so the generator records which sides exist and the diagnostics skip only the missing side's own field — after the thrown-extraction check, which always reports. Keep the exception that narrow: widening it per route, to API defaults, or ahead of the throw check would again make a lost shape indistinguishable from an undeclared one (ADR 0057). Source: `../src/typeMap/emitterArtifacts.ts`.
 
----
-
-## Pipeline order
-
-```typescript
-export const generateTypeMapFile = (options: GenerateTypeMapOptions = {}): void => {
-  const { quiet = false } = options;
-
-  assertValidRouteNaming({ srcDir: getSrcDir(), context: 'generating API/sync type maps' });
-  assertNoDuplicateNormalizedRouteKeys({ srcDir: getSrcDir(), context: 'generating API/sync type maps' });
-
-  invalidateProgramCache();
-  namedImports.clear();
-  defaultImports.clear();
-
-  // 1. Walk apiFiles, extract per-route input/output/stream/meta
-  // 2. Walk sync server/client files, join by `pagePath/syncName/version`
-  // 3. Build the Functions interface from the server functions tree
-  // 4. Abort on unresolved type symbols
-  // 5. Build + write the three artifacts
-
-  // ... (see breakdown below) ...
-};
-```
-
-`assertValidRouteNaming` and `assertNoDuplicateNormalizedRouteKeys` come first so a typo aborts before the expensive TypeScript Program build. `invalidateProgramCache()` is mandatory at the top — the generator is called both from build scripts (fresh process, no cache anyway) and from hot reload (cache may be warm but a file just changed).
-
-`namedImports` and `defaultImports` are module-level `Map`s that accumulate import statements for the generated file. They are cleared on each run so retries don't leak stale imports.
-
----
-
-## API extraction loop
-
-```typescript
-const apiFiles = findAllApiFiles(getSrcDir());
-const typesByPage = new Map<string, Map<string, { input, output, stream, method, rateLimit, auth, version }>>();
-const unresolvedTypeAliases = new Set<string>();
-
-for (const filePath of apiFiles) {
-  const pagePath = extractPagePath(filePath);
-  const apiName = extractApiName(filePath);
-  const apiVersion = extractApiVersion(filePath);
-  if (!pagePath || !apiName) continue;
-
-  const inputTypeResult = getInputTypeDetailsFromFile(filePath);
-  const outputTypeResult = getOutputTypeDetailsFromFile(filePath);
-  const streamTypeResult = getApiStreamPayloadTypeDetailsFromFile(filePath);
-  const httpMethod = extractHttpMethod(filePath, apiName);
-  const rateLimit = extractRateLimit(filePath);
-  const auth = extractAuth(filePath);
-
-  for (const symbol of [
-    ...inputTypeResult.unresolvedSymbols,
-    ...outputTypeResult.unresolvedSymbols,
-    ...streamTypeResult.unresolvedSymbols,
-  ]) {
-    if (!symbol.importPath) {
-      unresolvedTypeAliases.add(symbol.name);
-      console.error(`[TypeMapGenerator] Unresolved API type (${pagePath}/${apiName}/${apiVersion}): ${symbol.name}`);
-      continue;
-    }
-    getOrInit(namedImports, symbol.importPath, () => new Set<string>()).add(symbol.name);
-  }
-
-  getOrInit(typesByPage, pagePath, () => new Map()).set(`${apiName}@${apiVersion}`, {
-    input: inputTypeResult.text,
-    output: outputTypeResult.text,
-    stream: streamTypeResult.text,
-    method: httpMethod,
-    rateLimit,
-    auth,
-    version: apiVersion,
-  });
-}
-```
-
-Per-file extractor map (`typeMap/extractors.ts`):
-
-| Function | Returns | Used for |
-|---|---|---|
-| `getInputTypeDetailsFromFile(filePath)` | `{ text, unresolvedSymbols }` | API `data` parameter type |
-| `getOutputTypeDetailsFromFile(filePath)` | `{ text, unresolvedSymbols }` | API return type (the `result` member of `{ status: 'success', result: ... }`) |
-| `getApiStreamPayloadTypeDetailsFromFile(filePath)` | `{ text, unresolvedSymbols }` | API stream emitter payload (defaults to `never`) |
-| `getSyncClientDataTypeDetailsFromFile(filePath)` | `{ text, unresolvedSymbols }` | sync `clientInput` (the `data` param of `_server_v<n>.ts`, or the client-side type if no server file) |
-| `getSyncClientOutputTypeDetailsFromFile(filePath)` | `{ text, unresolvedSymbols }` | sync `clientOutput` returned by `_client_v<n>.ts` |
-| `getSyncServerOutputTypeDetailsFromFile(filePath)` | `{ text, unresolvedSymbols }` | sync `serverOutput` returned by `_server_v<n>.ts` |
-| `getSyncServerStreamPayloadTypeDetailsFromFile(filePath)` | `{ text, unresolvedSymbols }` | sync server stream emitter payload |
-| `getSyncClientStreamPayloadTypeDetailsFromFile(filePath)` | `{ text, unresolvedSymbols }` | sync client stream emitter payload |
-
-### Wire contract
-
-- Outputs and stream payloads describe serialized values: `Date -> string`,
-  `toJSON() -> return type`, omitted object values disappear/become optional, and
-  omitted array/tuple slots become `null`.
-- Binary values (`Buffer`, `ArrayBuffer`, typed arrays, Blob/File) abort generation.
-  Socket.io delivers them as binary attachments while HTTP emits JSON; one shared
-  route map cannot truthfully describe both. Return an explicit DTO/base64 string
-  or use a transport-specific custom route.
-- Inputs remain unprojected for fail-closed validation, but `Date` annotations are
-  rejected. Declare an ISO `string`, validate it, and convert explicitly in the
-  handler. Otherwise the source handler promises `Date` while JSON delivers a
-  string.
-- Extraction throws for API `stream` and sync `serverStream` / `clientStream` are
-  persisted as `extraction-error` diagnostics just like input/output failures.
-- A sync side that does not exist on disk is not a diagnostic. Its default output
-  text is indistinguishable from a present-but-shapeless side, so the entry also
-  carries whether each side was found; only the missing side's own field is
-  suppressed, and only after the throw check has passed.
-
-Two of these are also exported from the package root for use by the dev loader:
-
-```typescript
-export { getInputTypeFromFile, getSyncClientDataType } from './typeMap/extractors';
-```
-
-The loader uses them on every `upsertApiFromFile` / `upsertSyncFromFile` to attach an `inputType` string to the live route entry; this string later feeds `runtimeTypeValidation` in `@luckystack/core` via `resolveRuntimeTypeText` (see `runtime-type-resolver.md`).
-
-### Route metadata (`typeMap/routeMeta.ts`)
-
-```typescript
-export const extractApiName(filePath: string): string | null;
-export const extractApiVersion(filePath: string): string;
-export const extractPagePath(filePath: string): string | null;
-export const extractSyncName(filePath: string): string | null;
-export const extractSyncPagePath(filePath: string): string | null;
-export const extractSyncVersion(filePath: string): string;
-```
-
-Filename + path segments -> the components that compose route keys. `pagePath === 'root'` (or `''` for syncs) means the route lives at the project root, not under a page directory.
-
-### API meta (`typeMap/apiMeta.ts`)
-
-```typescript
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
-export const extractHttpMethod = (filePath: string, apiName: string): HttpMethod;
-export const extractRateLimit = (filePath: string): number | false | undefined;
-export const extractAuth = (filePath: string): { login: boolean; additional?: Record<string, unknown>[] };
-```
-
-Each one walks the source file's top-level statements looking for the matching `export const`. If the API doesn't export a value, sensible defaults apply:
-
-- `httpMethod` falls back to `inferHttpMethod(apiName)` (re-exported from `@luckystack/core`) — naming-based inference (e.g. `get*` -> `GET`, `delete*` -> `DELETE`).
-- `rateLimit` returns `undefined`, which the emitter omits from the generated entry.
-- `auth` returns `{ login: true }` (the safer default).
-
-There is also `extractValidation(filePath)` which returns `'strict' | 'relaxed' | { input: 'skip' | 'strict' } | undefined` — currently surfaced via `apiMetaMap` in the generated file.
-
----
-
-## Sync pairing + extraction
-
-```typescript
-const syncServerFiles = findAllSyncServerFiles(getSrcDir());
-const syncClientFiles = findAllSyncClientFiles(getSrcDir());
-
-const allSyncs = new Map<string, {
-  pagePath: string;
-  syncName: string;
-  serverFile?: string;
-  clientFile?: string;
-}>();
-
-for (const serverFile of syncServerFiles) {
-  const key = `${extractSyncPagePath(serverFile)}/${extractSyncName(serverFile)}/${extractSyncVersion(serverFile)}`;
-  const existing = allSyncs.get(key) || { pagePath, syncName };
-  existing.serverFile = serverFile;
-  allSyncs.set(key, existing);
-}
-
-for (const clientFile of syncClientFiles) {
-  // mirror with `clientFile`
-}
-```
-
-After both walks, `allSyncs` has one entry per logical sync route, populated with whichever of `serverFile` / `clientFile` exists. Three cases:
-
-1. **Server + client** — `clientInput` from the server's `data` param; `serverOutput` from server's return; `clientOutput` from client's return.
-2. **Server-only** — `clientInput` from server; `serverOutput` from server; `clientOutput` defaults to `{ }`.
-3. **Client-only** — `clientInput` from the client file (the framework still needs to know the type the caller sends); `serverOutput` defaults to `{ }`; `clientOutput` from client.
-
-```typescript
-const clientInputTypeResult = serverFile
-  ? getSyncClientDataTypeDetailsFromFile(serverFile)
-  : (clientFile
-    ? getSyncClientDataTypeDetailsFromFile(clientFile)
-    : { text: '{ }', unresolvedSymbols: [] });
-```
-
-Each `*TypeDetailsFromFile` returns `{ text, unresolvedSymbols }`; the symbols are merged into `unresolvedTypeAliases` / `namedImports` exactly the same way as in the API loop.
-
-When a server file exists, its `auth` and `rateLimit` are read with the SAME extractors as the API side (`extractAuth` / `extractRateLimit`) and feed `syncMetaMap`. Only server-backed routes (cases 1 and 2) get a `syncMetaMap` / `syncInputSchemas` entry: a client-only sync is not a callable route, so there is nothing for the test-runner to sweep.
-
----
-
-## Functions interface (`generateServerFunctions`)
-
-```typescript
-const functionsInterface = generateServerFunctions({ namedImports, defaultImports });
-```
-
-`generateServerFunctions` walks every configured `serverFunctionDirs` root recursively (legacy singular `serverFunctionsDir` still honored when set) and emits a nested-interface block representing every exported function or value. Per file:
-
-1. Parse the source via the TypeScript Program (reuses the same cached `ts.Program` — see `ts-program-cache.md`).
-2. For every `export const <name> = (...)` arrow or function expression, extract a signature string with `extractSignatureFromNode`. Default values are stripped from parameters; generic clauses are preserved; `Promise<unknown>` is the return-type fallback for async functions without annotations.
-3. For every `export const <name>: <Type> = ...` without a function initializer, run `inferValueTypeForExport` — uses `declaration.type` when annotated, falls back to `checker.typeToString` on the inferred type, then runs `simplifyInferredType` to map common framework types (`PrismaClient`, `Redis`) onto bare identifiers.
-4. For re-exports (`export { a } from 'module'`), emit `typeof import('<rel-spec>')['a']`. Relative specifiers are rewritten via `relativizeModuleSpecifier` so they resolve from the generated file's directory (`src/_sockets/apiTypes.generated.ts`).
-5. Defaults are merged into the file-named bucket so `import myFn from './myFn'` shows up at `Functions.<folder>.myFn.myFn` (matching `devFunctions`).
-
-The output is one big block of nested `'<folder>': { <file>: { <export>: <signature>; }; };` entries. It is embedded verbatim into `apiTypes.generated.ts` inside `export interface Functions { ... }`.
-
-`namedImports` / `defaultImports` from this walk feed the same import-statement builder as the API/sync walks — anything the `Functions` interface references that isn't an inline type is imported at the top of the generated file.
-
----
-
-## Unresolved symbol handling
-
-```typescript
-if (unresolvedTypeAliases.size > 0) {
-  const unresolvedList = [...unresolvedTypeAliases].sort().join(', ');
-  throw new Error(`[TypeMapGenerator] Aborting generation because unresolved type symbols were found: ${unresolvedList}`);
-}
-```
-
-A "symbol" with no `importPath` means the TypeChecker found a referenced identifier (e.g. `User`, `Settings`) but couldn't trace its declaration back to a source file. The most common cause is a name collision (two files declare a `User` type) or a missing `import`. Generation aborts so the symptom doesn't surface as broken IntelliSense.
-
-Symbols with an `importPath` are added to `namedImports` and become real `import { Symbol } from "<path>";` statements in the generated file.
-
----
-
-## Artifact build + write
-
-```typescript
-const { content, docsData, schemasContent } = buildTypeMapArtifacts({
-  typesByPage,
-  syncTypesByPage,
-  namedImports,
-  defaultImports,
-  functionsInterface,
-});
-
-writeTypeMapArtifacts({ content, docsData, schemasContent });
-```
-
-`buildTypeMapArtifacts` in `typeMap/emitterArtifacts.ts` renders three strings:
-
-### `content` -> `apiTypes.generated.ts`
-
-Single file emitted at `getGeneratedSocketTypesPath()` (default `<repo>/src/_sockets/apiTypes.generated.ts`, overridable via `@luckystack/core` path helpers). Layout:
-
-```
-/* eslint-disable ... */
-
-<importStatements>
-
-export interface Functions { ... };
-
-export type JsonPrimitive = ...;
-export type JsonValue = ...;
-// ... shared scalar helpers ...
-
-export type StreamPayload = { [key: string]: unknown };
-export type ApiStreamEmitter<T extends StreamPayload = StreamPayload> = ...;
-export type SyncServerStreamEmitter<T extends StreamPayload = StreamPayload> = ...;
-export type SyncClientStreamEmitter<T extends StreamPayload = StreamPayload> = ...;
-export type SyncBroadcastStreamEmitter<...> = ...;
-export type SyncStreamToEmitter<...> = ...;
-
-export type ApiResponse<T = unknown> = ...;
-export type ApiNetworkResponse<T = unknown> = ...;
-
-type _ProjectApiTypeMap = { ... per-route input/output/stream/method/rateLimit ... };
-export interface ApiTypeMap extends _ProjectApiTypeMap {}
-
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
-export type PagePath = ...;
-export type ApiName<P> = ...;
-export type ApiVersion<P, N> = ...;
-export type ApiInput<P, N, V = ApiVersion<P, N>> = ...;
-export type ApiOutput<P, N, V = ApiVersion<P, N>> = ...;
-export type ApiStream<P, N, V = ApiVersion<P, N>> = ...;
-export type ApiMethod<P, N, V = ApiVersion<P, N>> = ...;
-export type FullApiPath<P, N, V> = `api/${P}/${N & string}/${V & string}`;
-
-export const apiMethodMap: Record<string, Record<string, Record<string, HttpMethod>>> = { ... };
-export const getApiMethod = (...): HttpMethod | undefined => ...;
-
-export interface ApiMetaEntry { method, auth: { login, additional? }, rateLimit? };
-export const apiMetaMap: Record<...> = { ... };
-export const getApiMeta = (...): ApiMetaEntry | undefined => ...;
-
-export interface SyncMetaEntry { auth: { login, additional? }, rateLimit? };
-export const syncMetaMap: Record<...> = { ... };   // server-backed syncs only
-export const getSyncMeta = (...): SyncMetaEntry | undefined => ...;
-
-export type SyncServerResponse<T = unknown> = ...;
-export type SyncClientResponse<T = unknown> = ...;
-
-type _ProjectSyncTypeMap = { ... per-sync clientInput/serverOutput/clientOutput/serverStream/clientStream ... };
-export interface SyncTypeMap extends _ProjectSyncTypeMap {}
-
-export type SyncPagePath = ...;
-export type SyncName<P> = ...;
-export type SyncVersion<P, N> = ...;
-export type SyncClientInput<P, N, V = SyncVersion<P, N>> = ...;
-export type SyncServerOutput<P, N, V = SyncVersion<P, N>> = ...;
-export type SyncClientOutput<P, N, V = SyncVersion<P, N>> = ...;
-export type SyncServerStream<P, N, V = SyncVersion<P, N>> = ...;
-export type SyncClientStream<P, N, V = SyncVersion<P, N>> = ...;
-export type FullSyncPath<P, N, V> = `sync/${P}/${N & string}/${V & string}`;
-
-// Module augmentation merges the project's concrete maps into @luckystack/core
-// stub interfaces so framework code (apiRequest / syncRequest) gets the same
-// shapes without deep-relative imports.
-declare module '@luckystack/core' {
-  interface ApiTypeMap extends _ProjectApiTypeMap {}
-  interface SyncTypeMap extends _ProjectSyncTypeMap {}
-}
-```
-
-Before writing, `validateGeneratedTypeIdentifiers(content)` parses the content with `ts.createSourceFile` and asserts every referenced type identifier is either declared in the file or imported. Anything else (built-ins like `Record`, `Promise`, etc., plus a curated allow-list) throws and aborts the run.
-
-### `schemasContent` -> `apiInputSchemas.generated.ts`
-
-Built by `buildSchemasContent`. Loops over the API map again, runs each input type through `typeTextToZodSource` (from `typeMap/zodEmitter.ts`), and emits:
-
-```typescript
-import { z } from 'zod';
-
-export const apiInputSchemas: Record<string, Record<string, Record<string, z.ZodTypeAny>>> = {
-  '<pagePath>': {
-    '<apiName>': {
-      '<version>': <z.object(...)>,
-    },
-  },
-};
-
-export const getApiInputSchema = (pagePath, apiName, version): z.ZodTypeAny | undefined =>
-  apiInputSchemas[pagePath]?.[apiName]?.[version];
-```
-
-`typeTextToZodSource` walks the TS-AST of the inline type literal and emits Zod source. Unsupported shapes fall back to `z.any() /* unparseable input type */` with a TODO.
-
-A sibling `syncInputSchemas` / `getSyncInputSchema` pair covers every server-backed sync route, built from its `clientInput` (the `data` the client sends) with the same converter and fallback. It exists so the test-runner sweeps (contract / fuzz) can reach sync routes the way they reach API routes. Sync input fallbacks to `z.any()` are recorded in `apiTypeDiagnostics.generated.json` exactly like API ones. Output and stream types never get a schema.
-
-### `docsData` -> `apiDocs.generated.json`
-
-Pure JSON dump of every API and sync entry. Used by `@luckystack/docs-ui` to render an OpenAPI-like browser:
-
-```json
-{
-  "apis": {
-    "<pagePath>": [
-      { "page", "name", "version", "method", "input", "output", "stream", "rateLimit", "auth", "path" }
-    ]
-  },
-  "syncs": {
-    "<pagePath>": [
-      { "page", "name", "version", "clientInput", "serverOutput", "clientOutput", "serverStream", "clientStream", "path" }
-    ]
-  }
-}
-```
-
-Where each file is written:
-
-- `apiTypes.generated.ts` -> `getGeneratedSocketTypesPath()` (configurable via `@luckystack/core`).
-- `apiInputSchemas.generated.ts` -> `getGeneratedApiSchemasPath()`.
-- `apiDocs.generated.json` -> `getGeneratedApiDocsPath()`.
-
-`writeTypeMapArtifacts` only rewrites a file when its content changed (`writeFileIfChanged`). This avoids spurious file-modified events on the runner during hot reload (which would otherwise feed back into the watcher and trigger another regeneration).
-
----
-
-## `quiet` option
-
-```typescript
-generateTypeMapFile({ quiet: true });
-```
-
-Used by `setupWatchers()` for both the initial-boot regeneration and every subsequent hot-reload regeneration (see `hot-reload.md`). Suppresses:
-
-- The two banner lines (`═══════…`).
-- The `[TypeMapGenerator] Found N API files` / `Sync server/client files` headers.
-- Per-API and per-sync logs.
-
-The final per-file write logs (`Generated apiTypes.generated.ts`, etc.) still fire, but only when content changed.
-
----
-
-## Public extractor surface
-
-Re-exported from `@luckystack/devkit`:
-
-```typescript
-export { getInputTypeFromFile, getSyncClientDataType } from './typeMap/extractors';
-```
-
-Both are thin wrappers over the `*Details` variants — they discard `unresolvedSymbols` and return only `text`. Used by the dev loader to attach inline type text to live route entries (consumed downstream by `runtimeTypeValidation` in `@luckystack/core`).
-
----
-
-## Failure modes
-
-| Symptom | Cause |
-|---|---|
-| `[TypeProgram] tsconfig.server.json not found` | Project doesn't have a `tsconfig.server.json` next to `package.json`. See `ts-program-cache.md`. |
-| `assertValidRouteNaming` throw | A `_api/`/`_sync/` file fails the version regex. Fix the filename. |
-| `assertNoDuplicateNormalizedRouteKeys` throw | Two files (often case-differing) normalize to the same route key. Rename one. |
-| `[TypeMapGenerator] Aborting generation because unresolved type symbols were found: X, Y, Z` | TypeChecker couldn't trace identifier(s) back to a source file. Usually a missing import or a naming collision. |
-| `[TypeMapGenerator] Generated type map has unresolved type identifiers: ...` | Post-emission validation: a generated symbol wasn't declared or imported. Bug in an extractor or in `generateServerFunctions`. |
-| `[TypeMapGenerator] Error writing type map or docs: ...` | Filesystem error during write. Caught and logged, generator returns normally so hot reload doesn't crash the server. |
-| `declares Date in a transport input` | The handler annotation promises an instance JSON cannot deliver. Change the input field to `string`, validate ISO format, then convert. |
-| `has transport-dependent or non-JSON output semantics` | A route returns binary/BigInt output that cannot share one HTTP + Socket.io type. Return a JSON DTO/base64 string or use a custom transport route. |
-| Stale generated types after a hot reload | `invalidateProgramCache()` not called (shouldn't happen — the generator always invalidates at the top). |
+**Server-backed sync routes get the same metadata and input schemas as API routes.** Their auth and rate-limit settings are read with the same extractors as the API side, and their client input runs through the same schema converter and diagnostics, so the test-runner's contract and fuzz sweeps can reach sync routes the way they reach API routes (ADR 0064). A client-only sync is not a callable route and gets neither. Output and stream types never get a runtime schema. Source: `../src/typeMapGenerator.ts`, `../src/typeMap/emitterArtifacts.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckystack/devkit",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -45,7 +45,7 @@
   "files": [
     "dist",
     "README.md",
-    "CLAUDE.md",
+    "AGENTS.md",
     "docs",
     "LICENSE",
     "CHANGELOG.md"
@@ -56,13 +56,13 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@luckystack/core": "^0.10.2",
+    "@luckystack/core": "^0.11.0",
     "chokidar": "^5.0.0",
-    "dotenv": "^17.0.0"
+    "dotenv": "^17.0.0",
+    "typescript-7-api": "npm:typescript@7.1.0-dev.20261013.1"
   },
   "peerDependencies": {
     "@prisma/client": "^6.19.0",
-    "typescript": ">=5.7.3 <7.0.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {

package/CLAUDE.md

@@ -1,135 +0,0 @@
-# @luckystack/devkit
-
-> AI summary + function INDEX. For deep specs see `docs/` next to this file.
-
-## What this package does
-
-Dev-time tooling for LuckyStack projects: file-based route discovery + in-memory loaders (`devApis`, `devSyncs`, `devFunctions`), chokidar-driven hot reload, TypeScript-program-backed type-map + Zod schema emission, a route filename validator, a deep runtime type resolver (consumed by `@luckystack/core` in dev), a process supervisor that restarts the server on core file changes, file templates injected on empty API/sync file creation, and the `luckystack-validate-deploy` CLI. Designed to be installed as a `devDependency` only; the production server bundle never imports it.
-
-## When to USE this package
-
-- Running the framework locally (`npm run server` / `npm run dev`) — `setupWatchers` + `initializeAll` are the canonical dev wiring, and the prod runtime maps loader delegates to `devApis` / `devSyncs` when `NODE_ENV !== 'production'`.
-- Generating typed artifacts (`apiTypes.generated.ts`, `apiInputSchemas.generated.ts`, `apiDocs.generated.json`) from `_api/` and `_sync/` files — call `generateTypeMapFile()` from a build script.
-- Gating a deploy on configuration correctness — `luckystack-validate-deploy` (the package `bin`) confirms every service binding, preset, and env key resolves before shipping a bundle.
-- Wrapping the server in a watcher that restarts on `config.ts` / `.env` / `server/bootstrap/**` changes — `supervisor.ts` is the entry point.
-- Extending the deep type resolver from `@luckystack/core/src/runtimeTypeValidation.ts` (lazy-imported in dev) without owning the TypeScript-program plumbing.
-
-## When to NOT suggest this (yet)
-
-- **Production runtime.** Devkit is dev-only. Do not import it from code paths reachable in `NODE_ENV=production`; the supervisor, hot-reload watchers, and TypeScript Program have no place in a prod bundle and will not be present in consumer prod tarballs.
-- **Bundled / packaged consumer apps (`create-luckystack-app` templates that ship to end users).** Devkit belongs in `devDependencies` of the project, not in any shipped artifact.
-- **Replacing the runtime route registry.** `devApis` / `devSyncs` are dev-only maps that mirror the file tree. In production, `@luckystack/server` reads the generated runtime maps; do not call `initializeApis` / `initializeSyncs` from a prod code path.
-- **Running tests in CI without a TypeScript Program.** The type-map emitter expects `tsconfig.server.json`; in headless CI test harnesses that do not produce generated types, skip `generateTypeMapFile()` and rely on previously committed artifacts.
-- **Hot-reloading non-LuckyStack code.** The watchers know about LuckyStack's marker segments (`_api/`, `_sync/`) and the configured `srcDir` / `sharedDir` / `serverFunctionDirs` (legacy `serverFunctionsDir` singular form still honored when set). Generic file watching belongs in chokidar directly.
-
-## Function Index
-
-| Function / Export | One-liner | Deep doc |
-|---|---|---|
-| `initializeAll()` | Runs route-naming validation, then `initializeApis` + `initializeSyncs` + `initializeFunctions` in parallel. | -> docs/loader-pipeline.md |
-| `initializeApis()` | Clears `devApis`, walks the configured `srcDir`, loads every `_api/<name>_v<n>.ts` via dynamic `import()` with a cachebust query, and populates the dev-side route registry. | -> docs/loader-pipeline.md |
-| `initializeSyncs()` | Clears `devSyncs`, walks the configured `srcDir`, loads every `_sync/<name>_server_v<n>.ts` and `<name>_client_v<n>.ts`, and populates the dev-side route registry. | -> docs/loader-pipeline.md |
-| `initializeFunctions()` | Clears `devFunctions`, resolves the module list via `collectFunctionModules()`, imports each one, and builds a nested `Record<string, unknown>` mirror of the on-disk tree from its key path. Dev passes `onConflict` so a duplicate warns + keeps the first claim instead of throwing. | -> docs/loader-pipeline.md |
-| `collectFunctionModules(options?)` | **Single source of truth for function discovery** (ADR 0046). Walks every configured `serverFunctionDirs` root (default `['functions', 'shared']`, legacy singular `serverFunctionsDir` still honored) and derives each module's `functions.*` key path from its location relative to its root — so `shared/rbac/engine.ts` is `functions.rbac.engine`. Skips `node_modules`, test files (`.tests.`/`.test.`/`.spec.` via core's `isTestFile`), `__tests__`/`__mocks__` folders, and paths the `RoutingRules.ignore` predicate rejects. Throws on a cross-root duplicate key or a module/namespace collision; pass `onConflict` to warn + skip instead (dev-loader mode). `roots` overrides the configured roots for tests. Consumed by the dev loader, `functionsMeta.ts`, and BOTH `scripts/generateServerRequests.ts` copies. | -> docs/loader-pipeline.md |
-| `renderFunctionsMap({ modules, importPrefix, varPrefix? })` | Renders discovered modules into the `functions` export of a generated production runtime-map file: `{ imports, source }`, with a NESTED object literal matching what the dev loader builds and `apiTypes.generated.ts` declares. A default-only export is aliased to the file name (`functions.sleep.sleep`). | -> docs/loader-pipeline.md |
-| `formatFunctionKeyPath(keyPath)` / `functionModuleFileName(keyPath)` / `formatFunctionKeyConflict(...)` / `formatFunctionNamespaceConflict(...)` | Key-path helpers + the two canonical collision diagnostics, shared so dev and build-time emit identical wording. | -> docs/loader-pipeline.md |
-| Types: `FunctionModule`, `RenderedFunctionsMap`, `CollectFunctionModulesOptions` | Public typing for the function registry. | -> docs/loader-pipeline.md |
-| `upsertApiFromFile(filePath)` | Hot-reload single API: invalidates the TS Program cache + runtime type resolver cache, re-imports the file with a fresh cachebust, and replaces the matching entry in `devApis`. | -> docs/loader-pipeline.md |
-| `removeApiFromFile(filePath)` | Hot-reload delete: invalidates caches and deletes the matching entry from `devApis`. | -> docs/loader-pipeline.md |
-| `upsertSyncFromFile(filePath)` | Hot-reload single sync: handles both `_server_v<n>` and `_client_v<n>` kinds, invalidates caches, re-imports, replaces the matching entry in `devSyncs`. | -> docs/loader-pipeline.md |
-| `removeSyncFromFile(filePath)` | Hot-reload delete: invalidates caches and deletes the matching entry from `devSyncs`. | -> docs/loader-pipeline.md |
-| `devApis` | In-memory map of `route key -> { main, auth, rateLimit, httpMethod, schema, inputType, inputTypeFilePath }`. Mirrored by the prod runtime maps loader in dev. | -> docs/loader-pipeline.md |
-| `devSyncs` | In-memory map of `route key (with _server / _client suffix) -> server entry record or client callback function`. | -> docs/loader-pipeline.md |
-| `devFunctions` | Nested mirror of `serverFunctionsDir`. Each leaf is a module's named + default exports, with later folder scans merging onto existing nodes. | -> docs/loader-pipeline.md |
-| `setupWatchers()` | Boots the chokidar watchers for `srcDir` / each `serverFunctionDirs` root / `sharedDir` (legacy singular `serverFunctionsDir` still honored when set), coalesces hot-reload + type-map regenerations, fires initial background type-map generation. No-op when `NODE_ENV === 'production'`. | -> docs/hot-reload.md |
-| `generateTypeMapFile(options?)` | Discovers all `_api/` and `_sync/` files, runs the TypeChecker-backed extractors, emits `apiTypes.generated.ts` (incl. `apiMetaMap` + `syncMetaMap`), `apiInputSchemas.generated.ts` (`apiInputSchemas` + `syncInputSchemas`), and `apiDocs.generated.json`. Aborts if any unresolved type symbol is found. | -> docs/type-map-generation.md |
-| `getInputTypeFromFile(filePath)` | Public extractor: returns the inline-expanded `data` input type text for one API file. Consumed by the dev loader to drive `runtimeTypeValidation`. | -> docs/type-map-generation.md |
-| `getSyncClientDataType(filePath)` | Public extractor: returns the inline-expanded `clientInput` (sync server) or client data (sync client) type text. | -> docs/type-map-generation.md |
-| `API_VERSION_TOKEN_REGEX` | Canonical `_v<number>` regex used to parse API filenames. | -> docs/loader-pipeline.md |
-| `SYNC_VERSION_TOKEN_REGEX` | Canonical `_(server\|client)_v<number>` regex used to parse sync filenames. | -> docs/loader-pipeline.md |
-| `assertValidRouteNaming({ srcDir, context })` | Throws if any `_api/` or `_sync/` file fails naming rules. Called by `initializeAll` and `generateTypeMapFile`. | -> docs/loader-pipeline.md |
-| `assertNoDuplicateNormalizedRouteKeys({ srcDir, context })` | Throws on collisions between two files that normalize to the same route key. Called by `generateTypeMapFile`. | -> docs/loader-pipeline.md |
-| `registerRoutingRules(rules)` | Override the marker segments (`_api`, `_sync`), version regexes, `privateFolderPrefix`, `scaffoldIgnoredFolders`, and the optional `disableTemplateInjection: (filePath) => boolean` predicate for opting parts of the tree out of scaffold injection. | -> docs/loader-pipeline.md |
-| `getRoutingRules()` | Read the current rules (defaults shipped by the package). | -> docs/loader-pipeline.md |
-| `registerTemplate(kind, content)` | Override the BODY of a template kind with a string. Content resolution order at injection: consumer file (`.luckystack/templates/<kind>.template.ts(x)`) -> this string override -> bundled disk template. `{{REL_PATH}}` / `{{PAGE_PATH}}` / `{{SYNC_NAME}}` placeholders still apply. | -> docs/template-customization.md |
-| `getRegisteredTemplate(kind)` / `clearTemplateOverrides()` / `listRegisteredTemplateKinds()` | Lookup, test-reset, and diagnostic helpers for the content-override registry. | -> docs/template-customization.md |
-| `registerTemplateRule({ kind, match, priority? })` | Add a SELECTION rule — decides which kind a classified file gets. Rules evaluate by descending `priority` (ties: newest first); first match wins. `match(ctx)` receives `{ filePath, fileKind: 'api'\|'sync_server'\|'sync_client'\|'page', hasPairedServer, srcRelativePath }`. | -> docs/template-customization.md |
-| `registerTemplateKind(kind, { match, content?, priority? })` | Register a brand-new template kind (predicate + optional inline content) in one call. Default priority 100 so custom kinds beat the built-ins. | -> docs/template-customization.md |
-| `resolveTemplateKind(ctx)` / `getTemplateRules()` / `clearTemplateRules()` / `registerDefaultTemplateRules()` | Evaluate rules to a kind, read the active rule set, drop all rules (consumer replace), and (re)arm the built-in defaults. | -> docs/template-customization.md |
-| `BUILT_IN_TEMPLATE_KINDS` / `BUILT_IN_TEMPLATE_FILENAMES` / `DEFAULT_DASHBOARD_PATH_PATTERN` | The 6 built-in kinds, their bundled filenames, and the page-dashboard heuristic regex (reused by the scaffolded consumer rules file). | -> docs/template-customization.md |
-| Consumer overlay: `.luckystack/templates/` | devkit auto-loads `.luckystack/templates/templateRules.ts` in DEV (once, before the first injection) so consumers can edit/remove/add selection rules + kinds as code. Per-kind `*.template.ts(x)` files in the same folder override content. Shipped by `create-luckystack-app`. | -> docs/template-customization.md |
-| `assertNoDuplicatePageRoutes({ srcDir, context })` | Build-time validator that throws when two `page.tsx` files compute the same URL after invisible-parent stripping. Called by `generateTypeMapFile`. | -> docs/loader-pipeline.md |
-| `collectDuplicatePageRoutes(srcDir)` / `formatDuplicatePageRouteIssues({...})` | Non-throwing pair behind the assert. `initializeAll()` uses these to soft-warn at dev startup. **Internal** — live in `routeNamingValidation.ts` but are NOT re-exported from `index.ts`. | -> docs/loader-pipeline.md |
-| Type: `TemplateKind`, `DuplicatePageRouteIssue` | Public types for the new registry + duplicate-detector. | -> docs/hot-reload.md |
-| `apiMarkerSegment` / `syncMarkerSegment` | Resolved marker strings (default `_api` / `_sync`). | -> docs/loader-pipeline.md |
-| `isApiFileName(name)` / `isSyncFileName(name)` / `isSyncServerFileName(name)` / `isSyncClientFileName(name)` | Filename predicates that respect `getRoutingRules()`. | -> docs/loader-pipeline.md |
-| `Type: RoutingRules` | Shape of the overrideable rules registry. | -> docs/loader-pipeline.md |
-| `resolveRuntimeTypeText(typeText)` | Recursively expand a stored TypeScript type text into fully inlined form using the cached server program. Used by `@luckystack/core`'s dev-only runtime validator. | -> docs/runtime-type-resolver.md |
-| `clearRuntimeTypeResolverCache()` | Drop the resolver's memoization map. Called on every hot-reload upsert / delete. | -> docs/runtime-type-resolver.md |
-| `validateDeploy(input)` | Library form of the deploy validator. Returns a list of `ValidationFinding` records (severity + message + slot). Finding codes include `service-unassigned`, `service-in-multiple-presets`, `preset-references-unknown-service`, `binding-references-unknown-service`, `binding-invalid-url` (error — binding URL doesn't parse), `binding-missing-port` (error — binding URL has no explicit port), `unknown-redis-resource`, `unknown-mongo-resource`, `unknown-fallback-env`, `fallback-redis-mismatch`, `fallback-mongo-mismatch`, `missing-resource-env-var` (warning), `missing-synchronized-env-var` (warning), `service-bound-in-no-environment` (warning). | -> docs/cli.md |
-| `Types: ValidateDeployInput`, `ValidateDeployResult`, `ValidationFinding`, `ValidationSeverity` | Public typing for the validator. | -> docs/cli.md |
-| `luckystack-validate-deploy` (`bin`) | CLI wrapper that imports the consumer's compiled `services.config.js` + `deploy.config.js`, runs `validateDeploy`, prints findings, exits non-zero on errors (and on warnings under `--strict`). | -> docs/cli.md |
-| Supervisor entry (`supervisor.ts`) | Standalone Node entry: watches `config.ts`, `.env`, `.env.local`, `server/server.ts`, `server/bootstrap/**`, `server/auth/**`, and key `server/functions/*.ts` files; debounces restarts; respawns crashed children with a delay; honors SIGINT / SIGTERM. | -> docs/supervisor.md |
-
-Internal modules (not exported from `index.ts`, but live in this package):
-
-| Module | Role | Deep doc |
-|---|---|---|
-| `typeMap/tsProgram.ts` (`getServerProgram`, `invalidateProgramCache`, `expandType`) | Cached `ts.Program` over `tsconfig.server.json`. Rebuilt on hot reload + before every type-map generation. | -> docs/ts-program-cache.md |
-| `typeMap/discovery.ts` | Recursively walks `srcDir` to find `_api/`, `_sync/server`, `_sync/client` files. | -> docs/type-map-generation.md |
-| `typeMap/extractors.ts` | TypeChecker-backed extractors for `data` / `serverOutput` / `clientOutput` / stream payload types. | -> docs/type-map-generation.md |
-| `typeMap/apiMeta.ts` | Extracts `httpMethod`, `rateLimit`, `auth` from API files. | -> docs/type-map-generation.md |
-| `typeMap/routeMeta.ts` | Filename -> `pagePath` / `apiName` / `apiVersion` / `syncName` / `syncVersion`. | -> docs/type-map-generation.md |
-| `typeMap/functionsMeta.ts` | Builds the `Functions` interface text emitted into `apiTypes.generated.ts`. Discovery comes from `collectFunctionModules()`; this module only parses each file's exports and places it at its key path. | -> docs/type-map-generation.md |
-| `typeMap/emitter.ts` + `emitterArtifacts.ts` | Renders generated files to disk via `@luckystack/core`-resolved paths. | -> docs/type-map-generation.md |
-| `typeMap/zodEmitter.ts` | Generates the runtime Zod schemas for API inputs. | -> docs/type-map-generation.md |
-| `templateInjector.ts` + `templates/*.ts` | Detects empty `_api/`, `_sync/`, AND `page.tsx` files and injects starter content. Sync server/client pairing is auto-resolved. Page files get the `dashboard` template when the path contains `admin\|dashboard\|settings\|billing\|account\|profile`, else the `plain` template. Pages in invalid placements (inside a reserved framework folder, or directly inside an `_<folder>` with no URL segment left) get a commented diagnostic block instead of a usable template so the placement issue is visible at creation time. | -> docs/hot-reload.md |
-| `importDependencyGraph.ts` | Tracks which `_api/` / `_sync/` files depend on each shared module so hot reload can fan out. | -> docs/hot-reload.md |
-| `runtimeTypeResolver.ts` | Cached recursive expander built on top of `tsProgram`. | -> docs/runtime-type-resolver.md |
-
-## Codegen contract decisions (DD-DEVKIT-D1 / D2 / D3)
-
-**D1 — getSourceFile/Program miss → loud warning, never silent**
-
-When `getServerProgram().getSourceFile(filePath)` returns `undefined`, the extractor always emits a `console.warn` and falls back to `{ }` (empty input) or `{ status: string }` (empty output). This is a documented marker: it means the file is present on disk but absent from the TS Program (typically because `tsconfig.server.json` globs do not cover it, or the Program was not rebuilt after a new file was added). The affected route is also listed in `apiTypeDiagnostics.generated.json` under `reason: 'default-fallback'`. Never suppress this warning — a silent `{ }` input accepts any payload shape at runtime.
-
-**D2 — Zod strict-vs-loose policy**
-
-Object literal types → `.strict()` (unknown keys rejected, fail-closed). This is the posture for all typed API/sync inputs that the Zod emitter can structurally resolve. Types that fall outside the emitter's scope (intersections, unresolvable TypeReferences, mapped/conditional types) → `z.any()` fallback with a TODO comment. The fallback count is surfaced in `apiTypeDiagnostics.generated.json` (`reason: 'zod-any-fallback'`). Do not add `.passthrough()` to the emitter's default output — consumers who need to accept extra keys should widen their `ApiParams.data` type explicitly.
-
-**D3 — apiTypeDiagnostics.generated.json**
-
-Every `generateTypeMapFile()` run emits `apiTypeDiagnostics.generated.json` alongside `apiDocs.generated.json`. It lists every route whose type extraction degraded to a fallback (source file miss, thrown API/sync input/output/**stream** extraction, or `z.any()` in the Zod schema). Shape: `{ generatedAt, totalRoutes, fallbackCount, fallbacks: DiagnosticsEntry[] }`. CI can fail on non-zero `fallbackCount` to enforce type-fidelity. The file path is `<generatedApiDocs dir>/apiTypeDiagnostics.generated.json`.
-
-One case is deliberately NOT a fallback: a sync side that does not exist on disk. `_client` is optional by contract (`/docs/ARCHITECTURE_SYNC.md` — a pass-through sync must not have one, because a no-op handler costs an execution per recipient), and an absent side yields the same `{ }` text as a present side that declares no shape. The generator therefore carries per-entry presence flags so the emitter can tell the two apart, and suppresses only the field belonging to the missing side. A THROWN extraction is still checked first and always reported, so this can never hide a real failure — do not widen the exception past the missing side's own field.
-
-**D4 — transport-safe route contracts**
-
-Output extraction projects `JSON.stringify` semantics recursively: `Date` becomes `string`; `toJSON()` becomes its return type; omitted object values (`undefined`, symbol, every callable value) disappear or make a union-valued property optional; those values become `null` in arrays/tuples. Binary values are rejected because HTTP JSON and Socket.io binary delivery cannot share one truthful output type. Input extraction does not project declarations, but rejects `Date`: JSON can only deliver an ISO string, so route authors must declare `string`, validate it, and convert explicitly before using Date methods.
-
-## Config keys (env vars + registerProjectConfig slots)
-
-- `NODE_ENV` (env, required for branching) — `setupWatchers()` is a no-op outside dev; `supervisor.ts` only watches files in non-prod mode.
-- `LUCKYSTACK_CORE_SUPERVISED` (env, set by the supervisor) — present in the child process so framework code can detect it is running under the supervisor.
-- `projectConfig.paths.srcDir` — root for route discovery + watcher subscriptions.
-- `projectConfig.paths.sharedDir` — additional watch root for shared modules that feed back into route hot reload via the dependency graph.
-- `projectConfig.paths.serverFunctionDirs` (array) — roots for `initializeFunctions()` + the functions watchers. (Legacy `projectConfig.paths.serverFunctionsDir` singular form still honored when set; values are merged into the array at config load.)
-- `projectConfig.dev.hotReloadDebounceMs` — debounce window for coalesced reload + type-map regeneration.
-- `projectConfig.dev.watcherStabilityThresholdMs` / `projectConfig.dev.watcherPollIntervalMs` — chokidar `awaitWriteFinish` tuning passed to the source watcher.
-- Generated artifact paths (`getGeneratedSocketTypesPath()`, `getGeneratedApiDocsPath()`, Zod schema path) — resolved through `@luckystack/core`. Override at the core level, not in devkit.
-- `tsconfig.server.json` (file, required) — the `ts.Program` is built from this config; `getServerProgram()` throws if it cannot be located.
-
-## Peer dependencies
-
-- **Required peer (runtime)**: `typescript@>=5.7.3 <7.0.0` — the type-map emitter and runtime type resolver call into the TypeScript Compiler API. No optional fallback. The emitter's `checker.typeToString` output was verified byte-identical between TS 5.7.3 and 6.0.3, so both are supported; TS 7 (native port) is excluded until re-verified. Consumers on the React-eslint stack typically stay on 5.7.x (eslint-plugin-react / jsx-a11y have no ESLint-10 release yet, and ESLint 10 is what TS6-capable react-x requires); the framework itself builds on TS 6. If a consumer's `typescript` version drifts outside this range the emitter may produce different inlined output. Treat as a hard peer.
-- **Required peer**: `zod@^4.0.0` — the Zod schema emitter compiles consumer input types into runtime schemas via `zodEmitter.ts`.
-- **Optional peer**: `@prisma/client@^6.19.0` — required only when consumer route/config types actually reference Prisma models; non-Prisma projects generate without it.
-- **Direct dependency**: `chokidar@^5.0.0` (the file watcher used by both `hotReload.ts` and `supervisor.ts`).
-- **Direct dependency**: `@luckystack/core` (project config, root dir, generated artifact paths, `tryCatch`, locale reloader hook).
-- **Optional**: `tsx` — the supervisor spawns the child with `node node_modules/tsx/dist/cli.mjs server/server.ts`. Consumers who run the server differently need to spawn the supervisor's child themselves.
-
-## Related
-
-- Architecture deep-dives: `/docs/ARCHITECTURE_ROUTING.md` (file conventions + version token rules), `/docs/ARCHITECTURE_PACKAGING.md` (generated artifact layout), `/docs/ARCHITECTURE_API.md`, `/docs/ARCHITECTURE_SYNC.md`.
-- README (consumer quickstart): `./README.md`.
-- Consumed by: `scripts/generate*.ts` in this repo; `server/dev/setupWatchers.ts`; `server/prod/runtimeMaps.ts` (dev branch); `@luckystack/core/src/runtimeTypeValidation.ts` (dev-only lazy import).