@luckystack/devkit 0.10.2 → 0.11.0

package/dist/validateDeploy.d.ts

@@ -0,0 +1,25 @@
+import type { DeployConfigShape, ServicesConfigShape } from '@luckystack/core';
+export type ValidationSeverity = 'error' | 'warning';
+export interface ValidationFinding {
+    severity: ValidationSeverity;
+    code: string;
+    message: string;
+    /** Human-readable location pointer (e.g. `services.config.ts > presets.api`). */
+    location?: string;
+}
+export interface ValidateDeployInput {
+    services: ServicesConfigShape;
+    deploy: DeployConfigShape;
+    /**
+     * Environment values to consult for `synchronizedEnvKeys` / `urlEnvKey`
+     * presence checks. Defaults to `process.env`. Pass a fixture for tests.
+     */
+    env?: Record<string, string | undefined>;
+}
+export interface ValidateDeployResult {
+    ok: boolean;
+    findings: ValidationFinding[];
+    errorCount: number;
+    warningCount: number;
+}
+export declare const validateDeploy: ({ services, deploy, env, }: ValidateDeployInput) => ValidateDeployResult;

package/docs/cli.md

@@ -1,245 +1,5 @@
-# CLI (`luckystack-validate-deploy` + `validateDeploy`)
+# Deployment validation CLI
 
-> Dev / build-time only. The CLI is the pre-deploy gate that runs against compiled `services.config.js` + `deploy.config.js` artifacts. The validator itself (`validateDeploy`) is a pure function — safe to call directly from a build script without going through the CLI.
+Validate compiled deployment and service registrations before shipping a multi-service bundle. The validator catches unbound services, broken preset references and unresolved environment references earlier than a live router would. Run `luckystack-validate-deploy --help` for current arguments and exit behavior; the validator source owns its checks and finding shapes.
 
