@zerotal/core 1.4.0 → 1.5.0

package/src/lock/errors.ts

@@ -18,3 +18,29 @@ export class LockNotAcquiredError extends ZerotalError {
     this.key = key;
   }
 }
+
+/**
+ * Thrown when a lock that was being auto-refreshed could not be extended —
+ * the TTL lapsed and another holder took the key.
+ *
+ * Distinct from {@link LockNotAcquiredError} on purpose: that one means "you
+ * never got in", this one means "you were in and you are not any more", and the
+ * work in flight has to be treated as no longer exclusive. The callback's
+ * `AbortSignal` is aborted before this is thrown, so cooperative work stops
+ * rather than running on outside the lock it thinks it holds.
+ *
+ * @category Acquiring
+ */
+export class LockLostError extends ZerotalError {
+  /** The lock key that was lost. */
+  readonly key: string;
+
+  constructor(key: string) {
+    super(
+      `[Zerotal Lock] Lost the lock for key: "${key}" — it expired and was taken by another holder.`,
+      "E_LOCK_LOST",
+      409,
+    );
+    this.key = key;
+  }
+}

package/src/lock/facades/Lock.ts

@@ -1,7 +1,13 @@
 import { currentApp } from "../../application/currentApp.ts";
 import { ZerotalError } from "../../errors/index.ts";
-import type { LockManager, ManagedLock, BlockOptions } from "../LockManager.ts";
-import { LockNotAcquiredError } from "../errors.ts";
+import type {
+  LockManager,
+  ManagedLock,
+  BlockOptions,
+  TryOptions,
+  LockedCallback,
+} from "../LockManager.ts";
+import { LockNotAcquiredError, LockLostError } from "../errors.ts";
 
 /**
  * Resolve the live LockManager from the application container on every call.
@@ -75,12 +81,20 @@ export class Lock {
    * @param key - Logical lock name.
    * @param ttlSeconds - Lock time-to-live in seconds.
    * @param callback - Critical section to run while the lock is held.
+   * @param options - Pass `{ refresh: true }` to hold the lock across work
+   *   longer than its TTL.
    * @returns The value returned by `callback`.
    * @throws {LockNotAcquiredError} Immediately, if the lock is busy.
+   * @throws {LockLostError} If refreshing was on and the lock was lost mid-run.
    * @category Acquiring
    */
-  static async try<T>(key: string, ttlSeconds: number, callback: () => Promise<T> | T): Promise<T> {
-    return _manager().try(key, ttlSeconds, callback);
+  static async try<T>(
+    key: string,
+    ttlSeconds: number,
+    callback: LockedCallback<T>,
+    options?: TryOptions,
+  ): Promise<T> {
+    return _manager().try(key, ttlSeconds, callback, options);
   }
 
   /**
@@ -98,7 +112,7 @@ export class Lock {
   static async block<T>(
     key: string,
     ttlSeconds: number,
-    callback: () => Promise<T> | T,
+    callback: LockedCallback<T>,
     options?: BlockOptions,
   ): Promise<T> {
     return _manager().block(key, ttlSeconds, callback, options);
@@ -111,4 +125,15 @@ export class Lock {
    * @category Acquiring
    */
   static readonly NotAcquired = LockNotAcquiredError;
+
+  /**
+   * The {@link LockLostError} class, for `err instanceof Lock.Lost`.
+   *
+   * Worth catching separately from {@link Lock.NotAcquired}: that one means the
+   * work never started, this one means it started and must not be trusted to
+   * have finished exclusively.
+   *
+   * @category Acquiring
+   */
+  static readonly Lost = LockLostError;
 }

package/src/lock/index.ts

@@ -38,13 +38,13 @@
  */
 
 export { LockManager, ManagedLock } from "./LockManager.ts";
-export type { BlockOptions } from "./LockManager.ts";
+export type { BlockOptions, TryOptions, RefreshOptions, LockedCallback } from "./LockManager.ts";
 
 export { Lock } from "./facades/Lock.ts";
 export { LockProvider } from "../provider/LockProvider.ts";
 export { LockConfig } from "./config.ts";
 export type { LockConfigShape } from "./config.ts";
-export { LockNotAcquiredError } from "./errors.ts";
+export { LockNotAcquiredError, LockLostError } from "./errors.ts";
 
 // Drivers — exported for custom driver registration and direct instantiation
 export type { LockDriver } from "./drivers/LockDriver.ts";

package/src/macros/config.macro.ts

