@zerotal/core 1.7.0 → 1.7.3

package/src/router/routes.ts

@@ -48,6 +48,31 @@ import type {
 } from "./registry.ts";
 import { buildRouteUrl, unknownRouteError } from "./buildRoute.ts";
 
+/**
+ * Re-exported so a browser bundle can write its own typed wrappers.
+ *
+ * These live in `registry.ts`, which is reachable from the `@zerotal/core` root
+ * — and that root drags the CLI command modules into any bundle that imports it.
+ * A component building a helper around `route()` needs the types without the
+ * server, so they surface here, on the entry that is already browser-safe.
+ */
+export type { RouteArgs, RouteParamValues, RouteQuery, RouteTarget } from "./registry.ts";
+
+/**
+ * `route()` without an import.
+ *
+ * {@link defineRoutes} puts the builder on `globalThis`, and this is the
+ * declaration that lets a call site use it: a page writes `route("posts.show")`
+ * with no import line, typed exactly as the named export is — the same
+ * `RouteBuilder`, so an unknown name or a missing `:param` still fails the build.
+ *
+ * `var` rather than `const`, because only `var` in a `declare global` block
+ * creates a matching property on `globalThis` for the assignment to satisfy.
+ */
+declare global {
+  var route: RouteBuilder;
+}
+
 /**
  * The name → pattern map `route()` resolves against. A plain object is what
  * `types/routes.generated.ts` exports; a `Map` is accepted so a server-side
@@ -73,6 +98,25 @@ let _table: ReadonlyMap<string, string> | null = null;
  */
 export function defineRoutes(table: RouteTable): void {
   _table = table instanceof Map ? table : new Map(Object.entries(table));
+  _installGlobal();
+}
+
+/**
+ * Put `route()` on `globalThis`, so nothing has to import it.
+ *
+ * This is the one function both processes already call — the server from
+ * `Application._installRouteTable()` at boot, a browser entry beside its
+ * generated `ROUTES` — which makes it the only place that can install the global
+ * for both without an app remembering to do it in two files.
+ *
+ * The table is installed first, deliberately: a global that exists but throws
+ * "no route table" is worse than one that appears at the same moment it works.
+ *
+ * `route` stays a named export. Removing it would break every existing import
+ * for no gain, and a test that wants a clean global can still reach for it.
+ */
+function _installGlobal(): void {
+  (globalThis as { route?: typeof route }).route = route;
 }
 
 /**
@@ -147,3 +191,84 @@ export const route: RouteBuilder = Object.assign(
 // compile time, so `import type { RouteName } from "@zerotal/core"` costs a
 // browser bundle nothing — and a second export path for the same names is a
 // second entry in every surface report, forever, for no runtime benefit.
+
+// ── Verb-aware routes ─────────────────────────────────────────────────────────
+
+/**
+ * Augmented by `types/routes.generated.ts` with the HTTP method of every named
+ * route, exactly as {@link RouteRegistry} is augmented with their patterns.
+ *
+ * @internal The generator writes the augmentation; an app never names this.
+ */
+export interface RouteMethodRegistry {}
+
+/**
+ * A name the generated table knows a verb for.
+ *
+ * @internal Derived from {@link RouteMethodRegistry}, which the generator owns.
+ */
+export type MethodedRouteName = Extract<keyof RouteMethodRegistry, string>;
+
+const methodTable = new Map<string, string>();
+
+/**
+ * Register the generated `METHODS` table.
+ *
+ * Called once at boot beside {@link defineRoutes}. Kept separate because the two
+ * tables have different audiences: a page that only builds links needs the
+ * patterns and never the verbs, and a bundler can then drop the verbs entirely.
+ */
+export function defineRouteMethods(table: Readonly<Record<string, string>>): void {
+  methodTable.clear();
+  for (const [name, method] of Object.entries(table)) methodTable.set(name, method);
+}
+
+/**
+ * The verb a named route answers on, or undefined when it was never registered.
+ *
+ * @internal The read side of {@link defineRouteMethods}; apps call `action()`.
+ */
+export function routeMethod(name: string): string | undefined {
+  return methodTable.get(name);
+}
+
+/** A resolved endpoint: where to send a request, and how. */
+export interface RouteAction {
+  url: string;
+  method: string;
+}
+
+/**
+ * Resolve a named route to both its URL and its HTTP method.
+ *
+ * The pair is the point. A form that hardcodes a URL can still send the wrong
+ * verb, and the failure — a 404 or a 405 on submit — looks nothing like its
+ * cause. Taking both from one generated record means a route that changes verb
+ * changes it everywhere at once.
+ *
+ * Throws when the name has no registered verb. An earlier version defaulted to
+ * `GET`, and that default cost a real bug: a regenerated table came back empty,
+ * every `action()` reported `GET`, and a file upload submitted as a GET to its
+ * own store route and 404'd. The point of resolving a verb from a table is that
+ * a wrong verb becomes impossible — a silent fallback gives that away for a
+ * failure mode nobody reads, so this is loud instead.
+ *
+ * Use {@link route} for links, which need no verb.
+ *
+ * @example
+ * const submit = action("projects.issues.comments.store", { project: "apollo", issue: 4 });
+ * // → { url: "/projects/apollo/issues/4/comments", method: "POST" }
+ */
+export function action<N extends RouteTarget>(name: N, ...args: RouteArgs<N>): RouteAction {
+  const method = methodTable.get(name as string);
+  if (method === undefined) {
+    throw new Error(
+      `action("${String(name)}"): no HTTP method registered for this route. ` +
+        `On the server this is installed at boot, so an empty table means the route ` +
+        `is not registered. In a browser bundle, call defineRouteMethods(METHODS) ` +
+        `from types/routes.generated.ts at your entry point. ` +
+        `Use route() instead for links, which need no verb.`,
+    );
+  }
+  return { url: route(name, ...args), method };
+}

