@spfn/core 0.3.0-beta.3 → 0.3.0-beta.31

package/dist/codegen/index.d.ts

@@ -293,6 +293,24 @@ interface GenerationStats {
  * Generates a route map file containing routeName → {method, path} mappings.
  * This allows RPC proxy to resolve routes without importing the full router.
  *
+ * The router is loaded and walked, not parsed from source. A source parser sees
+ * the spelling rather than the router: `defineRouter({ createUser })` written on
+ * one line, an aliased key `create: createUser`, and a nested router assembled by
+ * a second `defineRouter(` in the same file are all ordinary ways to write a
+ * router, and all of them used to leave routes out of the map. The RPC client
+ * addresses a route by name, so a dropped name is a route that typechecks and
+ * 404s. Walking the loaded router registers exactly what `registerRoutes`
+ * registers, whatever the source looks like.
+ *
+ * The map carries the routes of every package router the app mounts with
+ * `.packages()`, not only the app's own. A package ships a client that addresses
+ * its routes by name — `authApi.login`, `monitorApi.getStats` — and the app's
+ * `createRpcProxy` resolves a name in the single map it was constructed with, so
+ * a package route in nobody's map is a call that resolves nowhere. The app
+ * therefore merges nothing by hand: `{ ...routeMap, ...authRouteMap }` is a
+ * no-op today and `{ ...routeMap }` is the whole of it. (`eventRouteMap` is the
+ * exception that stays — it is a hand-written constant, not a mounted router.)
+ *
  * @example
  * ```typescript
  * // .spfnrc.ts
@@ -326,10 +344,19 @@ interface RouteMapGeneratorConfig {
      */
     outputPath?: string;
     /**
-     * Additional route directories to scan (for package routers)
+     * Extra file patterns to watch, for routes outside src/server/routes
+     *
+     * @deprecated Ignored. The map is read from the loaded router, which reaches
+     * every route through its own imports wherever they live, so there is no
+     * longer a set of directories to scan. Still accepted so an existing
+     * `.spfnrc.ts` keeps working; the watch patterns it produced are unchanged.
      */
     additionalRouteDirs?: string[];
 }
+/** Thrown when the router cannot produce a route map at all. */
+declare class RouteMapGeneratorError extends Error {
+    constructor(message: string);
+}
 
 /**
  * Contract Generator
@@ -352,6 +379,7 @@ interface RouteMapGeneratorConfig {
  *         defineGenerator({
  *             name: '@spfn/core:contract',
  *             routerPath: './src/server/router.ts',
+ *             eventRouterPath: './src/server/events.ts',   // optional: contracted SSE events
  *             outputDir: './contracts',
  *         })
  *     ]
@@ -374,6 +402,18 @@ interface ContractGeneratorConfig {
      * @default 'appRouter', falling back to the default export
      */
     routerExport?: string;
+    /**
+     * Path to the file exporting the `defineEventRouter()` result (relative to
+     * project root). When set, its contracted events are written into the
+     * document's `events` section; unset, the document has none.
+     * @example './src/server/events.ts'
+     */
+    eventRouterPath?: string;
+    /**
+     * Named export holding the event router.
+     * @default 'eventRouter', falling back to the default export
+     */
+    eventRouterExport?: string;
     /**
      * Directory holding current.json, released/ and usage/ (relative to project root)
      * @default './contracts'
@@ -389,30 +429,126 @@ declare class ContractGeneratorError extends Error {
     constructor(message: string);
 }
 
+/**
+ * States Generator
+ *
+ * Generates a file naming the states the app declared — their ids and their
+ * manifest — as values a browser root or a server component can execute.
+ *
+ * `defineStateRouter` declares the states, and the browser reads them through
+ * `createStateClient<typeof states>`: a type import, erased at build. So nothing
+ * that runs in the browser says which states the app declared, and importing
+ * the router to find out is not an option — each state's `read()` closes over
+ * repositories and the database. A root that compares the declared ids with the
+ * `manifest` of `GET /state` can report a deploy skew between the Next.js server
+ * and the API before rendering, instead of a screen meeting `state.<id>` as
+ * `undefined`.
+ *
+ * The router is loaded and walked, as the route map's is. A state router is told
+ * apart by the `_stateManifest` marker `defineStateRouter` sets on the router it
+ * derives — the object the snapshot route answers as `manifest` — so the ids
+ * written here and the manifest the server serves come from one value.
+ *
+ * @example
+ * ```typescript
+ * // .spfnrc.ts
+ * import { defineConfig, defineGenerator } from '@spfn/core/codegen';
+ *
+ * export default defineConfig({
+ *     generators: [
+ *         defineGenerator({
+ *             name: '@spfn/core:states',
+ *             routerPath: './src/server/router.ts',
+ *             outputPath: './src/generated/states.ts',
+ *         })
+ *     ]
+ * });
+ * ```
+ */
+
+interface StatesGeneratorConfig {
+    /**
+     * Generator name (required for package-based loading)
+     */
+    name: '@spfn/core:states';
+    /**
+     * Path to the router file (relative to project root) — the one the route map reads
+     * @example './src/server/router.ts'
+     */
+    routerPath: string;
+    /**
+     * Output path for the generated states file (relative to project root)
+     * @default './src/generated/states.ts'
+     */
+    outputPath?: string;
+}
+/** Thrown when the router cannot produce the app's declared states. */
+declare class StatesGeneratorError extends Error {
+    constructor(message: string);
+}
+
 /**
  * Router registration guard
  *
- * A contract has to describe what production serves. When a route is registered
- * only under a feature flag or an environment check, the generated contract
- * describes whichever way the generator happened to run — and the gate then
- * compares a promise nobody made.
+ * A route registered only behind a feature flag or an environment check makes
+ * generated output depend on how the generator happened to run. The contract
+ * then describes a promise nobody made, and the route map leaves out a name
+ * `registerRoutes` registers in production — so `api.admin.call()` typechecks
+ * and 404s wherever the flag differs.
  *
- * Object spread is the one way a key can be conditionally present in the object
- * `defineRouter()` receives, so that is what this reads. A spread of a plain
- * identifier (`...baseRoutes`) is unconditional and passes; anything computed
- * inside the spread does not.
+ * What it reads is the router the generator was pointed at: the export the
+ * loader found the router under, and the routers that export mounts by name
+ * from the same file, since a nested router's routes land in the same flat map.
+ * A `defineRouter(` the file writes but the app router never reaches — a second
+ * router a test harness mounts, say — registers nothing in production and is
+ * not scanned.
+ *
+ * Reading is done with TypeScript's parser rather than a regular expression
+ * over the text. A spread is a syntax node there, so a JSDoc that spells
+ * `defineRouter({ ... })` in prose, a brace inside a route path, and a comment
+ * holding an old router are not router source. Only a spread whose expression
+ * reads a condition is refused — a ternary, `&&`, `||`, `??`. A call is
+ * allowed: `...metadataRoutes(config, resource)` is how `@spfn/mcp` composes
+ * its router, and loading yields exactly the routes it returns.
+ *
+ * Past it, by construction: a conditional spread inside an imported route
+ * module, a router built by a factory, a condition hoisted to a variable
+ * (`const extra = flag ? { admin } : {}` spread afterwards), and a
+ * `.packages()` list assembled conditionally. `NODE_ENV` is pinned before the
+ * router loads, which covers those only when the shell left it unset: the
+ * generator then reads the router production gets. `spfn build` pins
+ * `production` itself, so the deployed map is right. `spfn dev` sets
+ * `development` before it spawns the watcher, which inherits it — a
+ * `NODE_ENV === 'development'` condition hoisted to a variable therefore writes
+ * a dev-only route into the map the watcher regenerates, and `spfn build` takes
+ * it back out. The generated map's header names the `NODE_ENV` it was written
+ * under, so that difference shows up in the diff.
  */
-/** Thrown when the router registers contracted routes conditionally. */
+/** Thrown when the router registers routes conditionally. */
 declare class ConditionalRegistrationError extends Error {
     constructor(message: string);
 }
+interface RegistrationScan {
+    /** Path named in the error message. */
+    routerPath: string;
+    /** Contents of the router file. */
+    source: string;
+    /** The export the loader found the router under: `appRouter`, `default`, … */
+    exportName: string;
+    /** What is being generated, named in the message: `route map`, `contract`. */
+    subject: string;
+    /**
+     * The call the router is built with. `defineEventRouter` scans an event
+     * router file, whose event set the contract publishes the same way.
+     * @default 'defineRouter'
+     */
+    factory?: RouterFactory;
+}
+type RouterFactory = 'defineRouter' | 'defineEventRouter';
 /**
  * Refuse a router whose route set depends on a condition.
- *
- * @param routerPath - path named in the error message
- * @param source - contents of the router file
  */
-declare function assertUnconditionalRegistration(routerPath: string, source: string): void;
+declare function assertUnconditionalRegistration(scan: RegistrationScan): void;
 
 /**
  * Built-in Generators Export
@@ -421,7 +557,7 @@ declare function assertUnconditionalRegistration(routerPath: string, source: str
  * ```typescript
  * // .spfnrc.ts
  * import { defineConfig, defineGenerator } from '@spfn/core/codegen';
- * import type { RouteMapGeneratorConfig, ContractGeneratorConfig } from '@spfn/core/codegen';
+ * import type { RouteMapGeneratorConfig, ContractGeneratorConfig, StatesGeneratorConfig } from '@spfn/core/codegen';
  *
  * export default defineConfig({
  *   generators: [
@@ -435,6 +571,11 @@ declare function assertUnconditionalRegistration(routerPath: string, source: str
  *       routerPath: './src/server/router.ts',
  *       outputDir: './contracts',
  *     }),
+ *     defineGenerator<StatesGeneratorConfig>({
+ *       name: '@spfn/core:states',
+ *       routerPath: './src/server/router.ts',
+ *       outputPath: './src/generated/states.ts',
+ *     }),
  *   ]
  * });
  * ```
@@ -447,4 +588,4 @@ declare function assertUnconditionalRegistration(routerPath: string, source: str
  */
 declare const generators: Record<string, unknown>;
 
-export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, ConditionalRegistrationError, type ContractGeneratorConfig, ContractGeneratorError, type GenerationStats, type Generator, type GeneratorConfig, type GeneratorOptions, type GeneratorTrigger, type OrchestratorOptions, type ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
+export { type ClientGenerationOptions, type CodegenConfig, CodegenOrchestrator, ConditionalRegistrationError, type ContractGeneratorConfig, ContractGeneratorError, type GenerationStats, type Generator, type GeneratorConfig, type GeneratorOptions, type GeneratorTrigger, type OrchestratorOptions, type RegistrationScan, type ResourceRoutes, type RouteContractMapping, type RouteMapGeneratorConfig, RouteMapGeneratorError, type StatesGeneratorConfig, StatesGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };