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

package/dist/codegen/index.js

@@ -1,9 +1,10 @@
 import { watch } from 'chokidar';
-import { join, relative, sep, dirname, resolve } from 'path';
+import { join, relative, sep, dirname, resolve, isAbsolute } from 'path';
 import mm from 'micromatch';
 import { logger } from '@spfn/core/logger';
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync, readdirSync } from 'fs';
 import { createJiti } from 'jiti';
+import { createRequire } from 'module';
 import { collectContractDocument, writeCurrentDocument, checkContract, formatViolations } from '@spfn/core/contract';
 
 // src/codegen/core/orchestrator.ts
@@ -334,70 +335,552 @@ async function createGeneratorsFromConfig(config, cwd) {
   }
   return generators2;
 }
-var genLogger = logger.child("@spfn/core:route-map-generator");
-function parseRouteFile(filePath) {
-  const routes = [];
-  try {
-    const content = readFileSync(filePath, "utf-8");
-    const routePattern = /export\s+const\s+(\w+)\s*=\s*route\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/gi;
-    let match;
-    while ((match = routePattern.exec(content)) !== null) {
-      const [, name, method, path] = match;
-      routes.push({
-        name,
-        method: method.toUpperCase(),
-        path,
-        file: filePath
-      });
+var compiler;
+function typescript() {
+  compiler ??= createRequire(import.meta.url)("typescript");
+  return compiler;
+}
+
+// src/codegen/generators/contract-guard.ts
+var ConditionalRegistrationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConditionalRegistrationError";
+  }
+};
+var REFUSAL_WORDING = {
+  defineRouter: {
+    noun: "routes",
+    consequence: "a route production registers is left out, and the client that addresses it by name gets a 404",
+    remedy: "Register the route unconditionally and gate its behaviour inside the handler instead."
+  },
+  defineEventRouter: {
+    noun: "events",
+    consequence: "an event production streams is left out, and the client that subscribes to it by name gets a 400",
+    remedy: "Register the event unconditionally and decide who receives it with the stream's authorize hook instead."
+  }
+};
+function assertUnconditionalRegistration(scan) {
+  const compiler2 = typescript();
+  const file = compiler2.createSourceFile(
+    scan.routerPath,
+    scan.source,
+    compiler2.ScriptTarget.Latest,
+    /* setParentNodes */
+    false
+  );
+  const declarations = topLevelInitialisers(compiler2, file);
+  const routes = routesLiteral(compiler2, declarations.get(scan.exportName), declarations, /* @__PURE__ */ new Set(), factoryOf(scan));
+  if (routes) {
+    assertLiteral(compiler2, file, routes, declarations, /* @__PURE__ */ new Set(), scan);
+  }
+}
+function factoryOf(scan) {
+  return scan.factory ?? "defineRouter";
+}
+function topLevelInitialisers(compiler2, file) {
+  const found = /* @__PURE__ */ new Map();
+  for (const statement of file.statements) {
+    if (compiler2.isExportAssignment(statement) && !statement.isExportEquals) {
+      found.set("default", statement.expression);
+    }
+    if (compiler2.isVariableStatement(statement)) {
+      collectDeclarations(compiler2, statement, found);
+    }
+  }
+  for (const statement of file.statements) {
+    collectRenamedExports(compiler2, statement, found);
+  }
+  return found;
+}
+function collectDeclarations(compiler2, statement, found) {
+  for (const declaration of statement.declarationList.declarations) {
+    if (compiler2.isIdentifier(declaration.name) && declaration.initializer) {
+      found.set(declaration.name.text, declaration.initializer);
+    }
+  }
+}
+function collectRenamedExports(compiler2, statement, found) {
+  if (!compiler2.isExportDeclaration(statement) || !statement.exportClause || !compiler2.isNamedExports(statement.exportClause)) {
+    return;
+  }
+  for (const specifier of statement.exportClause.elements) {
+    if (specifier.propertyName && !found.has(specifier.name.text)) {
+      found.set(specifier.name.text, specifier.propertyName);
     }
-  } catch (error) {
-    genLogger.warn(`Failed to parse route file: ${filePath}`, error);
   }
-  return routes;
 }
-function parseRouterFile(routerPath) {
-  const importPaths = [];
-  const routeNames = [];
+function unwrap(compiler2, expression) {
+  if (!expression) {
+    return void 0;
+  }
+  if (compiler2.isParenthesizedExpression(expression) || compiler2.isAsExpression(expression) || compiler2.isSatisfiesExpression(expression) || compiler2.isNonNullExpression(expression) || compiler2.isTypeAssertionExpression(expression)) {
+    return unwrap(compiler2, expression.expression);
+  }
+  return expression;
+}
+function routesLiteral(compiler2, expression, declarations, seen, factory) {
+  const node = unwrap(compiler2, expression);
+  if (!node) {
+    return void 0;
+  }
+  if (compiler2.isIdentifier(node)) {
+    if (seen.has(node.text)) {
+      return void 0;
+    }
+    seen.add(node.text);
+    return routesLiteral(compiler2, declarations.get(node.text), declarations, seen, factory);
+  }
+  if (!compiler2.isCallExpression(node)) {
+    return void 0;
+  }
+  const callee = unwrap(compiler2, node.expression);
+  if (callee && compiler2.isIdentifier(callee) && callee.text === factory) {
+    const routes = unwrap(compiler2, node.arguments[0]);
+    return routes && compiler2.isObjectLiteralExpression(routes) ? routes : void 0;
+  }
+  return callee && compiler2.isPropertyAccessExpression(callee) ? routesLiteral(compiler2, callee.expression, declarations, seen, factory) : void 0;
+}
+function assertLiteral(compiler2, file, literal, declarations, seen, scan) {
+  for (const property of literal.properties) {
+    if (compiler2.isSpreadAssignment(property)) {
+      assertUnconditionalSpread(compiler2, file, property.expression, scan);
+      continue;
+    }
+    const nested = routesLiteral(compiler2, mountedRouter(compiler2, property), declarations, seen, factoryOf(scan));
+    if (nested) {
+      assertLiteral(compiler2, file, nested, declarations, seen, scan);
+    }
+  }
+}
+function mountedRouter(compiler2, property) {
+  if (compiler2.isPropertyAssignment(property)) {
+    return property.initializer;
+  }
+  return compiler2.isShorthandPropertyAssignment(property) ? property.name : void 0;
+}
+function assertUnconditionalSpread(compiler2, file, expression, scan) {
+  const condition = conditionKind(compiler2, expression);
+  if (!condition) {
+    return;
+  }
+  const wording = REFUSAL_WORDING[factoryOf(scan)];
+  throw new ConditionalRegistrationError(
+    `${scan.routerPath} registers ${wording.noun} conditionally: "...${spreadText(file, expression)}" (${condition}).
+
+The ${scan.subject} is generated from the router as it loads, so a set of ${wording.noun} that depends on a flag or an environment describes whichever way the generator happened to run: ${wording.consequence}.
+` + wording.remedy
+  );
+}
+function conditionKind(compiler2, expression) {
+  const node = unwrap(compiler2, expression);
+  if (!node) {
+    return void 0;
+  }
+  if (compiler2.isConditionalExpression(node)) {
+    return "a ternary";
+  }
+  if (!compiler2.isBinaryExpression(node)) {
+    return void 0;
+  }
+  switch (node.operatorToken.kind) {
+    case compiler2.SyntaxKind.AmpersandAmpersandToken:
+      return "&&";
+    case compiler2.SyntaxKind.BarBarToken:
+      return "||";
+    case compiler2.SyntaxKind.QuestionQuestionToken:
+      return "??";
+    default:
+      return void 0;
+  }
+}
+function spreadText(file, expression) {
+  return expression.getText(file).replace(/\s+/g, " ");
+}
+
+// src/codegen/generators/emit.ts
+function toObjectKey(name) {
+  if (name === "__proto__") {
+    return `[${JSON.stringify(name)}]`;
+  }
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+var SINGLE_QUOTABLE = /^[\x20-\x26\x28-\x5B\x5D-\x7E]*$/;
+function toStringLiteral(value) {
+  if (SINGLE_QUOTABLE.test(value)) {
+    return `'${value}'`;
+  }
+  return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+var loadLogger = logger.child("@spfn/core:codegen");
+function pinNodeEnv() {
+  if (process.env.NODE_ENV) {
+    return;
+  }
+  process.env.NODE_ENV = "production";
+  loadLogger.info('NODE_ENV was unset; pinned to "production" so generated output does not depend on the shell');
+}
+function parseHost(compiler2) {
+  return {
+    useCaseSensitiveFileNames: compiler2.sys.useCaseSensitiveFileNames,
+    readDirectory: () => [],
+    fileExists: compiler2.sys.fileExists,
+    readFile: compiler2.sys.readFile
+  };
+}
+var NO_INPUTS = 18003;
+function targetPath(target, base) {
+  return resolve(base, target.endsWith("/*") ? target.slice(0, -2) : target);
+}
+var UNREADABLE_CODES = /* @__PURE__ */ new Set(["EACCES", "EPERM"]);
+function isUnreadable(error) {
+  return UNREADABLE_CODES.has(error?.code ?? "");
+}
+function targetResolves(target, base) {
+  const path = targetPath(target, base);
+  if (!target.endsWith("/*")) {
+    return existsSync(path);
+  }
   try {
-    const content = readFileSync(routerPath, "utf-8");
-    const importPattern = /import\s+\{[^}]+\}\s+from\s+['"`](\.[^'"`]+)['"`]/g;
-    let match;
-    while ((match = importPattern.exec(content)) !== null) {
-      const importPath = match[1];
-      if (importPath.startsWith(".")) {
-        importPaths.push(importPath);
-      }
+    const stats = statSync(path, { throwIfNoEntry: false });
+    return stats?.isDirectory() === true && readdirSync(path).length > 0;
+  } catch (error) {
+    if (!isUnreadable(error)) {
+      throw error;
     }
-    const defineRouterStart = content.indexOf("defineRouter(");
-    if (defineRouterStart !== -1) {
-      const braceStart = content.indexOf("{", defineRouterStart);
-      if (braceStart !== -1) {
-        let depth = 1;
-        let braceEnd = braceStart + 1;
-        while (depth > 0 && braceEnd < content.length) {
-          if (content[braceEnd] === "{") depth++;
-          else if (content[braceEnd] === "}") depth--;
-          braceEnd++;
-        }
-        const routerContent = content.slice(braceStart + 1, braceEnd - 1);
-        const withoutComments = routerContent.replace(/\/\/[^\n]*/g, "");
-        const namePattern = /^\s*(\w+)\s*[,\n]/gm;
-        while ((match = namePattern.exec(withoutComments)) !== null) {
-          routeNames.push(match[1]);
-        }
-      }
+    return false;
+  }
+}
+function chooseTarget(pattern, targets, base) {
+  const present = targets.filter((target2) => targetResolves(target2, base));
+  const [target] = present.length > 0 ? present : targets;
+  if (!target) {
+    return void 0;
+  }
+  if (present.length > 1) {
+    loadLogger.warn(
+      `tsconfig "paths" maps ${pattern} to ${present.length} targets that could each resolve a module; while the router loads, only the first (${target}) does`
+    );
+  }
+  if (present.length === 0 && targets.length > 1) {
+    loadLogger.warn(
+      `tsconfig "paths" maps ${pattern} to ${targets.length} targets and none of them exists with anything in it; ${target} is used, and an import through it will name itself as unresolved`
+    );
+  }
+  return { target, others: targets.filter((candidate) => candidate !== target) };
+}
+function toAlias(pattern, targets, base) {
+  const choice = chooseTarget(pattern, targets, base);
+  if (!choice) {
+    return void 0;
+  }
+  const { target, others } = choice;
+  if (!pattern.includes("*")) {
+    return { from: pattern, to: resolve(base, target), pattern, target, others };
+  }
+  if (!pattern.endsWith("/*") || !target.endsWith("/*")) {
+    loadLogger.warn(
+      `tsconfig "paths" maps ${pattern} to ${target}, which is not a directory prefix mapping; it will not resolve while the router loads`
+    );
+    return void 0;
+  }
+  return { from: pattern.slice(0, -1), to: resolve(base, target.slice(0, -2)), pattern, target, others };
+}
+function readCompilerOptions(configPath, cwd) {
+  if (!existsSync(configPath)) {
+    return void 0;
+  }
+  const compiler2 = typescript();
+  const { config, error } = compiler2.readConfigFile(configPath, compiler2.sys.readFile);
+  if (error || !config) {
+    loadLogger.warn(`Could not read ${relative(cwd, configPath)}; its path aliases will not resolve`);
+    return void 0;
+  }
+  const parsed = compiler2.parseJsonConfigFileContent(config, parseHost(compiler2), dirname(configPath));
+  for (const diagnostic of parsed.errors) {
+    if (diagnostic.code !== NO_INPUTS) {
+      loadLogger.warn(
+        `${relative(cwd, configPath)}: ${compiler2.flattenDiagnosticMessageText(diagnostic.messageText, " ")} \u2014 path aliases it should have declared may be missing while the router loads`
+      );
     }
+  }
+  return parsed.options;
+}
+function isWithin(root, directory) {
+  const step = relative(root, directory);
+  return step === "" || !step.startsWith("..") && !isAbsolute(step);
+}
+function searchDirectories(cwd, startDir) {
+  const root = resolve(cwd);
+  const directories = [];
+  for (let directory = resolve(startDir); isWithin(root, directory); directory = dirname(directory)) {
+    directories.push(directory);
+    if (directory === root) {
+      return directories;
+    }
+  }
+  return [root];
+}
+function aliasesOf(paths, base) {
+  const aliases = /* @__PURE__ */ new Map();
+  for (const [pattern, targets] of Object.entries(paths)) {
+    const alias = toAlias(pattern, targets, base);
+    if (alias && !aliases.has(alias.from)) {
+      aliases.set(alias.from, alias);
+    }
+  }
+  return [...aliases.values()];
+}
+function projectAliases(cwd, startDir) {
+  for (const directory of searchDirectories(cwd, startDir)) {
+    const options = readCompilerOptions(join(directory, "tsconfig.json"), cwd);
+    if (options?.paths) {
+      const declaredIn = options.pathsBasePath;
+      return aliasesOf(options.paths, options.baseUrl ?? declaredIn ?? directory);
+    }
+  }
+  return [];
+}
+function describeFailure(error, subject, aliases) {
+  const message = error instanceof Error ? error.message : String(error);
+  const unresolved = /Cannot find module '([^']+)'/.exec(message);
+  if (!unresolved) {
+    return `${message}
+
+The ${subject} is read from the loaded router, so a route module must be importable without side effects. Check that nothing at module scope opens a connection or reads a missing environment value.`;
+  }
+  return `${message.split("\n")[0]}
+
+"${unresolved[1]}" did not resolve while the router was being imported. Imports resolve through Node and through the "paths" of the nearest tsconfig.json that declares them, searching from the router file up to the project root. Check that the specifier is mapped in one of those, and that what it points at exists: a workspace package resolves to a dist/ that has to have been built.` + describePassedOverTargets(unresolved[1], aliases);
+}
+function describePassedOverTargets(specifier, aliases) {
+  const alias = aliases.find((entry) => specifier.startsWith(entry.from) || specifier.startsWith(entry.to));
+  if (!alias || alias.others.length === 0) {
+    return "";
+  }
+  return `
+
+It was resolved through "${alias.target}", the first target of the "paths" entry "${alias.pattern}" that names a directory holding anything. That entry also lists ${alias.others.map((other) => `"${other}"`).join(", ")}, which the router load never tried: one alias per key is all the loader can express, so the whole load goes through a single target.`;
+}
+function loadRouterModule(load) {
+  const { cwd, absoluteRouterPath, subject, fail } = load;
+  const aliases = projectAliases(cwd, dirname(absoluteRouterPath));
+  const jiti = createJiti(cwd, {
+    interopDefault: true,
+    moduleCache: false,
+    alias: Object.fromEntries(aliases.map((alias) => [alias.from, alias.to]))
+  });
+  try {
+    return jiti(absoluteRouterPath);
   } catch (error) {
-    genLogger.warn(`Failed to parse router file: ${routerPath}`, error);
+    throw fail(
+      `Failed to load ${relative(cwd, absoluteRouterPath)}: ${describeFailure(error, subject, aliases)}`
+    );
+  }
+}
+function isRouter(value) {
+  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
+}
+function resolveRouterExport(module, candidates) {
+  for (const exportName of candidates) {
+    const candidate = module[exportName];
+    if (isRouter(candidate)) {
+      return { router: candidate, exportName };
+    }
+  }
+  return void 0;
+}
+
+// src/codegen/generators/route-map.ts
+var genLogger = logger.child("@spfn/core:route-map-generator");
+var RouteMapGeneratorError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RouteMapGeneratorError";
+  }
+};
+function isRouteDef(value) {
+  return value !== null && typeof value === "object" && "handler" in value;
+}
+var ROUTER_EXPORTS = ["appRouter", "default", "router"];
+function loadRouter(cwd, absoluteRouterPath) {
+  const module = loadRouterModule({
+    cwd,
+    absoluteRouterPath,
+    subject: "route map",
+    fail: (message) => new RouteMapGeneratorError(message)
+  });
+  const resolved = resolveRouterExport(module, ROUTER_EXPORTS);
+  if (resolved) {
+    return resolved;
+  }
+  throw new RouteMapGeneratorError(
+    `No router found in ${relative(cwd, absoluteRouterPath)}. Looked for: ${ROUTER_EXPORTS.join(", ")}. Export the defineRouter() result under one of those names.`
+  );
+}
+var HTTP_METHODS = { GET: true, POST: true, PUT: true, PATCH: true, DELETE: true };
+function duplicateNameError(origin, name, existing, where) {
+  if (origin === "app") {
+    return new RouteMapGeneratorError(
+      `Two routes are both named "${name}" (${existing.trail} and ${where}). The RPC client addresses a route by its name alone, and a nested route registers under its own key, so a name must be unique across the whole router.`
+    );
+  }
+  return new RouteMapGeneratorError(
+    `Two package routers both register a route named "${name}" (${existing.trail} and ${where}). Both are written into this app's route map, which holds one entry per name, so one of the two packages would have its client call the other package's path. Nothing of this app's can be renamed to fix it: drop one of the two mounts, or raise the name with the package that took it second.`
+  );
+}
+function addRoute(name, routeDef, trail, into, origin) {
+  const where = trail.join(".");
+  if (!routeDef.method || !routeDef.path) {
+    genLogger.warn(
+      `Route "${where}" has no method or path and is left out of the map. The RPC client resolves a name to a method and a path, so both are required. A route reaches this state by being registered before .handler() was called \u2014 the server skips it too.`
+    );
+    return void 0;
+  }
+  if (!Object.hasOwn(HTTP_METHODS, routeDef.method)) {
+    throw new RouteMapGeneratorError(
+      `Route "${where}" declares the method "${routeDef.method}", which is not an HttpMethod (${Object.keys(HTTP_METHODS).join(", ")}). The generated map is typed HttpMethod, so naming it would write a file that does not compile.`
+    );
+  }
+  const existing = into.get(name);
+  if (existing) {
+    if (origin === "package" && existing.def === routeDef) {
+      return void 0;
+    }
+    throw duplicateNameError(origin, name, existing, where);
+  }
+  const collected = {
+    method: routeDef.method,
+    path: routeDef.path,
+    trail: where,
+    def: routeDef
+  };
+  into.set(name, collected);
+  return collected;
+}
+function pathPrefix(path) {
+  const [, first] = path.split("/");
+  return first ? `/${first}` : path;
+}
+function collectPackageRoutes(router, trail, mount, collection) {
+  if (router._publishesRouteMap === false || collection.visited.has(router)) {
+    return;
+  }
+  collection.visited.set(router, trail.join("."));
+  for (const [name, entry] of Object.entries(router.routes)) {
+    if (isRouter(entry)) {
+      collectPackageRoutes(entry, [...trail, name], mount, collection);
+      continue;
+    }
+    if (!isRouteDef(entry)) {
+      genLogger.warn(
+        `Package router entry "${[...trail, name].join(".")}" is neither a route nor a router (got ${typeof entry}) and is left out of the map. \`registerRoutes\` skips it too.`
+      );
+      continue;
+    }
+    const collected = addRoute(name, entry, [...trail, name], collection.packages, "package");
+    if (collected) {
+      mount.count += 1;
+      mount.prefixes.add(pathPrefix(collected.path));
+      continue;
+    }
+    const already = collection.packages.get(name);
+    if (already?.def === entry) {
+      mount.sharedWith ??= already.trail;
+    }
+  }
+  for (const [index, nested] of (router._packageRouters ?? []).entries()) {
+    collectPackageRoutes(nested, [...trail, `packages[${index}]`], mount, collection);
+  }
+}
+function mountPackageRouter(router, label, collection) {
+  const mount = { label, count: 0, prefixes: /* @__PURE__ */ new Set() };
+  const alreadyAt = collection.visited.get(router);
+  if (router._publishesRouteMap === false) {
+    mount.skipped = "publishes no route map";
+  } else if (alreadyAt) {
+    mount.skipped = `already reached through ${alreadyAt}`;
   }
-  return { importPaths, routeNames };
+  collectPackageRoutes(router, [label], mount, collection);
+  if (mount.count === 0 && !mount.skipped && mount.sharedWith) {
+    mount.skipped = `every route it holds was already collected through ${mount.sharedWith}`;
+  }
+  collection.mounts.push(mount);
+  return mount;
 }
-function generateRouteMapContent(routes) {
+function collectRoutes(router, trail, collection) {
+  for (const [name, entry] of Object.entries(router.routes)) {
+    if (isRouter(entry)) {
+      collectRoutes(entry, [...trail, name], collection);
+      continue;
+    }
+    if (!isRouteDef(entry)) {
+      genLogger.warn(
+        `Router entry "${[...trail, name].join(".")}" is neither a route nor a router (got ${typeof entry}) and is left out of the map. \`registerRoutes\` skips it too, so no name the client can call goes unanswered.`
+      );
+      continue;
+    }
+    addRoute(name, entry, [...trail, name], collection.app, "app");
+  }
+  for (const [index, packageRouter] of (router._packageRouters ?? []).entries()) {
+    mountPackageRouter(packageRouter, `${trail.join(".")}.packages[${index}]`, collection);
+  }
+}
+function assertNoPackageCollision(collection) {
+  for (const [name, route] of collection.packages) {
+    const appRoute = collection.app.get(name);
+    if (!appRoute) {
+      continue;
+    }
+    throw new RouteMapGeneratorError(
+      `The app route "${name}" (${appRoute.trail}) is also registered by a package router (${route.trail}). Both go into this app's generated route map, which holds one entry per name, so one of the two paths becomes unreachable while the typed client still describes the app's route. Rename the app route.`
+    );
+  }
+}
+function collectRouteMap(router) {
+  const collection = {
+    app: /* @__PURE__ */ new Map(),
+    packages: /* @__PURE__ */ new Map(),
+    mounts: [],
+    visited: /* @__PURE__ */ new Map()
+  };
+  collectRoutes(router, ["router"], collection);
+  assertNoPackageCollision(collection);
+  return collection;
+}
+function describeMount(mount) {
+  if (mount.count === 0) {
+    return `${mount.label} \u2014 no routes${mount.skipped ? ` (${mount.skipped})` : ""}`;
+  }
+  const routes = `${mount.count} route${mount.count === 1 ? "" : "s"}`;
+  return `${mount.label} \u2014 ${routes} under ${[...mount.prefixes].join(", ")}`;
+}
+function packageHeaderLines(collection) {
+  if (collection.packages.size === 0) {
+    return [];
+  }
+  return [
+    " *",
+    " * The entries under the .packages() line below are not this app's. They belong",
+    " * to the package routers it mounts, copied in as they were when this file was",
+    " * generated:",
+    ...collection.mounts.map((mount) => ` *   ${describeMount(mount)}`),
+    " *",
+    " * A package upgrade reaches them only through a regeneration: `spfn build`",
+    " * regenerates before it compiles, a bare `next build` uses what is committed here."
+  ];
+}
+function generateRouteMapContent(collection, nodeEnv) {
   const lines = [
     "/**",
     " * Route Map (Auto-generated)",
     " *",
     " * DO NOT EDIT - This file is generated by @spfn/core:route-map generator",
+    " *",
+    ` * Generated with NODE_ENV=${nodeEnv}. A route registered only under one environment is`,
+    " * named here only when the generator ran under it, so this line changing is that",
+    " * difference rather than an edit.",
+    ...packageHeaderLines(collection),
     " */",
     "",
     "import type { HttpMethod } from '@spfn/core/route';",
@@ -410,8 +893,14 @@ function generateRouteMapContent(routes) {
     "",
     "export const routeMap: Record<string, RouteInfo> = {"
   ];
-  for (const route of routes) {
-    lines.push(`    ${route.name}: { method: '${route.method}', path: '${route.path}' },`);
+  for (const [name, route] of collection.app) {
+    lines.push(entryLine(name, route));
+  }
+  if (collection.packages.size > 0) {
+    lines.push("    // From the package routers this app mounts with .packages(), not its own:");
+    for (const [name, route] of collection.packages) {
+      lines.push(entryLine(name, route));
+    }
   }
   lines.push("};");
   lines.push("");
@@ -421,6 +910,9 @@ function generateRouteMapContent(routes) {
   lines.push("");
   return lines.join("\n");
 }
+function entryLine(name, route) {
+  return `    ${toObjectKey(name)}: { method: '${route.method}', path: ${toStringLiteral(route.path)} },`;
+}
 function createRouteMapGenerator(config) {
   const {
     routerPath,
@@ -440,9 +932,11 @@ Usage:
   }
   return {
     name: "@spfn/core:route-map",
+    // Unchanged, including the deprecated dirs: what the map is *built* from
+    // moved to the loaded router, but what a rebuild should be *triggered* by
+    // is still every file a route can live in.
     watchPatterns: [
       routerPath,
-      // Watch route directories derived from router imports
       "src/server/routes/**/*.ts",
       ...additionalRouteDirs.map((dir) => `${dir}/**/*.ts`)
     ],
@@ -456,97 +950,36 @@ Usage:
         return;
       }
       if (debug) {
-        genLogger.info("Parsing router file", { path: absoluteRouterPath });
-      }
-      const { importPaths, routeNames } = parseRouterFile(absoluteRouterPath);
-      if (debug) {
-        genLogger.info("Found route imports", { count: importPaths.length, names: routeNames });
-      }
-      const routerDir = dirname(absoluteRouterPath);
-      const allRoutes = [];
-      for (const importPath of importPaths) {
-        let resolvedPath = resolve(routerDir, importPath);
-        if (!resolvedPath.endsWith(".ts")) {
-          const withTs = resolvedPath + ".ts";
-          if (existsSync(withTs)) {
-            resolvedPath = withTs;
-          } else {
-            const indexPath = join(resolvedPath, "index.ts");
-            if (existsSync(indexPath)) {
-              resolvedPath = indexPath;
-            } else {
-              resolvedPath = withTs;
-            }
-          }
-        }
-        if (existsSync(resolvedPath)) {
-          const routes = parseRouteFile(resolvedPath);
-          allRoutes.push(...routes);
-          if (debug) {
-            genLogger.info(`Parsed ${routes.length} routes from ${relative(cwd, resolvedPath)}`);
-          }
-        }
+        genLogger.info("Loading router", { path: absoluteRouterPath });
       }
-      const exportedRoutes = allRoutes.filter((r) => routeNames.includes(r.name));
+      pinNodeEnv();
+      const { router, exportName } = loadRouter(cwd, absoluteRouterPath);
+      assertUnconditionalRegistration({
+        routerPath,
+        source: readFileSync(absoluteRouterPath, "utf-8"),
+        exportName,
+        subject: "route map"
+      });
+      const collection = collectRouteMap(router);
+      const total = collection.app.size + collection.packages.size;
       if (debug) {
-        genLogger.info(`Found ${exportedRoutes.length} exported routes`);
+        genLogger.info(`Found ${total} routes`, {
+          app: [...collection.app.keys()],
+          packages: [...collection.packages.keys()]
+        });
       }
-      const content = generateRouteMapContent(exportedRoutes);
       const outputDir = dirname(absoluteOutputPath);
       if (!existsSync(outputDir)) {
         mkdirSync(outputDir, { recursive: true });
       }
-      writeFileSync(absoluteOutputPath, content, "utf-8");
-      genLogger.info(`Generated route map: ${relative(cwd, absoluteOutputPath)} (${exportedRoutes.length} routes)`);
+      const nodeEnv = process.env.NODE_ENV ?? "unset";
+      writeFileSync(absoluteOutputPath, generateRouteMapContent(collection, nodeEnv), "utf-8");
+      genLogger.info(
+        `Generated route map: ${relative(cwd, absoluteOutputPath)} (${collection.app.size} app routes, ${collection.packages.size} from mounted packages)`
+      );
     }
   };
 }
-
-// src/codegen/generators/contract-guard.ts
-var ConditionalRegistrationError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ConditionalRegistrationError";
-  }
-};
-function defineRouterBlock(source) {
-  const start = source.indexOf("defineRouter(");
-  if (start === -1) {
-    return void 0;
-  }
-  const open = source.indexOf("{", start);
-  if (open === -1) {
-    return void 0;
-  }
-  let depth = 1;
-  let cursor = open + 1;
-  while (depth > 0 && cursor < source.length) {
-    if (source[cursor] === "{") depth++;
-    else if (source[cursor] === "}") depth--;
-    cursor++;
-  }
-  return source.slice(open + 1, cursor - 1).replace(/\/\/[^\n]*/g, "");
-}
-var PLAIN_REFERENCE = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*\s*$/;
-function assertUnconditionalRegistration(routerPath, source) {
-  const block = defineRouterBlock(source);
-  if (!block) {
-    return;
-  }
-  for (const [, expression] of block.matchAll(/\.\.\.\s*([^,\n]+)/g)) {
-    if (PLAIN_REFERENCE.test(expression)) {
-      continue;
-    }
-    throw new ConditionalRegistrationError(
-      `${routerPath} registers routes conditionally: "...${expression.trim()}".
-
-A contract has to describe what production serves. When the route set depends on a flag or an environment, the generated contract describes whichever way the generator happened to run.
-Register contracted routes unconditionally, and gate behaviour inside the handler instead.`
-    );
-  }
-}
-
-// src/codegen/generators/contract.ts
 var genLogger2 = logger.child("@spfn/core:contract-generator");
 var ContractGeneratorError = class extends Error {
   constructor(message) {
@@ -554,43 +987,67 @@ var ContractGeneratorError = class extends Error {
     this.name = "ContractGeneratorError";
   }
 };
-function isRouter(value) {
-  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
-}
-function loadRouter(cwd, absoluteRouterPath, routerExport) {
-  let module;
-  try {
-    const jiti = createJiti(cwd, { interopDefault: true, moduleCache: false });
-    module = jiti(absoluteRouterPath);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new ContractGeneratorError(
-      `Failed to load ${relative(cwd, absoluteRouterPath)}: ${message}
-
-The contract is read from the loaded router, so a route module must be importable without side effects. Check that nothing at module scope opens a connection or reads a missing environment value.`
-    );
-  }
+function loadRouter2(cwd, absoluteRouterPath, routerExport) {
+  const module = loadRouterModule({
+    cwd,
+    absoluteRouterPath,
+    subject: "contract",
+    fail: (message) => new ContractGeneratorError(message)
+  });
   const candidates = routerExport ? [routerExport] : ["appRouter", "default", "router"];
-  for (const name of candidates) {
-    const candidate = module[name];
-    if (isRouter(candidate)) {
-      return candidate;
-    }
+  const resolved = resolveRouterExport(module, candidates);
+  if (resolved) {
+    return resolved;
   }
   throw new ContractGeneratorError(
     `No router found in ${relative(cwd, absoluteRouterPath)}. Looked for: ${candidates.join(", ")}. Set "routerExport" to the export holding the defineRouter() result.`
   );
 }
-function pinNodeEnv() {
-  if (!process.env.NODE_ENV) {
-    process.env.NODE_ENV = "production";
-    genLogger2.info('NODE_ENV was unset; pinned to "production" so the contract does not depend on the shell');
+function isEventRouter(value) {
+  return value !== null && typeof value === "object" && "events" in value && "eventNames" in value;
+}
+function loadEventRouter(cwd, absolutePath, eventRouterExport) {
+  const module = loadRouterModule({
+    cwd,
+    absoluteRouterPath: absolutePath,
+    subject: "contract",
+    fail: (message) => new ContractGeneratorError(message)
+  });
+  const candidates = eventRouterExport ? [eventRouterExport] : ["eventRouter", "default"];
+  const exportName = candidates.find((candidate) => isEventRouter(module[candidate]));
+  if (exportName) {
+    return { eventRouter: module[exportName], exportName };
+  }
+  throw new ContractGeneratorError(
+    `No event router found in ${relative(cwd, absolutePath)}. Looked for: ${candidates.join(", ")}. Set "eventRouterExport" to the export holding the defineEventRouter() result.`
+  );
+}
+function readEventRouter(cwd, eventRouterPath, eventRouterExport) {
+  if (!eventRouterPath) {
+    return void 0;
   }
+  const absolutePath = join(cwd, eventRouterPath);
+  if (!existsSync(absolutePath)) {
+    throw new ContractGeneratorError(
+      `Event router file not found: ${eventRouterPath}. The contract generator is configured with "eventRouterPath" but has nothing to read there.`
+    );
+  }
+  const { eventRouter, exportName } = loadEventRouter(cwd, absolutePath, eventRouterExport);
+  assertUnconditionalRegistration({
+    routerPath: eventRouterPath,
+    source: readFileSync(absolutePath, "utf-8"),
+    exportName,
+    subject: "contract",
+    factory: "defineEventRouter"
+  });
+  return eventRouter;
 }
 function createContractGenerator(config) {
   const {
     routerPath,
     routerExport,
+    eventRouterPath,
+    eventRouterExport,
     outputDir = "./contracts",
     additionalRouteDirs = []
   } = config;
@@ -609,6 +1066,7 @@ Usage:
     name: "@spfn/core:contract",
     watchPatterns: [
       routerPath,
+      ...eventRouterPath ? [eventRouterPath] : [],
       "src/server/routes/**/*.ts",
       ...additionalRouteDirs.map((dir) => `${dir}/**/*.ts`)
     ],
@@ -623,9 +1081,14 @@ Usage:
         );
       }
       pinNodeEnv();
-      assertUnconditionalRegistration(routerPath, readFileSync(absoluteRouterPath, "utf-8"));
-      const router = loadRouter(cwd, absoluteRouterPath, routerExport);
-      const document = collectContractDocument(router);
+      const { router, exportName } = loadRouter2(cwd, absoluteRouterPath, routerExport);
+      assertUnconditionalRegistration({
+        routerPath,
+        source: readFileSync(absoluteRouterPath, "utf-8"),
+        exportName,
+        subject: "contract"
+      });
+      const document = collectContractDocument(router, readEventRouter(cwd, eventRouterPath, eventRouterExport));
       const changed = writeCurrentDocument(contractsDir, document);
       genLogger2.info(
         `${changed ? "Wrote" : "Verified"} ${relative(cwd, join(contractsDir, "current.json"))} (${document.operations.length} contracted operation(s))`
@@ -653,13 +1116,156 @@ A released client cannot be fixed by redeploying the server. Keep the promise, o
     }
   };
 }
+var genLogger3 = logger.child("@spfn/core:states-generator");
+var StatesGeneratorError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StatesGeneratorError";
+  }
+};
+var ROUTER_EXPORTS2 = ["appRouter", "default", "router"];
+function loadRouter3(cwd, absoluteRouterPath) {
+  const module = loadRouterModule({
+    cwd,
+    absoluteRouterPath,
+    subject: "state manifest",
+    fail: (message) => new StatesGeneratorError(message)
+  });
+  const resolved = resolveRouterExport(module, ROUTER_EXPORTS2);
+  if (resolved) {
+    return resolved;
+  }
+  throw new StatesGeneratorError(
+    `No router found in ${relative(cwd, absoluteRouterPath)}. Looked for: ${ROUTER_EXPORTS2.join(", ")}. Export the defineRouter() result under one of those names.`
+  );
+}
+function collectStates(router, trail, visited, into) {
+  if (visited.has(router)) {
+    return 0;
+  }
+  visited.add(router);
+  let stateRouters = addStates(router, trail.join("."), into) ? 1 : 0;
+  for (const [name, entry] of Object.entries(router.routes)) {
+    if (isRouter(entry)) {
+      stateRouters += collectStates(entry, [...trail, name], visited, into);
+    }
+  }
+  for (const [index, nested] of (router._packageRouters ?? []).entries()) {
+    stateRouters += collectStates(nested, [...trail, `packages[${index}]`], visited, into);
+  }
+  return stateRouters;
+}
+function addStates(router, trail, into) {
+  if (!Object.hasOwn(router, "_stateManifest")) {
+    return false;
+  }
+  for (const [id, entry] of Object.entries(router._stateManifest ?? {})) {
+    const existing = into.get(id);
+    if (existing) {
+      throw new StatesGeneratorError(
+        `Two state routers both declare a state "${id}" (${existing.trail} and ${trail}). The browser addresses a state by its id alone and the generated manifest holds one entry per id, so one of the two would be read through the other's routes. Rename one of the states, or mount one of the two routers only.`
+      );
+    }
+    into.set(id, { entry, trail });
+  }
+  return true;
+}
+function collectDeclaredStates(router, routerPath) {
+  const states = /* @__PURE__ */ new Map();
+  if (collectStates(router, ["router"], /* @__PURE__ */ new Set(), states) === 0) {
+    throw new StatesGeneratorError(
+      `No state router is mounted by ${routerPath}. The @spfn/core:states generator is configured, but nothing it reads mounts a defineStateRouter(...).router, so the file it would write could not say which states the app declared, and every id the server serves would read as a skew. Mount the state router \u2014 \`appRouter.packages([states.router])\` \u2014 or remove the generator from .spfnrc.ts.`
+    );
+  }
+  return states;
+}
+function entryLine2(id, entry) {
+  return `    ${toObjectKey(id)}: { key: [${entry.key.map(toStringLiteral).join(", ")}], write: ${entry.write} },`;
+}
+function generateStatesContent(states, nodeEnv) {
+  const ids = [...states.keys()];
+  return [
+    "/**",
+    " * State Manifest (Auto-generated)",
+    " *",
+    " * DO NOT EDIT - This file is generated by @spfn/core:states generator",
+    " *",
+    ` * Generated with NODE_ENV=${nodeEnv}. A state router mounted only under one environment is`,
+    " * named here only when the generator ran under it, so this line changing is that",
+    " * difference rather than an edit.",
+    " *",
+    " * Compare `stateManifest` with the `manifest` of `GET <state path>` (or of the snapshot a",
+    " * server component read): an id here that the server's manifest lacks, or an entry that",
+    " * differs, is a deploy skew between this build and the API.",
+    " */",
+    "",
+    `export const stateIds = [${ids.map(toStringLiteral).join(", ")}] as const;`,
+    "",
+    "export type StateId = (typeof stateIds)[number];",
+    "",
+    "export const stateManifest: Readonly<Record<StateId, { readonly key: readonly string[]; readonly write: boolean }>> = {",
+    ...ids.map((id) => entryLine2(id, states.get(id).entry)),
+    "};",
+    ""
+  ].join("\n");
+}
+function createStatesGenerator(config) {
+  const { routerPath, outputPath = "./src/generated/states.ts" } = config;
+  if (!routerPath) {
+    throw new Error(
+      `[@spfn/core:states] Missing required "routerPath" option.
+
+Usage:
+  defineGenerator<StatesGeneratorConfig>({
+    name: '@spfn/core:states',
+    routerPath: './src/server/router.ts',
+  })`
+    );
+  }
+  return {
+    name: "@spfn/core:states",
+    watchPatterns: [
+      routerPath,
+      "src/server/states.ts",
+      "src/server/states/**/*.ts",
+      "src/server/routes/**/*.ts"
+    ],
+    runOn: ["watch", "manual", "build"],
+    async generate(options) {
+      const { cwd, debug } = options;
+      const absoluteRouterPath = join(cwd, routerPath);
+      const absoluteOutputPath = join(cwd, outputPath);
+      if (!existsSync(absoluteRouterPath)) {
+        genLogger3.warn(`Router file not found: ${absoluteRouterPath}`);
+        return;
+      }
+      pinNodeEnv();
+      const { router, exportName } = loadRouter3(cwd, absoluteRouterPath);
+      assertUnconditionalRegistration({
+        routerPath,
+        source: readFileSync(absoluteRouterPath, "utf-8"),
+        exportName,
+        subject: "state manifest"
+      });
+      const states = collectDeclaredStates(router, routerPath);
+      if (debug) {
+        genLogger3.info(`Found ${states.size} states`, { ids: [...states.keys()] });
+      }
+      mkdirSync(dirname(absoluteOutputPath), { recursive: true });
+      const nodeEnv = process.env.NODE_ENV ?? "unset";
+      writeFileSync(absoluteOutputPath, generateStatesContent(states, nodeEnv), "utf-8");
+      genLogger3.info(`Generated states: ${relative(cwd, absoluteOutputPath)} (${states.size} states)`);
+    }
+  };
+}
 
 // src/codegen/generators/index.ts
 var generators = {
   "route-map": createRouteMapGenerator,
-  contract: createContractGenerator
+  contract: createContractGenerator,
+  states: createStatesGenerator
 };
 
-export { CodegenOrchestrator, ConditionalRegistrationError, ContractGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
+export { CodegenOrchestrator, ConditionalRegistrationError, ContractGeneratorError, RouteMapGeneratorError, StatesGeneratorError, assertUnconditionalRegistration, createGeneratorsFromConfig, defineConfig, defineGenerator, generators, loadCodegenConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map