package/src/security/redactGraph.ts

@@ -89,7 +89,16 @@ function _walk(
     }
     const out: Record<string, unknown> = {};
     for (const [key, item] of Object.entries(object as Record<string, unknown>)) {
-      out[key] = options.sensitive(key) ? options.mask : _walk(item, options, depth + 1, seen);
+      // A boolean is never a secret. It has two possible values, so masking one
+      // conceals nothing a reader could not guess — while destroying the answer
+      // they came for. Names are matched by substring, so this is not
+      // hypothetical: `cors.credentials` contains "credential" and came back as
+      // `‹redacted›` on the DevTools Config tab, hiding whether credentialed
+      // CORS was on. That is a security setting a reader is checking *because*
+      // it matters.
+      const maskable = typeof item !== "boolean";
+      out[key] =
+        maskable && options.sensitive(key) ? options.mask : _walk(item, options, depth + 1, seen);
     }
     return out;
   } finally {

package/src/support/env.ts

@@ -53,6 +53,21 @@ export const DEV_WORKER_ENV_VAR = "ZT_DEV";
  */
 export const DEPLOY_ENV_VAR = "ZT_APP_ENV";
 
+/**
+ * Environment variable holding the *runtime mode* — `web`, `worker`, `console`.
+ *
+ * Separate from `APP_ENV`, which holds the deployment name, because they answer
+ * different questions and one variable cannot hold both. It used to try: every
+ * boot overwrote `APP_ENV` with the mode, so `APP_ENV=production` read back as
+ * `"console"` inside a CLI command and a guard written `if (env("APP_ENV") ===
+ * "production") refuse()` was inert exactly where destructive commands live.
+ *
+ * Written by `setAppEnv()`; read through {@link runtimeMode}. Settable by hand to
+ * force a mode — `APP_TYPE=web bun zt.ts something` — which is what the dev
+ * orchestrator does for the server it supervises.
+ */
+export const RUNTIME_MODE_VAR = "APP_TYPE";
+
 /**
  * The values of `APP_ENV` that name a runtime *mode* rather than a deployment.
  * `setAppEnv()` writes these; {@link deployEnv} recognises them to know whether
@@ -73,17 +88,18 @@ export const RUNTIME_MODES: ReadonlySet<string> = new Set([
  * The deployment name this process was started with — `production`, `staging`,
  * `local`, whatever the operator set — as opposed to the runtime *mode*.
  *
- * `APP_ENV` carries both meanings, and the second one destroys the first:
- * `setAppEnv()` overwrites it with `web` / `console` / `worker` before the app
- * boots, so a gate that asks `isProdLike(Bun.env["APP_ENV"])` after startup is
+ * `APP_ENV` used to carry both meanings, and the second destroyed the first:
+ * `setAppEnv()` overwrote it with `web` / `console` / `worker` before the app
+ * booted, so a gate asking `isProdLike(Bun.env["APP_ENV"])` after startup was
  * asking whether `"web"` is production and always getting no. That was not
  * theoretical — it silently disabled the weak-`APP_KEY` refusal and left the
- * ORM's N+1 detector wrapping every query in production.
+ * ORM's N+1 detector wrapping every query in production, and it later made
+ * `env("APP_ENV")` return `"console"` inside a seeder.
  *
- * `setAppEnv()` now preserves the original value, and this reads it back. Prefer
- * it to `Bun.env["APP_ENV"]` for **any** production decision. Config is an
- * equally correct source where it is available (`config("app.env")`), but this
- * works before config is loaded and in processes that have none.
+ * The mode now lives in its own variable ({@link RUNTIME_MODE_VAR}) and `APP_ENV`
+ * is left alone, so this is usually just a read of it. The runtime-mode branch
+ * below stays for a process started by an older launcher, or one where somebody
+ * still exports `APP_ENV=web` by hand.
  *
  * @internal
  */
@@ -101,6 +117,30 @@ export function deployEnv(): string {
   return Bun.env[DEPLOY_ENV_VAR] ?? current;
 }
 
+/**
+ * How this process is running — `web`, `worker`, or `console`.
+ *
+ * The other half of what `APP_ENV` used to mean. Providers are filtered on it
+ * (`static environments = ["console"]`), which is why getting it wrong is not a
+ * cosmetic problem: a provider is simply never asked to register, with no error
+ * and nothing missing from the logs.
+ *
+ * `fallback` is what an unset environment means, and it differs by caller:
+ * `setAppEnv()` treats a process that never declared itself as a script
+ * (`console`), while `Application.create()` has always treated one as a server
+ * (`web`) — an app constructed directly, in a test or a script, expects its
+ * web providers to register.
+ */
+export function runtimeMode(fallback = "console"): string {
+  const mode = (Bun.env[RUNTIME_MODE_VAR] ?? "").toLowerCase();
+  if (RUNTIME_MODES.has(mode)) return mode;
+
+  // A process started by an older launcher, which put the mode in `APP_ENV`.
+  // eslint-disable-next-line no-restricted-syntax -- reading the legacy location is the fallback's entire job
+  const legacy = (Bun.env["APP_ENV"] ?? "").toLowerCase();
+  return RUNTIME_MODES.has(legacy) ? legacy : fallback;
+}
+
 /**
  * Whether *this process* may expose dev-only surfaces — the stack-trace error
  * page, the trace inspector, an open monitor panel.