-`@luckystack/devkit` ships a single bin entry:
-
-```json
-{
-  "bin": {
-    "luckystack-validate-deploy": "./dist/cli/validateDeploy.js"
-  }
-}
-```
-
-The CLI is a thin wrapper around `validateDeploy()` from `src/validateDeploy.ts`. The validator runs nine rules against the project's `services.config` + `deploy.config` snapshots and returns a structured `ValidateDeployResult` with one finding per detected problem.
-
----
-
-## CLI surface
-
-```
-USAGE
-  luckystack-validate-deploy --deploy <file> --services <file> [options]
-
-REQUIRED
-  --deploy, -d <file>      Path to compiled deploy.config.js (registers DeployConfig).
-  --services, -s <file>    Path to compiled services.config.js (registers ServicesConfig).
-
-OPTIONS
-  --strict                 Exit 1 on warnings as well as errors.
-  --help, -h               Show this help.
-```
-
-Argument parsing (`parseArgs(argv)`):
-
-```typescript
-interface CliArgs {
-  deploy: string | null;
-  services: string | null;
-  failOnWarning: boolean;
-}
-```
-
-Both config paths are required. There is no implicit search of the working directory — the CLI demands an explicit path so build pipelines can't accidentally pick up a stale untracked file.
-
----
-
-## Side-effect import order
-
-```typescript
-await importConfig(args.deploy, 'deploy config');
-await importConfig(args.services, 'services config');
-
-if (!isDeployConfigRegistered()) {
-  // exit 2 with hint
-}
-if (!isServicesConfigRegistered()) {
-  // exit 2 with hint
-}
-```
-
-The compiled config files are expected to call `registerDeployConfig(...)` / `registerServicesConfig(...)` (re-exported from `@luckystack/core`) as a side effect of import. The CLI imports each file via `pathToFileURL(absolute).href` (Windows-safe), then probes the registry with `isDeployConfigRegistered()` / `isServicesConfigRegistered()`.
-
-If a file imports cleanly but doesn't register, the CLI exits with code 2 and a message:
-
-```
-[luckystack-validate-deploy] deploy config file did not call registerDeployConfig — nothing to validate.
-```
-
-This is the most common authoring mistake: forgetting the registration call leaves a silent empty registry, which would otherwise pass validation with zero findings.
-
-`importConfig` wraps the dynamic import in a try/catch and re-throws with a clearer message including the absolute path:
-
-```typescript
-const importConfig = async (file: string, label: string): Promise<void> => {
-  const abs = path.isAbsolute(file) ? file : path.join(process.cwd(), file);
-  try {
-    await import(pathToFileURL(abs).href);
-  } catch (error) {
-    throw new Error(`[luckystack-validate-deploy] failed to import ${label} at ${abs}: ${message}`);
-  }
-};
-```
-
----
-
-## `validateDeploy(input)` — pure validator
-
-Defined in `packages/devkit/src/validateDeploy.ts`. Public types:
-
-```typescript
-export type ValidationSeverity = 'error' | 'warning';
-
-export interface ValidationFinding {
-  severity: ValidationSeverity;
-  code: string;
-  message: string;
-  /** Human-readable location pointer (e.g. `services.config.ts > presets.api`). */
-  location?: string;
-}
-
-export interface ValidateDeployInput {
-  services: ServicesConfigShape;
-  deploy: DeployConfigShape;
-  env?: Record<string, string | undefined>; // defaults to process.env
-}
-
-export interface ValidateDeployResult {
-  ok: boolean;
-  findings: ValidationFinding[];
-  errorCount: number;
-  warningCount: number;
-}
-
-export const validateDeploy = ({ services, deploy, env = process.env }: ValidateDeployInput): ValidateDeployResult;
-```
-
-`ServicesConfigShape` / `DeployConfigShape` are re-exported from `@luckystack/core` and define the canonical shape of the two config files. The validator never reads from disk — it works exclusively from the in-memory snapshots passed in.
-
-### Rules
-
-| # | Rule | Code | Severity |
-|---|---|---|---|
-| 1 | Every service is assigned to exactly one preset | `service-unassigned`, `service-in-multiple-presets` | error |
-| 2 | Every preset references services that exist | `preset-references-unknown-service` | error |
-| 3 | Every environment binding's service matches an actual service | `binding-references-unknown-service` | error |
-| 3a | Every environment binding URL parses as a valid URL | `binding-invalid-url` | error |
-| 3b | Every environment binding URL declares an explicit port | `binding-missing-port` | error |
-| 4 | Every environment's redis/mongo resource keys exist | `unknown-redis-resource`, `unknown-mongo-resource` | error |
-| 5 | Fallback envs must share the same redis/mongo resource keys (shared-resource invariant) | `unknown-fallback-env`, `fallback-redis-mismatch`, `fallback-mongo-mismatch` | error |
-| 6 | `urlEnvKey` values resolve at config time | `missing-resource-env-var` | warning |
-| 7 | `synchronizedEnvKeys` values resolve at config time | `missing-synchronized-env-var` | warning |
-| 8 | Services bound in no environment | `service-bound-in-no-environment` | warning |
-
-Each rule pushes one or more `ValidationFinding` records into a single result array; the validator never throws. The CLI iterates findings and prints each one before deciding the exit code.
-
-### Findings output
-
-```typescript
-const printFinding = (finding: ValidationFinding): void => {
-  const tag = finding.severity === 'error'
-    ? `<red bold>ERROR</red>`
-    : `<yellow bold>WARN </yellow>`;
-  const code = `<dim>[${finding.code}]</dim>`;
-  const location = finding.location ? `\n  <dim>at ${finding.location}</dim>` : '';
-  const sink = finding.severity === 'error' ? process.stderr : process.stdout;
-  sink.write(`${tag} ${code} ${finding.message}${location}\n`);
-};
-```
-
-- Errors go to stderr, warnings to stdout — so CI pipelines that only mirror stderr see failures cleanly.
-- ANSI color is only applied when stdout is a TTY (`process.stdout.isTTY`). Piping the CLI through `tee`, redirecting to a file, or running under non-TTY CI yields plain text.
-- The trailing summary line is the same as a single finding: `OK — 0 error(s), 2 warning(s)` (green) or `FAILED — 1 error(s), 0 warning(s)` (red).
-
-### Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | No errors. Warnings are allowed unless `--strict`. |
-| `1` | At least one error finding, OR `--strict` with at least one warning. |
-| `2` | Bad CLI usage: missing required flag, failed import, or config file didn't call its register function. |
-
-Designed to be a pre-deploy gate — the recommended placement is the last step of `npm run build` or a dedicated CI job after `tsc -p tsconfig.build.json`.
-
----
-
-## Calling from a build script
-
-```typescript
-import { validateDeploy } from '@luckystack/devkit';
-import { getServicesConfig, getDeployConfig } from '@luckystack/core';
-
-await import('./services.config');
-await import('./deploy.config');
-
-const result = validateDeploy({
-  services: getServicesConfig(),
-  deploy: getDeployConfig(),
-});
-
-if (!result.ok) {
-  for (const finding of result.findings) {
-    console.error(finding);
-  }
-  process.exit(1);
-}
-```
-
-`validateDeploy` is pure and has no I/O. Pass a `env` fixture in tests:
-
-```typescript
-const result = validateDeploy({
-  services: testServices,
-  deploy: testDeploy,
-  env: {
-    REDIS_URL: 'redis://localhost:6379',
-    // MONGO_URL deliberately absent to trigger the warning
-  },
-});
-
-expect(result.findings.map(f => f.code)).toContain('missing-resource-env-var');
-```
-
-The CLI is sugar; library consumers should reach for `validateDeploy` directly and decide their own exit behavior.
-
----
-
-## Failure modes
-
-| Symptom | Cause | Exit code |
-|---|---|---|
-| `--deploy and --services are required.` | Missing required flag | 2 |
-| `failed to import deploy config at <path>: ...` | The file path is wrong, throws on evaluation, or is missing | 2 |
-| `... did not call registerDeployConfig — nothing to validate` | Import succeeded but the consumer forgot the registration call | 2 |
-| `ERROR [service-unassigned] ...` | A service in `services.services` isn't in any preset | 1 |
-| `ERROR [preset-references-unknown-service] ...` | A preset references a service that doesn't exist | 1 |
-| `ERROR [binding-invalid-url] ...` | A binding URL in `deploy.config.ts > environments.<env>.bindings.<service>` doesn't parse as a valid URL | 1 |
-| `ERROR [binding-missing-port] ...` | A binding URL in `deploy.config.ts > environments.<env>.bindings.<service>` is missing an explicit port — the router requires one to disambiguate per-preset backends | 1 |
-| `ERROR [fallback-redis-mismatch] ...` | Two envs in a fallback chain reference different redis resource keys | 1 |
-| `WARN [missing-resource-env-var] ...` | A resource's `urlEnvKey` is unset at config time (boot may still succeed if env is set at runtime) | 0 (1 with `--strict`) |
-| `FAILED — N error(s)` | Run had at least one error finding | 1 |
-| `OK — 0 error(s), N warning(s)` | No errors; warnings tolerated | 0 |
-
----
-
-## Public exports
-
-Re-exported from `@luckystack/devkit`:
-
-```typescript
-export { validateDeploy } from './validateDeploy';
-export type {
-  ValidateDeployInput,
-  ValidateDeployResult,
-  ValidationFinding,
-  ValidationSeverity,
-} from './validateDeploy';
-```
-
-Core registry probes used by the CLI live in `@luckystack/core`:
-
-- `getServicesConfig()` / `isServicesConfigRegistered()`
-- `getDeployConfig()` / `isDeployConfigRegistered()`
-
-These are not re-exported by devkit; consumers calling `validateDeploy` from build scripts should import them directly from core.
+Registration modules are loaded for their side effects, so their paths must point at the intended compiled environment. Treat warnings as failures in stricter deployment pipelines when a warning might hide a topology error. Do not treat a successful static validation as a replacement for runtime health checks or Redis boot-handshake verification.