@@ -42,6 +42,8 @@ export function loadConfigsSync(configDir: string): Record<string, Record<string
   for (const file of glob.scanSync({ cwd: configDir })) {
     if (file === "index.ts") continue;
     const key = file.replace(/\.ts$/, "");
+    // Bun macros execute at bundle time, where module loading is synchronous by design.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const loadedModule = require(join(configDir, file)) as Record<string, unknown>;
     result[key] = (loadedModule["default"] ?? loadedModule) as Record<string, unknown>;
   }

package/src/provider/ServiceProvider.ts

@@ -5,6 +5,8 @@
 import type { Application } from "../application/Application.ts";
 import type { ContainerBindings } from "../container/types.ts";
 import type { HttpContext } from "../pipeline/HttpContext.ts";
+import type { DevProcessDefinition } from "../dev/DevProcess.ts";
+import type { DoctorCheck } from "../doctor/AppDoctor.ts";
 
 /** The runtime modes a provider can declare it participates in. */
 export type AppEnvironment = "web" | "console" | "worker" | "test" | "repl";
@@ -81,4 +83,42 @@ export abstract class ServiceProvider {
   replContext(): Record<string, unknown> {
     return {};
   }
+
+  /**
+   * Long-running processes to run beside the server under `bun zt dev`.
+   *
+   * A package that ships a companion process — a queue worker, a listener, a
+   * watcher — declares it here and it appears as its own tab in the deck,
+   * individually restartable, without the developer running a second terminal.
+   *
+   * Called once on a booted app, so it may read config.
+   *
+   * @example
+   * override devProcesses() {
+   *   return [{ name: "queue", command: "queue:work", enabled: () => this._hasQueue() }];
+   * }
+   */
+  devProcesses(): DevProcessDefinition[] {
+    return [];
+  }
+
+  /**
+   * Checks this package contributes to `bun zt doctor`.
+   *
+   * The declarative counterpart to `app.registerDoctorCheck()`: same checks,
+   * same report, but asked of the provider rather than pushed from inside
+   * `onRegister()`. Prefer this — it keeps a package's checks next to its other
+   * contributions and readable without tracing a registration call.
+   *
+   * Keep findings machine-readable. `zt doctor` is what an agent runs as the
+   * last step of a task, and "looks fine to me" is not a result it can act on.
+   *
+   * @example
+   * override doctorChecks() {
+   *   return [{ id: "queue-driver", label: "Queue", run: () => ({ status: "ok", message: "sqlite" }) }];
+   * }
+   */
+  doctorChecks(): DoctorCheck[] {
+    return [];
+  }
 }

package/src/router/Router.ts

@@ -15,6 +15,13 @@ import type {
   ModelBindingResolver,
   ViewLayout,
 } from "./Route.ts";
+import type {
+  RouteArgs,
+  RouteParamValue,
+  RouteParamValues,
+  RouteQuery,
+  RouteTarget,
+} from "./registry.ts";
 import type { HttpContext } from "../pipeline/HttpContext.ts";
 import type { ExceptionHandler } from "../application/ExceptionHandler.ts";
 import { createRouteHandler } from "./RouteHandler.ts";
