@zerotal/core 1.7.4 → 1.7.5

package/api-surface.md

@@ -686,8 +686,6 @@ function data_get = (target: unknown, key: string, defaultValue?: unknown) => un
 
 function deepMerge = <T extends object>(base: T, override: DeepPartial<T>) => T
 
-function deployEnv = () => string
-
 function devSurfacesEnabled = () => boolean
 
 function env = {    (key: string): string | undefined;    (key: string, fallback: string): string;    (key: string, fallback: boolean): boolean;    (key: string, fallback: number): number;}
@@ -704,8 +702,6 @@ function inject = (...tokens: BindingToken[]) => (target: new (...args: any[]) =
 
 function isDevSurfaceAllowed = (env: string) => boolean
 
-function isProdLike = (env: string) => boolean
-
 function json = (data: unknown, status?: number) => void
 
 function make = <T>(token: BindingToken<T>) => Promise<T>
@@ -728,8 +724,6 @@ function redirect = {    (url: string, status?: 301 | 302 | 303 | 307 | 308): Re
 
 function redirectTo = <N extends RouteTarget>(name: N, params?: RouteParamsArg<N>, status?: 301 | 302 | 303 | 307 | 308) => ResponseBuilder
 
-function registerAppScope = (installer: AppScopeInstaller) => void
-
 function registerErrorDiagnoser = (diagnoser: ErrorDiagnoser) => void
 
 function registerFileRouteResolver = (resolver: FileRouteResolver) => void
@@ -754,8 +748,6 @@ function setAppEnv = (command?: string) => void
 
 function setCurrentPageResolver = (resolver: CurrentPageResolver) => void
 
-function setImplicitModelResolver = (fn: ((paramName: string) => ModelBindingResolver | undefined) | null) => void
-
 function sha256Hex = (input: string | Uint8Array) => string
 
 function singularize = (value: string) => string
@@ -1114,8 +1106,6 @@ type ArgDef = {    name: string;    required?: boolean;    default?: string;}
 
 type BindingToken = ClassToken<T> | AbstractToken<T> | keyof ContainerBindings
 
-type ClassRef = abstract new (...args: never[]) => unknown
-
 type ContextKey = never
 
 type ContextValue = ContextRegistry[K]
@@ -1526,35 +1516,6 @@ class CssBuildCommand = {
   write: (msg: string) => void
 }
 
-class DeployCommand = {
-  new (): DeployCommand
-  static args: ArgDef[]
-  static commandName: string
-  static description: string
-  static flags: ({    name: string;    type: 'boolean';    description: string;    default: boolean;} | {    name: string;    type: 'string';    description: string;    default?: never;})[]
-  static needsApp: boolean
-  static target: string
-  _readLine: () => Promise<string>
-  _writer: OutputWriter
-  app: unknown
-  args: Record<string, string>
-  ask: (question: string, defaultValue?: string) => Promise<string>
-  choice: (question: string, options: string[]) => Promise<string>
-  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
-  dim: (msg: string) => void
-  error: (msg: string) => void
-  flags: Record<string, string | number | boolean>
-  info: (msg: string) => void
-  line: (msg: string) => void
-  newLine: () => void
-  run: () => Promise<void>
-  secret: (question: string) => Promise<string>
-  section: (title: string) => void
-  table: (rows: [string, string][], indent?: number) => void
-  warn: (msg: string) => void
-  write: (msg: string) => void
-}
-
 class DevCommand = {
   new (): DevCommand
   static aliases: string[]
@@ -2316,8 +2277,6 @@ class WorkerCommand = {
   write: (msg: string) => void
 }
 
-function makeDeployCommand = (target: string) => DeployCommandClass
-
 ## ./config  `(./src/config/index.ts)`
 
 class ConfigLoader = {
@@ -2511,8 +2470,6 @@ const SERVER_PROCESS_NAME = 'server'
 
 function bootBuildDecision = (outDirs: string[], env: string | undefined) => Promise<BootBuildDecision>
 
-function browserEnvDefines = (isProduction: boolean) => Record<string, string>
-
 function buildCssBundle = (input: string, outdir: string, minify?: boolean, loader?: Record<string, string>) => Promise<BundleResult>
 
 function buildJsBundle = (input: string, outdir: string, minify?: boolean) => Promise<BundleResult>
@@ -2523,14 +2480,8 @@ function createDeck = (options: DeckOptions) => Deck
 
 function detectCssPlugins = (cwd: string) => Promise<BunPlugin[]>
 
-function isDevOrchestrated = (env?: Record<string, string | undefined>, argv?: readonly string[]) => boolean
-
 function isWritableDir = (dir: string) => Promise<boolean>
 
-function pruneBuildOutput = (outdir: string, outputs: readonly {    path: string;}[]) => Promise<string[]>
-
-function registerDevBuildHook = (name: string, fn: BuildHookFn) => void
-
 function registerDevHtmlSnippet = (name: string, fn: DevHtmlSnippet) => void
 
 function startDevMode = (options: StartDevModeOptions) => Promise<void>
@@ -3409,8 +3360,6 @@ class StackChannel = {
 
 const Log = LogManager
 
-function frameworkLog = (scope: string) => BoundLogger
-
 function LoggingConfig = (options?: Partial<LoggingConfigShape>) => LoggingConfigShape
 
 function renderTable = (data: TableData, indent?: number) => string[]
@@ -3506,17 +3455,11 @@ function hasRoute = (name: string) => boolean
 
 function resetRoutes = () => void
 
-function routeMethod = (name: string) => string | undefined
-
 interface RouteAction = {
   method: string
   url: string
 }
 
-interface RouteMethodRegistry = {}
-
-type MethodedRouteName = never
-
 type RouteArgs = [params?: RouteParamValues, query?: RouteQuery]
 
 type RouteParamValues = {    [x: string]: RouteParamValue | readonly RouteParamValue[];}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.7.4",
+  "version": "1.7.5",
   "license": "MIT",
   "maturity": "stable",
   "private": false,

package/src/application/Application.ts

@@ -34,7 +34,12 @@ import {
 } from "../middleware/SecureHeadersMiddleware.ts";
 import { isAllowedOrigin, allowedOriginsFrom } from "../http/originGuard.ts";
 import { rescueSync } from "../helpers/index.ts";
-import { configureAssets, setAssetVersion, assetVersion } from "../assets/assets.ts";
+import {
+  configureAssets,
+  setAssetVersion,
+  assetVersion,
+  deriveAssetVersion,
+} from "../assets/assets.ts";
 import { ConfigLoader, type ConfigMap } from "../config/ConfigLoader.ts";
 import { Emitter } from "../events/Emitter.ts";
 import { FrameworkEvents, AppBooted } from "../events/FrameworkEvents.ts";
@@ -1358,7 +1363,18 @@ export class Application {
       // each rebuild ships a fresh token over the reload channel (see ServeCommand).
       const isDevWorker = process.argv.includes("--dev-worker");
       configureAssets({ prefix: assets?.prefix ?? "/", dev: isDevWorker });
-      if (isDevWorker) setAssetVersion(Bun.env["ZT_ASSET_VERSION"] ?? "");
+
+      if (isDevWorker) {
+        setAssetVersion(Bun.env["ZT_ASSET_VERSION"] ?? "");
+      } else {
+        // Production gets a token too, derived from the built files. `assets:build`
+        // writes `app.js` under that name every deploy and the static handler sends
+        // no `Cache-Control`, so without this a returning visitor keeps the bundle
+        // their browser cached — through any number of deploys, while the server
+        // reports success. Derived rather than random so a restart that changed no
+        // assets does not invalidate every client's cache for nothing.
+        setAssetVersion(deriveAssetVersion(`${dir}/${assets?.outDir ?? "public"}`));
+      }
     }
 
     // Convention phase — discovers app/schedules (class-based), models, observers, jobs, etc.

package/src/assets/assets.ts

@@ -14,8 +14,25 @@
  * {@link bumpAssetVersion}) and propagated from the dev orchestrator to the
  * server worker over its reload channel. This mirrors Inertia's asset-version
  * model — one token per build, busting every asset at once.
+ *
+ * ## Production needs this more than dev does
+ *
+ * It used to be dev-only, on the reasoning that production assets would be
+ * content-hashed by something downstream. Nothing does: `assets:build` writes
+ * `public/js/app.js` under that exact name every time, the static handler sends
+ * no `Cache-Control`, and so a returning visitor keeps whatever bundle their
+ * browser heuristically cached — for the life of that heuristic, across any
+ * number of deploys. A shipped fix that reaches nobody who has visited before is
+ * the worst kind, because everything on the server says it worked.
+ *
+ * So the version applies whenever it is set, in any environment. In production
+ * it is derived from the built files themselves ({@link deriveAssetVersion}), so
+ * it changes when the assets change and a plain restart does not bust a thing.
  */
 
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
 let _prefix = "/";
 let _dev = false;
 let _version = "";
@@ -36,6 +53,41 @@ export function setAssetVersion(version: string): void {
   _version = version;
 }
 
+/**
+ * A token derived from the built assets in `dir`, or `""` when there are none.
+ *
+ * Name, size and mtime of every file, hashed. Content would be stricter and costs
+ * a full read of every bundle at boot for a token that only has to *change* when
+ * the files do — a rebuild that produces identical bytes keeping its old token is
+ * the correct outcome either way.
+ *
+ * `""` when the directory is missing or empty, which leaves `asset()` emitting
+ * clean URLs rather than a token that means nothing.
+ */
+export function deriveAssetVersion(dir: string): string {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir, { recursive: true }) as string[];
+  } catch {
+    return "";
+  }
+
+  const parts: string[] = [];
+  for (const entry of entries.sort()) {
+    try {
+      const info = statSync(join(dir, entry));
+      if (!info.isFile()) continue;
+      parts.push(`${entry}:${info.size}:${Math.floor(info.mtimeMs)}`);
+    } catch {
+      // Raced with a deploy swapping the directory. Skipping the file is fine:
+      // whatever lands next boot produces a different token anyway.
+    }
+  }
+
+  if (parts.length === 0) return "";
+  return Bun.hash(parts.join("|")).toString(36).slice(0, 10);
+}
+
 /** The current asset version, or `""` when unset. */
 export function assetVersion(): string {
   return _version;
@@ -56,15 +108,15 @@ export function bumpAssetVersion(): string {
  * Build the public URL for a front-end asset.
  *
  * @param path  Asset path relative to the asset prefix (leading slash optional).
- * @returns     `<prefix>/<path>`, with `?v=<version>` appended in dev.
+ * @returns     `<prefix>/<path>`, with `?v=<version>` appended when a version is set.
  *
  * @example
- *   asset("/app.css")   // prod → "/app.css"
- *   asset("app.css")    // dev  → "/app.css?v=lq3k7m"
+ *   asset("/app.css")   // → "/app.css?v=lq3k7m"
+ *   asset("app.css")    // → "/app.css?v=lq3k7m"
  */
 export function asset(path: string): string {
   const url = _joinUrl(_prefix, path);
-  if (_dev && _version) {
+  if (_version) {
     const separator = url.includes("?") ? "&" : "?";
     return `${url}${separator}v=${_version}`;
   }

package/src/assets/index.ts

@@ -1,14 +1,19 @@
 /**
  * Front-end asset URL helper and asset versioning (the `@zerotal/core/assets`
- * subpath). {@link asset} builds the public URL for a built asset, appending a
- * `?v=<version>` cache-buster in dev; the versioning helpers let the dev
- * orchestrator bust every asset at once after a rebuild.
+ * subpath). {@link asset} builds the public URL for a built asset and appends a
+ * `?v=<version>` cache-buster — in every environment, not only in dev.
+ *
+ * Production needs it more: `assets:build` writes `app.js` under that name on
+ * every deploy and the static handler sends no `Cache-Control`, so an unbusted
+ * URL leaves a returning visitor on whatever bundle their browser cached. The
+ * production token is derived from the built files, so it moves when they do and
+ * a plain restart busts nothing.
  *
  * @example
  * ```ts
  * import { asset } from "@zerotal/core/assets";
  *
- * asset("/app.css"); // prod → "/app.css"; dev → "/app.css?v=lq3k7m"
+ * asset("/app.css"); // → "/app.css?v=lq3k7m"
  * ```
  *
  * @packageDocumentation

package/src/build/PackageLinter.ts

@@ -113,6 +113,61 @@ function _checkErrorDiscipline(files: PackageFiles, packageName: string): Violat
 }
 
 /** Lint every package under `packagesDir` and return a report per package. */
+/**
+ * A package below `stable` names the release by which its label is reviewed, and
+ * the review actually falls due.
+ *
+ * The support policy's own argument is that "an honest 'experimental' is useful
+ * once and corrosive indefinitely" — a package that has worn the label for a year
+ * is not being cautious, it is unowned. It then set a review release for `ai` and
+ * `arch` in a prose table, where nothing could enforce it: the version could sail
+ * past and the only consequence would be a sentence quietly becoming untrue.
+ *
+ * So the date lives in `package.json` beside the label it governs, and when the
+ * package's version reaches it, this fails until somebody performs the review —
+ * promote, keep with a new date and the reason, or withdraw.
+ */
+function _checkMaturityReview(files: PackageFiles): Violation[] {
+  const violations: Violation[] = [];
+  const pkg = files.packageJson;
+  if (!pkg) return violations;
+
+  const maturity = pkg["maturity"] as string | undefined;
+  if (!maturity || maturity === "stable") return violations;
+
+  const review = pkg["maturityReview"] as string | undefined;
+  if (!review) {
+    violations.push({
+      rule: "maturity-review",
+      severity: "medium",
+      message: `maturity '${maturity}' with no 'maturityReview' — name the release by which the label is reviewed`,
+    });
+    return violations;
+  }
+
+  const version = pkg["version"] as string | undefined;
+  if (version && _atOrPast(version, review)) {
+    violations.push({
+      rule: "maturity-review-due",
+      severity: "high",
+      message: `maturity '${maturity}' was to be reviewed by ${review} and this package is ${version} — promote it, withdraw it, or set a new 'maturityReview' with the reason in docs/support-policy.md`,
+    });
+  }
+  return violations;
+}
+
+/** Whether `version` has reached `target`, comparing numerically per segment. */
+function _atOrPast(version: string, target: string): boolean {
+  const a = version.split(".").map(Number);
+  const b = target.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const left = a[i] ?? 0;
+    const right = b[i] ?? 0;
+    if (left !== right) return left > right;
+  }
+  return true;
+}
+
 export async function lintPackages(packagesDir: string): Promise<PackageReport[]> {
   const reports: PackageReport[] = [];
   let entries: string[];
@@ -134,6 +189,7 @@ export async function lintPackages(packagesDir: string): Promise<PackageReport[]
       ..._checkTests(files),
       ..._checkPackaging(files),
       ..._checkErrorDiscipline(files, packageName),
+      ..._checkMaturityReview(files),
     ];
     reports.push({ package: packageName, violations });
   }

package/src/events/FrameworkEvents.ts

@@ -35,7 +35,8 @@ function _kindOf(ctor: EventCtor): string {
  *
  * @example
  * ```ts
- * import { FrameworkEvents, QueryExecuted } from "@zerotal/core";
+ * import { FrameworkEvents } from "@zerotal/core";
+ * import { QueryExecuted } from "@zerotal/orm";
  *
  * // In a provider's onBooting(): watch every SQL query.
  * const off = FrameworkEvents.on(QueryExecuted, (e) => {