package/docs/hot-reload.md

@@ -1,365 +1,7 @@
-# Hot Reload (`setupWatchers`, template injection, dependency graph)
+# Hot reload design
 
-> Dev-only. `setupWatchers()` is a no-op when `process.env.NODE_ENV === 'production'`. Production servers read the generated runtime maps on disk and never run chokidar.
+Development route loading serves requests from in-memory registries; regenerating editor-facing type artifacts should not block the Socket.io request path. File-event bursts are coalesced, and a generation already in progress gets a follow-up pass instead of competing builds. Deferring heavy work lets the server listen before the TypeScript Program is built. Consult the watcher source for event classification and timing rather than maintaining a second event-flow implementation here.
 
-`setupWatchers()` is the single dev-time entry point that turns the project source tree into a live, hot-reloadable route registry. It boots one chokidar watcher for the source tree, one watcher per configured `serverFunctionDirs` root (legacy singular `serverFunctionsDir` still honored when set), and one for `sharedDir`. It coalesces file events into a few coarse buckets, and schedules background type-map regeneration without blocking the Socket.io thread.
+When a shared dependency changes, reload only affected routes rather than every route, but invalidate type caches so subsequent requests use fresh source. Generated outputs must not trigger their own watcher loops. Empty route files can receive starter templates; paired sync files should remain type-consistent. Preserve the distinction between runtime reload and generated developer artifacts: a generation failure can leave IDE hints stale without justifying a production-path dependency on devkit.
 