@@ -36,7 +43,8 @@ import {
  * The `Route` export from '@zerotal/core' is typed as `typeof Router & RouterMacros`
  * so every declared macro is callable as a static method.
  */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- intentional augmentation target: external packages merge macros in via `declare module`.
+// Intentionally empty: it is an augmentation target, and external packages merge
+// their macros in via `declare module`.
 export interface RouterMacros {}
 
 // ── Handler wrappers ──────────────────────────────────────────────────────────
@@ -271,26 +279,99 @@ export interface ViewRegistration {
   withLayout(layout: ViewLayout): ViewRegistration;
 }
 
+/** Encode one catch-all value: `'guides/intro'` and `['guides','intro']` both give `guides/intro`. */
+function _encodeWildcard(value: RouteParamValue | readonly RouteParamValue[]): string {
+  const segments = Array.isArray(value) ? value : String(value).split("/");
+  return (segments as readonly RouteParamValue[])
+    .map((segment) => encodeURIComponent(String(segment)))
+    .filter((segment) => segment.length > 0)
+    .join("/");
+}
+
+/** Serialise the query bag: `null`/`undefined` drop out, arrays repeat the key. */
+function _encodeQuery(query: RouteQuery): string {
+  const pairs: string[] = [];
+  for (const [key, value] of Object.entries(query)) {
+    if (value === null || value === undefined) continue;
+    const values = Array.isArray(value) ? value : [value];
+    for (const entry of values as readonly (string | number | boolean)[]) {
+      pairs.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(entry))}`);
+    }
+  }
+  return pairs.join("&");
+}
+
+/** The {@link route} helper: a checked call signature plus its `dynamic` escape hatch. */
+export interface RouteBuilder {
+  /**
+   * Generate a URL for a named route, substituting `:param` segments.
+   *
+   * @param name - The registered route name, e.g. `'posts.show'`.
+   * @param args - `params` (one value per `:param`; a catch-all takes the `"*"` key and accepts an array of segments) then optional `query` values.
+   * @throws {Error} when the route name is unknown, a required `:param` is missing, or a param key matches no segment.
+   */
+  <N extends RouteTarget>(name: N, ...args: RouteArgs<N>): string;
+
+  /**
+   * Build a URL for a route name that isn't known at compile time — a name from
+   * config, a database row, or a package that registers routes conditionally.
+   *
+   * The escape hatch is a separate function rather than an overload on purpose:
+   * an overload taking `string` is matched by every string, which would let
+   * every typo through the front door. This one is greppable, and reads as the
+   * exception it is.
+   *
+   * @param name - The route name, resolved at runtime.
+   * @param params - One value per `:param` in the pattern.
+   * @param query - Optional query-string values.
+   * @throws {Error} on the same conditions as {@link route} — an unknown name still throws.
+   *
+   * @example
+   * route.dynamic(config('app.home_route'), { id })
+   */
+  dynamic(name: string, params?: RouteParamValues, query?: RouteQuery): string;
+}
+
 /**
- * Generate a URL for a named route, substituting :param segments.
- * Extra params that don't match a :segment become query-string entries.
+ * Generate a URL for a named route, substituting `:param` segments.
+ *
+ * Params are **exact**: a key the pattern has no segment for is a mistake, not a
+ * query-string entry, so query values go in the third argument. That is what
+ * makes the types worth having — a typo'd param name that silently became
+ * `?slugg=hello` is precisely the bug this signature exists to catch.
  *
- * @throws {Error} when the route name is unknown or a required `:param` is missing.
+ * Once `types/routes.generated.ts` exists (`bun zt route:types`) the name and
+ * its params are checked at compile time: `route('nope')` and
+ * `route('posts.show', {})` are both errors, and the second one names the
+ * `slug` it wants. Until then every name is accepted and nothing is checked.
+ * For a name that is only known at runtime, use `route.dynamic`.
  *
  * @example
- * route('posts.show', { slug: 'hello' })          // '/posts/hello'
- * route('search',     { q: 'reno', page: 2 })     // '/search?q=reno&page=2'
+ * route('posts.show', { slug: 'hello' })              // '/posts/hello'
+ * route('search', {}, { q: 'reno', page: 2 })         // '/search?q=reno&page=2'
+ * route('docs.show', { '*': 'guides/intro' })         // '/docs/guides/intro'
  *
  * @category Naming & URLs
  */
-export function route(name: string, params: Record<string, string | number> = {}): string {
+export const route: RouteBuilder = Object.assign(
+  <N extends RouteTarget>(name: N, ...args: RouteArgs<N>): string => {
+    const [params = {}, query = {}] = args as [RouteParamValues?, RouteQuery?];
+    return _buildRoute(name, params, query);
+  },
+  {
+    dynamic: (name: string, params: RouteParamValues = {}, query: RouteQuery = {}): string =>
+      _buildRoute(name, params, query),
+  },
+);
+
+function _buildRoute(name: string, params: RouteParamValues, query: RouteQuery): string {
   const pattern = _s().namedRoutes.get(name);
   if (pattern === undefined) {
     throw new Error(`[Zerotal] Named route not found: "${name}"`);
   }
 
   const usedKeys = new Set<string>();
-  const url = pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, key: string) => {
+  let url = pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, key: string) => {
     const value = params[key];
     if (value === undefined) {
       throw new Error(`[Zerotal] Missing parameter "${key}" for route "${name}"`);
@@ -300,11 +381,28 @@ export function route(name: string, params: Record<string, string | number> = {}
     return encodeURIComponent(String(value));
   });
 
-  const queryParams = Object.entries(params)
-    .filter(([key]) => !usedKeys.has(key))
-    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+  // A catch-all segment reaches the router as `*` — the `[...slug]` name is gone
+  // by then — so the wildcard is its own param key.
+  if (url.includes("*")) {
+    const value = params["*"];
+    if (value === undefined) {
+      throw new Error(`[Zerotal] Missing catch-all parameter "*" for route "${name}"`);
+    }
+    usedKeys.add("*");
+    url = url.replace("*", _encodeWildcard(value));
+  }
+
+  const unknown = Object.keys(params).filter((key) => !usedKeys.has(key));
+  if (unknown.length > 0) {
+    throw new Error(
+      `[Zerotal] Unknown parameter${unknown.length > 1 ? "s" : ""} ` +
+        `${unknown.map((key) => `"${key}"`).join(", ")} for route "${name}" (${pattern}). ` +
+        `Query-string values go in the third argument: route(name, params, query).`,
+    );
+  }
 
-  return queryParams.length > 0 ? `${url}?${queryParams.join("&")}` : url;
+  const search = _encodeQuery(query);
+  return search ? `${url}?${search}` : url;
 }
 
 /**
@@ -1101,7 +1199,7 @@ export class Router {
    *
    * Lets framework packages re-run a route's middleware outside the normal
    * HTTP pipeline — e.g. @zerotal/flow re-applies the original page route's
-   * middleware on every WebSocket update (Livewire-style persistent middleware).
+   * middleware on every WebSocket update (persistent middleware).
    *
    * @example
    * const middleware = Router.middlewareFor('GET', '/dashboard');

package/src/router/registry.ts

@@ -0,0 +1,123 @@
+/**
+ * The typed route registry and the param types derived from it. `RouteRegistry`
+ * is the routing analogue of `ConfigRegistry`: an empty interface filled by
+ * declaration merging, so `route("posts.show", { slug })` is checked against the
+ * routes the application actually registered.
+ *
+ * Nothing here is hand-written by an app. `bun zt route:types` boots the app,
+ * reads `Router.namedRoutes`, and writes `types/routes.generated.ts`:
+ *
+ * ```ts
+ * export const ROUTES = {
+ *   "home":       "/",
+ *   "posts.show": "/posts/:slug",
+ * } as const;
+ *
+ * declare module "@zerotal/core" {
+ *   interface RouteRegistry extends Routes {}
+ * }
+ * ```
+ *
+ * Params are *derived* from the pattern rather than generated, so adding a
+ * segment to a route changes one string in that file and every call site
+ * updates with it.
+ */
+
+/** A value that can be substituted into a `:param` segment. */
+export type RouteParamValue = string | number;
+
+/** The loose param bag accepted by the untyped `route()` overload. */
+export type RouteParamValues = Record<string, RouteParamValue | readonly RouteParamValue[]>;
+
+/**
+ * Query-string values accepted as `route()`'s third argument. `null` and
+ * `undefined` entries are dropped; an array repeats the key
+ * (`{ tag: ['a','b'] }` → `?tag=a&tag=b`).
+ */
+export type RouteQuery = Record<
+  string,
+  string | number | boolean | null | undefined | readonly (string | number | boolean)[]
+>;
+
+/**
+ * Maps each registered route name to its URL pattern. Augmented by the
+ * generated `types/routes.generated.ts`; empty until that file exists, which is
+ * why `route()` keeps an untyped overload — an app that never runs the
+ * generator (or registers routes behind a config flag) still compiles.
+ *
+ * @category Extension registries
+ */
+export interface RouteRegistry {}
+
+/** Flatten an intersection so editors show `{ slug: string | number }`, not `A & B`. */
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Every route name known to the augmented {@link RouteRegistry}. */
+export type RouteName = Extract<keyof RouteRegistry, string>;
+
+/**
+ * What `route()` accepts as a name: the registered names once the registry is
+ * augmented, any string before that.
+ *
+ * There is deliberately **no** `route(name: string)` overload alongside the
+ * typed one. An overload that accepts every string is matched by every string,
+ * so `route("nope")` would compile and the types would be decorative — the
+ * failure mode this whole feature exists to remove. A name that genuinely is
+ * not known until runtime goes through `route.dynamic()`, which says so at the
+ * call site.
+ */
+export type RouteTarget = [RouteName] extends [never] ? string : RouteName;
+
+/** The URL pattern registered for route `N`, or plain `string` when it isn't a known name. */
+export type RoutePattern<N extends string> = N extends RouteName
+  ? RouteRegistry[N] extends string
+    ? RouteRegistry[N]
+    : string
+  : string;
+
+/**
+ * The params a URL pattern requires, read straight off the pattern string.
+ *
+ * - `/posts/:slug` → `{ slug: string | number }`
+ * - `/a/:x/b/:y` → `{ x: …; y: … }`
+ * - `/docs/*` → `{ "*": … }` — a catch-all (`[...slug]`) compiles to `*` in the
+ *   URL pattern, so the segment name is gone by the time routing sees it. The
+ *   key is the wildcard itself, and it accepts an array of segments.
+ * - `/about` → `{}`
+ */
+export type ParamsOf<P extends string> = P extends `${string}:${infer Name}/${infer Rest}`
+  ? { [K in Name]: RouteParamValue } & ParamsOf<`/${Rest}`>
+  : P extends `${string}:${infer Name}`
+    ? { [K in Name]: RouteParamValue }
+    : P extends `${string}*${string}`
+      ? { "*": RouteParamValue | readonly RouteParamValue[] }
+      : Record<never, never>;
+
+/** The params required by route `N`. */
+export type RouteParams<N extends string> = Prettify<ParamsOf<RoutePattern<N>>>;
+
+/**
+ * The param bag a route helper accepts for `N`: exact once the registry is
+ * generated, loose before that. Used by the helpers that take params without
+ * being able to take `route()`'s rest-tuple — `redirect().to(name, params,
+ * status)` and Flow's `redirectRoute`.
+ */
+export type RouteParamsArg<N extends string> = [RouteName] extends [never]
+  ? RouteParamValues
+  : RouteParams<N>;
+
+/**
+ * `route()`'s arguments after the name: params are required only when the
+ * pattern has a `:param` (or a wildcard), and the query bag is always optional.
+ *
+ * Before the registry is generated there is no pattern to read, so params stay
+ * loose — an app that has never run `zt route:types` compiles exactly as it did
+ * before, it just isn't checked.
+ */
+export type RouteArgs<N extends string> = [RouteName] extends [never]
+  ? [params?: RouteParamValues, query?: RouteQuery]
+  : [keyof RouteParams<N>] extends [never]
+    ? // `Record<string, never>` rather than `{}`: an empty object type accepts
+      // any literal, so a static route would quietly swallow `{ page: 2 }`.
+      [params?: Record<string, never>, query?: RouteQuery]
+    : [params: RouteParams<N>, query?: RouteQuery];

package/src/router/routeTypes.ts

@@ -0,0 +1,132 @@
+/**
+ * Writes `types/routes.generated.ts` — the name → URL pattern map that makes
+ * `route()` type-checked.
+ *
+ * The map is read from a **booted application's** `Router.namedRoutes`, never
+ * from the filesystem. Route names come from three places and only one of them
+ * is a file path: the file-router's naming convention, an explicit
+ * `export const meta = { GET: { name } }`, and programmatic registrations
+ * (`Router.get(path, C, 'name')`, a provider's `Router.group()`, Flow's file
+ * routes). A globber would see the first and miss the other two, and a second
+ * implementation of the naming rules is a second implementation to disagree
+ * with the first. Booting makes the generated file true by construction — it is
+ * the same map `route()` reads at runtime.
+ *
+ * The emitted shape is data, not code:
+ *
+ * ```ts
+ * export const ROUTES = { "posts.show": "/posts/:slug" } as const;
+ * ```
+ *
+ * one line per route, so adding a param changes one string rather than
+ * regenerating a function per route. Params are derived from the pattern by
+ * `ParamsOf` (see `registry.ts`), and the same plain object is importable from
+ * the browser bundle.
+ */
+import { relative } from "node:path";
+
+/** Where the generated map is written, relative to the project root. */
+export const ROUTE_TYPES_FILE = "types/routes.generated.ts";
+
+const HEADER = [
+  "// Auto-generated by @zerotal/core — do not edit manually.",
+  "// Regenerate with: bun zt route:types",
+  "//",
+  "// Every named route and the URL pattern it compiles to. `route()` reads this",
+  "// through declaration merging, so an unknown name or a missing :param is a",
+  "// compile error. Commit this file: editors and CI need it without booting the app.",
+  "",
+];
+
+/**
+ * Render the contents of `types/routes.generated.ts` from a name → pattern map.
+ *
+ * Names are sorted so the file is stable across boots — provider registration
+ * order is not, and an unstable generated file shows up as noise in every diff
+ * and as a false failure in `--check`.
+ *
+ * @param namedRoutes - The router's `namedRoutes` map (name → URL pattern).
+ * @param importSpecifier - Module to augment. Defaults to `@zerotal/core`; apps that import the framework through the `zerotal` meta-package still augment core, since that is where `RouteRegistry` is declared.
+ * @returns The full file contents, ending in a newline.
+ */
+export function generateRouteTypes(
+  namedRoutes: ReadonlyMap<string, string>,
+  importSpecifier = "@zerotal/core",
+): string {
+  const entries = Array.from(namedRoutes.entries()).sort(([a], [b]) => a.localeCompare(b));
+
+  // Quote the key only when it isn't a bare identifier — `home` stays bare and
+  // `posts.show` stays quoted, which is what a formatter would do to this file
+  // anyway. Matching it here keeps `format:check` off a file nobody edits.
+  const lines = entries.map(
+    ([name, pattern]) =>
+      `  ${/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name)}: ` +
+      `${JSON.stringify(pattern)},`,
+  );
+
+  // Empty on one line: an app with no named routes still gets a file a formatter
+  // leaves alone (and a registry that types nothing, so `route()` stays on its
+  // untyped overload).
+  const table =
+    lines.length > 0
+      ? ["export const ROUTES = {", ...lines, "} as const;"]
+      : ["export const ROUTES = {} as const;"];
+
+  return [
+    ...HEADER,
+    ...table,
+    "",
+    "/** The generated route table, as a type. */",
+    "export type Routes = typeof ROUTES;",
+    "",
+    `declare module ${JSON.stringify(importSpecifier)} {`,
+    "  interface RouteRegistry extends Routes {}",
+    "}",
+    // The file is rewritten on every dev boot; without a trailing newline a
+    // formatter in the app would put one back, forever.
+    "",
+  ].join("\n");
+}
+
+/** Outcome of {@link writeRouteTypes}. */
+export interface RouteTypesResult {
+  /** Project-relative path of the generated file. */
+  path: string;
+  /** The contents that should be on disk. */
+  content: string;
+  /** True when the file on disk differed (or was missing) — i.e. the write changed something. */
+  changed: boolean;
+  /** How many named routes were written. */
+  count: number;
+}
+
+/**
+ * Write (or, with `check`, verify) `types/routes.generated.ts` for a booted app.
+ *
+ * @param namedRoutes - The router's `namedRoutes` map.
+ * @param options - `cwd` (project root, default `process.cwd()`) and `check` (compare only, never write).
+ * @returns Whether the on-disk file was stale, plus the contents it should have.
+ */
+export async function writeRouteTypes(
+  namedRoutes: ReadonlyMap<string, string>,
+  options: { cwd?: string; check?: boolean } = {},
+): Promise<RouteTypesResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const content = generateRouteTypes(namedRoutes);
+  const target = `${cwd}/${ROUTE_TYPES_FILE}`;
+
+  const file = Bun.file(target);
+  const existing = (await file.exists()) ? await file.text() : null;
+  const changed = existing !== content;
+
+  if (changed && options.check !== true) {
+    await Bun.write(target, content);
+  }
+
+  return {
+    path: relative(cwd, target).replace(/\\/g, "/"),
+    content,
+    changed,
+    count: namedRoutes.size,
+  };
+}

package/src/support/classRef.ts

@@ -0,0 +1,27 @@
+/**
+ * The framework's one name for "a class, used as a key".
+ *
+ * Policies, event listeners, auto-registered middleware, injection metadata,
+ * column and relation definitions — all of them are registered against the class
+ * itself and read back by walking its prototype chain. A dozen signatures
+ * therefore need a type that means *the constructor*, not *an instance*. That
+ * type used to be the built-in `Function`, which also accepts a plain arrow
+ * function and says nothing about being constructible: the registries would
+ * happily key off a callback.
+ *
+ * `abstract` and `never[]` are both deliberate. A base class is often abstract, a
+ * mixin-composed class takes whatever arguments its bases take, and neither
+ * should be excluded from a registry key. Nothing that holds a `ClassRef` ever
+ * calls the constructor — code that genuinely needs an instance narrows first.
+ *
+ * This is deliberately not the container's `AbstractToken`: a token is something
+ * the container can *resolve*, and its `<T>` is the instance you get back. A
+ * `ClassRef` is only ever a map key, so it asserts nothing about instances and
+ * returns `unknown` — narrowing `object` here would reject the container's own
+ * `new (...args: unknown[]) => T` tokens for a guarantee no caller uses.
+ *
+ * @internal Every signature that takes one is itself `@internal`: this is the
+ * vocabulary first-party packages share for registering metadata, not surface an
+ * app writes against.
+ */
+export type ClassRef = abstract new (...args: never[]) => unknown;