-It must be called AFTER `initializeAll()` so the initial `devApis`/`devSyncs`/`devFunctions` maps are populated before the first hot-reload event has a chance to mutate them.
-
----
-
-## Marker + path segments
-
-Resolved once per startup so consumers with custom paths or marker names work without forking:
-
-```typescript
-const apiMarkerSlash = `/${getRoutingRules().apiMarker}/`;
-const syncMarkerSlash = `/${getRoutingRules().syncMarker}/`;
-const apiMarkerNoLead = `${getRoutingRules().apiMarker}/`;
-const syncMarkerNoLead = `${getRoutingRules().syncMarker}/`;
-
-const pathsCfg = getProjectConfig().paths;
-const srcSegment = `/${pathsCfg.srcDir.replaceAll('\\', '/')}/`;
-const sharedSegment = `/${pathsCfg.sharedDir.replaceAll('\\', '/')}/`;
-// One segment per configured root in `pathsCfg.serverFunctionDirs` (the legacy
-// singular `pathsCfg.serverFunctionsDir` is folded into the array at config load):
-const serverFunctionsSegments = pathsCfg.serverFunctionDirs.map(
-  (dir) => `/${dir.replaceAll('\\', '/')}/`,
-);
-const localesSegment = `${srcSegment}_locales/`;
-```
-
-The `*NoLead` variants exist because some event paths arrive without a leading slash (e.g. from chokidar add events) and the `*Slash` variants are used for `.includes()` middle-of-path matches.
-
----
-
-## Coalescing state
-
-Three buckets of state, all module-local to the closure created by `setupWatchers`:
-
-```typescript
-const reloadTimers = new Map<'api' | 'sync' | 'functions' | 'typemap' | 'locales', NodeJS.Timeout>();
-const pendingApiUpserts = new Set<string>();
-const pendingApiDeletes = new Set<string>();
-const pendingSyncUpserts = new Set<string>();
-const pendingSyncDeletes = new Set<string>();
-```
-
-`reloadTimers` is keyed by reload kind. `scheduleReload(key, task, delay = getProjectConfig().dev.hotReloadDebounceMs)` clears any pending timer for that key and queues a new one. This means a flurry of saves coalesces to a single run; the timer's `task` reads the current pending sets and processes them atomically:
-
-```typescript
-const scheduleReload = (
-  key: 'api' | 'sync' | 'functions' | 'typemap' | 'locales',
-  task: () => Promise<void> | void,
-  delay = getProjectConfig().dev.hotReloadDebounceMs
-) => {
-  const activeTimer = reloadTimers.get(key);
-  if (activeTimer) clearTimeout(activeTimer);
-
-  const timer = setTimeout(() => {
-    reloadTimers.delete(key);
-    void task();
-  }, delay);
-
-  reloadTimers.set(key, timer);
-};
-```
-
-The same path is allowed to appear in both an upsert set and a delete set across consecutive events (rename, delete-then-write); the processing functions drain each set and the loader's `upsert*FromFile` / `remove*FromFile` are idempotent.
-
----
-
-## Type-map regeneration queue
-
-```typescript
-const typeMapQueue = { pending: false, running: false };
-
-const runTypeMapRegeneration = () => {
-  typeMapQueue.running = true;
-  typeMapQueue.pending = false;
-  const startedAt = Date.now();
-  setImmediate(() => {
-    void (async () => {
-      const [err] = await tryCatch(() => { generateTypeMapFile({ quiet: true }); });
-      if (err) {
-        console.log(`[HotReload] type map regeneration failed: ${String(err)}`, 'red');
-      } else {
-        console.log(`[HotReload] type map ready in ${Date.now() - startedAt}ms`, 'green');
-      }
-      typeMapQueue.running = false;
-      if (typeMapQueue.pending) {
-        runTypeMapRegeneration();
-      }
-    })();
-  });
-};
-
-const requestTypeMapRegeneration = () => {
-  if (typeMapQueue.running) {
-    typeMapQueue.pending = true;
-    return;
-  }
-  runTypeMapRegeneration();
-};
-```
-
-Two invariants:
-
-1. **Type-map regeneration is a DX artifact.** The runtime request path reads from in-memory `devApis`/`devSyncs`/`devFunctions`, so regeneration is purely for IDE IntelliSense + the Zod schemas on disk. There is no reason to await it on the reload critical path.
-2. **Single-flight with one queued follow-up.** If a regeneration is already running, the next request flips `pending = true` and returns. When the running pass finishes it consults `pending` and re-runs. This collapses any number of saves during a long pass into exactly one follow-up.
-
-`setImmediate` is critical: it yields to the event loop so the Socket.io accept path keeps serving during a burst of saves. Without it, a single `generateTypeMapFile()` could hold the thread for hundreds of milliseconds during heavy type expansion. The same pattern is used for the initial type-map generation on boot (see "Boot-time behavior" below).
-
-`quiet: true` silences the per-API/per-sync logs from the emitter during hot reload — only the final "type map ready in Xms" line prints. The first run on boot also runs quiet to keep startup output readable.
-
----
-
-## File-kind classifiers
-
-```typescript
-const isGeneratedPath = (n: string): boolean =>
-  n.includes('apiTypes.generated.ts') || n.includes('apiDocs.generated.json');
-
-const isRouteDependencyFile = (n: string): boolean => {
-  // .ts / .tsx, inside srcDir, NOT inside an _api or _sync folder, NOT a generated artifact
-};
-
-const isSharedDependencyFile = (n: string): boolean => {
-  // .ts / .tsx inside sharedDir OR any configured serverFunctionDirs root
-  // (legacy singular serverFunctionsDir still honored when set)
-};
-
-const isTypeMapRelevantFile = (n: string): boolean => {
-  // .ts / .tsx, in srcDir / sharedDir / or root config.ts, NOT generated, NOT _api/_sync
-};
-
-const isLocaleFile = (n: string): boolean =>
-  n.includes(localesSegment) && n.endsWith('.json');
-```
-
-These predicates classify each event into one of the buckets handled by the event handlers. Order matters in the handlers: route files go through the API/Sync path; shared/route-dependency files trigger a fan-out through the import dependency graph; locales trigger a translator reload; generated files are dropped entirely (otherwise the type-map regeneration would feed itself).
-
----
-
-## Event handlers
-
-Three chokidar watchers all route into a small set of handlers:
-
-```typescript
-watch(pathsConfig.srcDir, { ignoreInitial: true, awaitWriteFinish: { ... } })
-  .on('add', handleAdd)
-  .on('change', handleChange)
-  .on('unlink', handleDelete);
-
-// One watcher per configured root in `pathsConfig.serverFunctionDirs`
-// (legacy singular `pathsConfig.serverFunctionsDir` is folded into the array at config load):
-for (const serverFunctionsDir of pathsConfig.serverFunctionDirs) {
-  watch(serverFunctionsDir, { ignoreInitial: true })
-    .on('add', handleFunctionChange)
-    .on('change', handleFunctionChange)
-    .on('unlink', handleFunctionChange);
-}
-
-watch(pathsConfig.sharedDir, { ignoreInitial: true })
-  .on('add', handleFunctionChange)
-  .on('change', handleFunctionChange)
-  .on('unlink', handleFunctionChange);
-```
-
-`awaitWriteFinish` is tuned via `projectConfig.dev`:
-
-```typescript
-awaitWriteFinish: {
-  stabilityThreshold: devConfig.watcherStabilityThresholdMs,
-  pollInterval: devConfig.watcherPollIntervalMs,
-}
-```
-
-This is what stops chokidar from firing on a partially-written file (e.g. a save-in-progress from VSCode).
-
-### `handleAdd(path)`
-
-1. Normalize the path.
-2. `invalidateGraphForFile(normalizedPath)` — drop any stale dependency-graph nodes pointing at the old version of this file (see `importDependencyGraph.ts`).
-3. Route filename validation via `getRouteFilenameValidationMessage`. If the filename is invalid AND `shouldInjectTemplate(path)` says it's an empty file, try `injectTemplate(path)` — this is how `touch _api/foo.ts` ends up with starter content. If a template was injected, return (the change event from writing the template will flow back through).
-4. Empty-file template injection for a valid-named file:
-   - Sync server file with an existing client: extract the `clientInput` type from the client file, inject the paired server template with that type pre-filled, schedule type-map regeneration in the background, update the client to import the type, then upsert both files.
-   - Otherwise inject the standalone template.
-5. If the path is inside the API marker folder: add to `pendingApiUpserts`, schedule the `api` reload. The schedule's task calls `processPendingApiChanges({ regenerateTypeMap: true })` — `true` because an add changes the route set, not just one route's types.
-6. If inside the sync marker folder: mirror the same with `pendingSyncUpserts`.
-7. Otherwise delegate to `handleChange(path)` so dependency-graph / type-map relevance logic runs for the new file.
-
-### `handleChange(path)`
-
-The hot path for "I just saved this file". Sequence after `invalidateGraphForFile`:
-
-1. If the filename is route-shaped but invalid, log and bail (after attempting template injection if the file is empty).
-2. If `shouldInjectTemplate(path)` (the file became empty) — inject and return.
-3. Drop generated paths.
-4. Locale `.json` — schedule the `locales` task which calls `await getLocaleReloader()?.()` (the function `@luckystack/core`'s i18n module registers).
-5. **Route dependency file (a `.ts`/`.tsx` inside `srcDir` that is NOT an API or sync):**
-   - Schedule a `typemap` task that requests background regeneration.
-   - Call `enqueueAffectedRoutesFromDependency(normalizedPath)` to fan out reloads through the import dependency graph (next section).
-6. **Type-map-relevant file** that wasn't already a route dependency (e.g. `config.ts`, shared lib files): schedule a `typemap` regeneration only.
-7. API/sync file change: schedule both `typemap` regeneration AND a reload pass that processes the upsert/delete sets.
-
-### `handleDelete(path)`
-
-Same skeleton as `handleChange`. The two notable extras:
-
-- Generated paths and locale deletes are handled the same way as in `handleChange`.
-- Sync server file deletion: the watcher reads the just-deleted server file's `clientInput` type FROM THE GENERATED TYPE MAP (the server file is already gone on disk) via `extractClientInputFromGeneratedTypes(pagePath, syncName)`, then rewrites the client file via `updateClientFileForDeletedServer(clientPath, clientInputTypes)`. If extraction fails, a fallback string is written with a TODO comment. This is the only place the watcher reaches into the generated type-map to read a type.
-
-### `handleFunctionChange(changedPath)`
-
-Triggered by both the server-functions watcher and the shared watcher.
-
-- Invalidate the dependency graph for the changed file.
-- Schedule the `functions` reload: re-run `initializeFunctions()` AND request a type-map regeneration (server functions are part of the generated `Functions` interface).
-- If the file is a shared-dependency file, ALSO call `enqueueAffectedRoutesFromDependency` so routes that import from `<sharedDir>` or any configured `<serverFunctionDirs>` root (legacy singular `<serverFunctionsDir>` still honored when set) reload.
-
----
-
-## Dependency graph fan-out
-
-Defined in `importDependencyGraph.ts`. Two functions:
-
-```typescript
-findDependentRouteFiles(changedPath: string): Set<string>
-invalidateGraphForFile(changedPath: string): void
-```
-
-`findDependentRouteFiles` returns every `_api/`/`_sync/` route file that (transitively) imports `changedPath`. `enqueueAffectedRoutesFromDependency` walks the result and routes each entry into the right pending set:
-
-```typescript
-for (const routePath of affectedRoutes) {
-  if (routePath.includes(apiMarkerSlash)) {
-    pendingApiDeletes.delete(routePath);
-    pendingApiUpserts.add(routePath);
-    queuedApiCount += 1;
-  } else if (routePath.includes(syncMarkerSlash)) {
-    pendingSyncDeletes.delete(routePath);
-    pendingSyncUpserts.add(routePath);
-    queuedSyncCount += 1;
-  }
-}
-```
-
-With dynamic `import()` + per-load `?v=` cachebust in the loader, there is nothing to invalidate on the main thread; the next upsert fetches a fresh module instance, and the import dependency graph itself is invalidated synchronously by `invalidateGraphForFile`.
-
-If no routes depend on the changed file, the function logs in yellow and returns without scheduling work — saving an unrelated `_components/Foo.tsx` doesn't fan out to every route.
-
----
-
-## Pending change processors
-
-```typescript
-const processPendingApiChanges = async ({ regenerateTypeMap = false }: { regenerateTypeMap?: boolean } = {}) => {
-  const deletePaths = [...pendingApiDeletes];
-  const upsertPaths = [...pendingApiUpserts];
-  pendingApiDeletes.clear();
-  pendingApiUpserts.clear();
-
-  if (regenerateTypeMap) {
-    requestTypeMapRegeneration();
-  }
-
-  for (const deletePath of deletePaths) {
-    removeApiFromFile(deletePath);
-    console.log(`[HotReload] API removed: ${deletePath}`, 'yellow');
-  }
-
-  for (const upsertPath of upsertPaths) {
-    await upsertApiFromFile(upsertPath);
-    console.log(`[HotReload] API reloaded: ${upsertPath}`, 'green');
-  }
-};
-```
-
-The sync variant mirrors this and adds the sync-server-delete-with-living-client repair step (see `handleDelete`). Both processors:
-
-1. Snapshot the pending sets.
-2. Clear the sets so concurrent file events can populate them again.
-3. Optionally request a background type-map regeneration.
-4. Run deletes before upserts so a delete followed by an immediate re-add resolves correctly.
-5. Use the loader's `upsertApiFromFile` / `removeApiFromFile` (and `upsertSyncFromFile` / `removeSyncFromFile`), each of which invalidates the TS program cache and the runtime type resolver cache. See `loader-pipeline.md`.
-
----
-
-## Template injection
-
-Helpers from `templateInjector.ts` and `templates/*.ts`:
-
-| Helper | What |
-|---|---|
-| `shouldInjectTemplate(path)` | File exists, is `.ts`, and is empty (`isEmptyFile`) AND is API- or sync-shaped. |
-| `injectTemplate(path)` | Writes the right template based on the filename: API, sync server, or sync client. Returns `true` if injected. |
-| `isSyncServerFile(normalizedPath)` | Filename matches `_server_v<n>.ts`. |
-| `getPairedSyncFile(normalizedPath)` | Returns the sibling `_client_v<n>.ts` (or `_server_v<n>.ts`) path. |
-| `getRouteFilenameValidationMessage(normalizedPath)` | Returns a human-readable error string if the filename is route-shaped but invalid; `null` otherwise. |
-| `extractClientInputFromFile(clientPath)` | Reads the client file with the TS Program and returns the `data` type literal text. |
-| `extractClientInputFromGeneratedTypes(pagePath, syncName)` | Reads `apiTypes.generated.ts` and returns the `clientInput` member for the sync. Used when the server file has just been deleted. |
-| `extractSyncPagePath(path)` / `extractSyncName(path)` | Filename -> generated-types lookup keys. |
-| `injectServerTemplateWithClientInput(serverPath, clientInput)` | Writes the sync server template with the `data` type pre-filled. |
-| `updateClientFileForPairedServer(clientPath)` | Rewrites the client to import `clientInput` / `serverOutput` from the generated types file. |
-| `updateClientFileForDeletedServer(clientPath, clientInput)` | Rewrites the client to redeclare `clientInput` inline (since the server is gone). |
-| `isEmptyFile(filePath)` | True if file size is 0 or content is whitespace-only. |
-
-The pairing flow (sync server added with an existing client) is the most interesting case — without it, the writer would have to manually copy the `data` type into both files. With it, the AI / IDE sees consistent types across server + client immediately after `touch foo_server_v1.ts`.
-
----
-
-## Locale reload integration
-
-```typescript
-if (isLocaleFile(normalizedPath)) {
-  scheduleReload('locales', async () => {
-    await getLocaleReloader()?.();
-  });
-  return;
-}
-```
-
-`getLocaleReloader()` returns the function `@luckystack/core` registered via `registerLocaleReloader(...)` during boot. The locale module owns its own cache; devkit just signals "your files changed, reload yourself".
-
-If no locale reloader is registered, the optional chain is a no-op and the save is silently dropped.
-
----
-
-## Boot-time behavior
-
-```typescript
-setImmediate(() => {
-  void (async () => {
-    const [err] = await tryCatch(() => { generateTypeMapFile({ quiet: true }); });
-    if (err) {
-      console.log(`[HotReload] initial type map generation failed: ${String(err)}`, 'red');
-    } else {
-      console.log(`[HotReload] type map ready in background`, 'green');
-    }
-  })();
-});
-```
-
-At the bottom of `setupWatchers()`. Generates the initial type map on the next event-loop tick so:
-
-1. `server.listen()` happens before the heavy TypeScript Program build.
-2. The runtime reads from the in-memory `devApis`/`devSyncs` maps (already populated by `initializeAll()` before `setupWatchers` runs); the on-disk type map is purely for IDE IntelliSense + Zod schema files.
-3. Deferring drops boot time ~6–8 seconds on a 54-API project.
-
-The same `setImmediate` + `quiet` + tryCatch pattern is reused by `runTypeMapRegeneration` for every subsequent run.
-
----
-
-## Failure modes
-
-| Symptom | Cause | What happens |
-|---|---|---|
-| `[HotReload] type map regeneration failed: ...` | `generateTypeMapFile()` threw (unresolved symbols, missing `tsconfig.server.json`, etc.) | Logged in red, server keeps running, runtime maps unchanged |
-| `[HotReload] <route validation message>` | Filename is route-shaped but invalid (no `_v<n>`, etc.) | File not loaded; route key absent |
-| `[HotReload] No API/Sync routes depend on: ...` | A shared/dep file changed but no route imports it | Type-map regeneration still scheduled; no upserts |
-| Server file deletion without existing client | `getPairedSyncFile` returns null or client doesn't exist | Sync entry removed, no client repair attempted |
-| Two saves in <`hotReloadDebounceMs`> ms | `scheduleReload` coalesces | One run reads the final pending sets |
-| Save during regeneration | `requestTypeMapRegeneration` flips `pending = true` | One follow-up run after the current one finishes |
-| Empty file written by `touch` | `shouldInjectTemplate` returns true | Template is injected; the resulting change event flows through normally |
-| Locale `.json` typo | `getLocaleReloader()` errors | No special handling; error surfaces from the registered reloader |
+Production does not start these watchers. If the live registry appears stale, inspect watcher errors and route naming before relying on regenerated files as proof the running handler was replaced.