@zerotal/core 1.8.1 → 1.10.0

package/src/config/validation.ts

@@ -29,7 +29,11 @@ export interface ConfigIssue {
   message: string;
 }
 
-/** Context handed to a config validator. */
+/**
+ * Context handed to a config validator.
+ *
+ * @internal
+ */
 export interface ConfigValidationContext {
   /** The namespace being validated (e.g. `"session"`). */
   namespace: string;
@@ -52,7 +56,11 @@ export type ConfigValidator = (
   ctx: ConfigValidationContext,
 ) => ConfigIssue[] | void;
 
-/** A validator paired with the namespace it guards, as held on the application. */
+/**
+ * A validator paired with the namespace it guards, as held on the application.
+ *
+ * @internal
+ */
 export interface RegisteredConfigValidator {
   namespace: string;
   validate: ConfigValidator;

package/src/conventions/ConventionLoader.ts

@@ -12,7 +12,11 @@ import type { Application } from "../application/Application.ts";
 import type { AppEnvironment } from "../provider/ServiceProvider.ts";
 import { frameworkLog } from "../logger/frameworkLog.ts";
 
-/** The context a concern receives while registering discovered modules. */
+/**
+ * The context a concern receives while registering discovered modules.
+ *
+ * @internal
+ */
 export interface ConcernContext {
   app: Application;
   env: AppEnvironment;
@@ -41,7 +45,7 @@ export interface RunConventionsOptions {
   root: string;
   env: AppEnvironment;
   /** Per-concern directory overrides (config `discovery.paths`). */
-  paths?: Record<string, string>;
+  paths?: Record<string, string> | undefined;
   ctx: ConcernContext;
 }
 
@@ -101,7 +105,10 @@ export async function runConventions(
 ): Promise<void> {
   const orderedConcerns = [...concerns].sort((first, second) => first.order - second.order);
   for (const concern of orderedConcerns) {
-    if (concern.envs && !concern.envs.includes(options.env)) continue;
+    if (concern.envs && !concern.envs.includes(options.env)) {
+      await _announceSkipped(concern, options);
+      continue;
+    }
 
     if (concern.dir && concern.register) {
       const relativeDirectory = options.paths?.[concern.name] ?? concern.dir;
@@ -126,3 +133,37 @@ export async function runConventions(
     }
   }
 }
+
+/**
+ * Say once, at boot, that this process is not running a convention the app has
+ * written files for.
+ *
+ * An env-restricted concern is skipped by *not looking*, which is correct and
+ * completely silent: from a web process's point of view nothing is wrong, because
+ * from a web process's point of view nothing exists. An app ran for weeks in
+ * production with `app/schedules` full and no worker process — no inventory hold
+ * released, no payment reminder sent, nothing logged, and it was found by going
+ * looking rather than by being told.
+ *
+ * Only announced when the directory actually holds files: "skipping 0 schedules" on
+ * every boot of every app is noise, and noise is how the line that matters gets
+ * scrolled past.
+ */
+async function _announceSkipped(
+  concern: ConcernDescriptor,
+  options: RunConventionsOptions,
+): Promise<void> {
+  if (!concern.dir || !concern.register) return;
+
+  const relativeDirectory = options.paths?.[concern.name] ?? concern.dir;
+  const files = (await _scanDir(`${options.root}/${relativeDirectory}`)).filter(
+    (file) => !_shouldSkip(file),
+  );
+  if (files.length === 0) return;
+
+  frameworkLog("app").info(
+    `Skipping ${files.length} file(s) in ${relativeDirectory} — the "${concern.name}" convention ` +
+      `does not run in env=${options.env} (it runs in: ${(concern.envs ?? []).join(", ")}).`,
+    { convention: concern.name, env: options.env, files: files.length },
+  );
+}

package/src/dev/BuildOutput.ts

@@ -98,15 +98,67 @@ function _relative(root: string, path: string): string {
 }
 
 /**
- * The manifest lives outside `outdir` — writing it inside would put a file the
- * app then serves (and registers a route for) into the public directory.
+ * Where a directory's manifest lives.
+ *
+ * Outside `outdir` — writing it inside would put a file the app then serves (and
+ * registers a route for) into the public directory.
+ *
+ * Named from the output directory's path **relative to the project**, not its
+ * absolute one. The hash used to be `Bun.hash(absolutePath)`, which made the
+ * manifest belong to a machine rather than to a release: the same project built at
+ * `/home/me/app` and unpacked at `/opt/app` produced two different filenames, so a
+ * manifest that travelled with a deploy matched nothing at the other end and the
+ * server could not say which files belonged to the current release. It also meant
+ * moving a checkout silently orphaned the record and stopped pruning.
+ *
+ * @internal
  */
-function _manifestPath(root: string): string {
-  const slug = _relative(resolve(process.cwd()), root).replace(/[^a-z0-9]+/gi, "-") || "out";
+export function _buildManifestPath(root: string, cwd: string = process.cwd()): string {
+  const relativeRoot = _relative(resolve(cwd), resolve(root));
+  const slug = relativeRoot.replace(/[^a-z0-9]+/gi, "-") || "out";
   // The slug alone can collide (two different roots normalising to the same
   // name); the hash makes each directory's manifest its own.
-  const hash = Bun.hash(root).toString(36);
-  return join(process.cwd(), MANIFEST_DIR, `${slug}-${hash}.json`);
+  const hash = Bun.hash(relativeRoot).toString(36);
+  return join(cwd, MANIFEST_DIR, `${slug}-${hash}.json`);
+}
+
+/** Back-compat alias used throughout this module. */
+function _manifestPath(root: string): string {
+  return _buildManifestPath(root);
+}
+
+/**
+ * Every file the recorded builds wrote to `outdir`, relative and slash-normalised.
+ *
+ * The answer to "which assets belong to this release" — the question a deploy has
+ * to answer before it can remove anything, and the one that has no answer at all
+ * from inside a directory somebody extracted a tarball over.
+ *
+ * @param outdir - The output directory to describe.
+ * @param cwd - Project root the manifest is stored under. Defaults to the working directory.
+ * @returns The recorded files, or `[]` when no manifest exists.
+ *
+ * @internal
+ */
+export async function _recordedBuildOutput(
+  outdir: string,
+  cwd: string = process.cwd(),
+): Promise<string[]> {
+  try {
+    const contents = (await Bun.file(_buildManifestPath(outdir, cwd)).json()) as unknown;
+    if (Array.isArray(contents)) {
+      return contents.filter((entry): entry is string => typeof entry === "string").sort();
+    }
+    if (!contents || typeof contents !== "object") return [];
+    const files = new Set<string>();
+    for (const list of Object.values(contents as Record<string, unknown>)) {
+      if (!Array.isArray(list)) continue;
+      for (const entry of list) if (typeof entry === "string") files.add(entry);
+    }
+    return [...files].sort();
+  } catch {
+    return [];
+  }
 }
 
 /**

package/src/dev/CssPlugins.ts

@@ -40,6 +40,8 @@ function _scanRoots(cwd: string): string[] {
  *
  * Returns an empty array when `bun-plugin-tailwind` is not installed.
  * The caller falls back to a `bunx @tailwindcss/cli` subprocess.
+ *
+ * @internal
  */
 export async function detectCssPlugins(cwd: string): Promise<BunPlugin[]> {
   try {
@@ -60,6 +62,8 @@ export async function detectCssPlugins(cwd: string): Promise<BunPlugin[]> {
  * @param input   Absolute path to the CSS source (e.g. `${cwd}/resources/css/app.css`)
  * @param outdir  Absolute path to the output directory (e.g. `${cwd}/public/css`)
  * @param minify  Whether to minify the output (true in production)
+ *
+ * @internal
  */
 export async function buildCssBundle(
   input: string,
@@ -155,6 +159,8 @@ export async function buildCssBundle(
  * @param input   Absolute path to the JS/TS entry (e.g. `${cwd}/resources/js/app.js`)
  * @param outdir  Absolute path to the output directory (e.g. `${cwd}/public/js`)
  * @param minify  Whether to minify the output (true in production)
+ *
+ * @internal
  */
 export async function buildJsBundle(
   input: string,
@@ -193,20 +199,24 @@ function _basename(filePath: string): string {
   return filePath.split("/").at(-1) ?? filePath;
 }
 
-/** The resolved `app.assets` config block (see {@link AppAssetsConfig}). */
+/**
+ * The resolved `app.assets` config block (see {@link AppAssetsConfig}).
+ *
+ * @internal
+ */
 export interface AssetBuildConfig {
   entrypoint: string | string[];
   outDir: string;
   prefix: string;
   minify: boolean;
   /** Per-extension loader overrides (e.g. `{ ".woff2": "file" }`). See AppAssetsConfig. */
-  loader?: Record<string, string>;
+  loader?: Record<string, string> | undefined;
   /**
    * Delete everything in `outDir` this build did not write, rather than only what
    * the last build on this machine recorded. See {@link cleanBuildOutput} — it
    * refuses a directory that holds more than build output.
    */
-  clean?: boolean;
+  clean?: boolean | undefined;
 }
 
 /**

package/src/dev/DevBuildHook.ts

@@ -12,7 +12,11 @@
  * server cheerfully reported "rebuilding… ✓ ready" on every change.
  */
 
-/** Outcome of a frontend build: whether it succeeded and any collected logs. */
+/**
+ * Outcome of a frontend build: whether it succeeded and any collected logs.
+ *
+ * @internal
+ */
 export interface BuildResult {
   success: boolean;
   logs?: unknown[];
@@ -25,7 +29,11 @@ export interface BuildResult {
   skipped?: boolean;
 }
 
-/** A frontend build routine that resolves once the build finishes. */
+/**
+ * A frontend build routine that resolves once the build finishes.
+ *
+ * @internal
+ */
 export type BuildHookFn = () => Promise<BuildResult>;
 
 const _hooks = new Map<string, BuildHookFn>();

package/src/dev/DevDeck.ts

@@ -51,6 +51,7 @@ export interface Deck {
   stop(): void;
 }
 
+/** @internal */
 export interface DeckOptions {
   writer: OutputWriter;
   /** Restart the named process — bound to `r`. */
@@ -58,10 +59,10 @@ export interface DeckOptions {
   /** The user asked to quit — bound to `q`. */
   onQuit: () => void;
   /** Force a renderer. Defaults to tabs on a TTY, stream otherwise. */
-  mode?: "tabs" | "stream";
+  mode?: "tabs" | "stream" | undefined;
   /** Overridable for tests. Defaults to `process.stdout`/`process.stdin`. */
-  stdout?: DeckStdout;
-  stdin?: DeckStdin;
+  stdout?: DeckStdout | undefined;
+  stdin?: DeckStdin | undefined;
 }
 
 /** The bits of `process.stdout` the deck reads. */
@@ -90,6 +91,8 @@ export interface DeckStdin {
  * read keys from. A process with a TTY on stdout but not stdin (some CI
  * runners, `zt dev < /dev/null`) would render a tab bar nobody could ever
  * switch, so it gets stream instead.
+ *
+ * @internal
  */
 export function createDeck(options: DeckOptions): Deck {
   const stdout = options.stdout ?? process.stdout;
@@ -108,6 +111,8 @@ export function createDeck(options: DeckOptions): Deck {
  * Colour is applied only when stdout is a terminal. Piped to a file this emits
  * nothing but text, which is the point — a log with escape codes in it is a log
  * you have to clean before you can read it.
+ *
+ * @internal
  */
 export class StreamDeck implements Deck {
   private _width = 0;
@@ -181,6 +186,7 @@ interface Card {
   scroll: number;
 }
 
+/** @internal */
 export class TabsDeck implements Deck {
   private readonly _cards: Card[] = [];
   private readonly _index = new Map<string, Card>();

package/src/dev/DevOrchestrator.ts

@@ -14,6 +14,8 @@ import { ZEROTAL_VERSION, installedCoreVersion } from "../support/version.ts";
  * All optional, and all defaulting to the console. Without them the orchestrator
  * behaves exactly as it did before the deck existed — which is what keeps the
  * plain `bun --watch` path and the existing tests honest.
+ *
+ * @internal
  */
 export interface DevOrchestratorHooks {
   /**

package/src/dev/DevProcess.ts

@@ -69,13 +69,21 @@ export interface DevProcessDefinition {
   color?: DevProcessColor;
 }
 
-/** The colours a deck tab can take. Named, not ANSI codes, so the deck owns the rendering. */
+/**
+ * The colours a deck tab can take. Named, not ANSI codes, so the deck owns the rendering.
+ *
+ * @internal
+ */
 export type DevProcessColor = "cyan" | "magenta" | "yellow" | "green" | "blue" | "red";
 
 /** Assigned in order to processes that did not pick a colour. */
 const _PALETTE: DevProcessColor[] = ["cyan", "magenta", "yellow", "green", "blue", "red"];
 
-/** A definition with every default filled in and its argv settled. */
+/**
+ * A definition with every default filled in and its argv settled.
+ *
+ * @internal
+ */
 export interface ResolvedDevProcess {
   name: string;
   label: string;
@@ -95,12 +103,16 @@ export interface ResolvedDevProcess {
   registrant: string;
 }
 
-/** The `app.dev` config block. */
+/**
+ * The `app.dev` config block.
+ *
+ * @internal
+ */
 export interface DevConfigShape {
   /** App-level processes, registered after every provider's. */
-  processes?: DevProcessDefinition[];
+  processes?: DevProcessDefinition[] | undefined;
   /** Names to drop, whoever registered them. */
-  disable?: string[];
+  disable?: string[] | undefined;
 }
 
 /** The bits of `Application` this module needs — kept structural to avoid a cycle. */
@@ -123,6 +135,8 @@ interface ConfigReader {
  * @param app     A booted application — providers must have run, since `enabled`
  *                and a `command` thunk are allowed to read config.
  * @param config  The config manager, read for `app.dev`.
+ *
+ * @internal
  */
 export async function collectDevProcesses(
   app: ProviderHost,

package/src/dev/DevReloadMiddleware.ts

@@ -19,7 +19,11 @@ import type { HttpContext } from "../pipeline/HttpContext.ts";
 import { BaseMiddleware } from "../middleware/BaseMiddleware.ts";
 import { DEV_RELOAD_CLIENT } from "./reloadClient.ts";
 
-/** Produces an HTML fragment to inject before `</body>` for the given request. */
+/**
+ * Produces an HTML fragment to inject before `</body>` for the given request.
+ *
+ * @internal
+ */
 export type DevHtmlSnippet = (ctx: HttpContext) => string;
 
 interface RegisteredSnippet {
@@ -39,6 +43,8 @@ const _snippets: RegisteredSnippet[] = [];
  * registerDevHtmlSnippet("devtools", (ctx) =>
  *   ctx.url.pathname.startsWith("/__zerotal") ? "" : `<script src="/__zerotal/devtools/client.js"></script>`,
  * );
+ *
+ * @internal
  */
 export function registerDevHtmlSnippet(name: string, fn: DevHtmlSnippet): void {
   if (_snippets.some((s) => s.name === name)) return;

package/src/dev/DevSupervisor.ts

@@ -1,4 +1,4 @@
-/**
+/**
  * Runs the dev processes and keeps them running.
  *
  * The supervisor owns lifetimes, not presentation: it spawns, watches, restarts,
@@ -16,7 +16,11 @@
  */
 import type { ResolvedDevProcess } from "./DevProcess.ts";
 
-/** What the supervisor needs back from whatever it spawned. */
+/**
+ * What the supervisor needs back from whatever it spawned.
+ *
+ * @internal
+ */
 export interface DevChild {
   readonly stdout: ReadableStream<Uint8Array> | null;
   readonly stderr: ReadableStream<Uint8Array> | null;
@@ -24,16 +28,28 @@ export interface DevChild {
   kill(signal?: number | NodeJS.Signals): void;
 }
 
-/** How the supervisor starts a child. Injected so tests need no real processes. */
+/**
+ * How the supervisor starts a child. Injected so tests need no real processes.
+ *
+ * @internal
+ */
 export type DevSpawnFn = (
   argv: string[],
   options: { cwd: string; env: Record<string, string | undefined> },
 ) => DevChild;
 
-/** Where a process is in its life. */
+/**
+ * Where a process is in its life.
+ *
+ * @internal
+ */
 export type DevProcessState = "starting" | "running" | "restarting" | "exited" | "parked";
 
-/** A process as the deck sees it. */
+/**
+ * A process as the deck sees it.
+ *
+ * @internal
+ */
 export interface DevProcessStatus {
   name: string;
   label: string;
@@ -53,19 +69,20 @@ export interface DevSupervisorHooks {
   onState?: (status: DevProcessStatus) => void;
 }
 
+/** @internal */
 export interface DevSupervisorOptions extends DevSupervisorHooks {
   cwd: string;
-  env?: Record<string, string | undefined>;
+  env?: Record<string, string | undefined> | undefined;
   /** Defaults to `Bun.spawn` with output piped and **stdin ignored**. */
-  spawn?: DevSpawnFn;
+  spawn?: DevSpawnFn | undefined;
   /**
    * Backoff before each retry, in ms. Overridable for the same reason `spawn`
    * is: a test of the restart policy should assert the policy, not spend three
    * seconds proving that `setTimeout` works.
    */
-  backoffMs?: number[];
+  backoffMs?: number[] | undefined;
   /** How long a run must last to be considered healthy. See {@link HEALTHY_AFTER_MS}. */
-  healthyAfterMs?: number;
+  healthyAfterMs?: number | undefined;
 }
 
 /** Give up after this many consecutive failed starts. */
@@ -92,6 +109,7 @@ interface Entry {
   healthyTimer?: ReturnType<typeof setTimeout> | undefined;
 }
 
+/** @internal */
 export class DevSupervisor {
   private readonly _entries = new Map<string, Entry>();
   private readonly _cwd: string;

package/src/dev/bootBuild.ts

@@ -23,7 +23,11 @@
 import { mkdir, unlink, writeFile } from "node:fs/promises";
 import { isProdLike } from "../support/env.ts";
 
-/** What to do about a boot-time asset build, and why. */
+/**
+ * What to do about a boot-time asset build, and why.
+ *
+ * @internal
+ */
 export interface BootBuildDecision {
   /** Whether to run the build. */
   build: boolean;
@@ -37,6 +41,8 @@ export interface BootBuildDecision {
  * Tested by writing rather than by reading a permission bit: the thing that makes
  * `public/` unwritable in the failure this guards against is `ProtectSystem=strict`, a
  * mount-level restriction that a mode check does not see.
+ *
+ * @internal
  */
 export async function isWritableDir(dir: string): Promise<boolean> {
   const probe = `${dir}/.zerotal-write-probe-${process.pid}`;
@@ -68,6 +74,8 @@ export async function isWritableDir(dir: string): Promise<boolean> {
  * if (!decision.build) console.info(decision.reason);
  * else await build();
  * ```
+ *
+ * @internal
  */
 export async function bootBuildDecision(
   outDirs: string[],

package/src/dev/index.ts

@@ -33,7 +33,12 @@ export { DEV_RELOAD_CLIENT } from "./reloadClient.ts";
 export { browserEnvDefines } from "./buildEnv.ts";
 export { detectCssPlugins, buildCssBundle, buildJsBundle } from "./CssPlugins.ts";
 export type { AssetBuildConfig } from "./CssPlugins.ts";
-export { pruneBuildOutput, cleanBuildOutput } from "./BuildOutput.ts";
+export {
+  pruneBuildOutput,
+  cleanBuildOutput,
+  _recordedBuildOutput,
+  _buildManifestPath,
+} from "./BuildOutput.ts";
 // Lets `serve` and any view provider agree on whether to build at boot, so a hardened
 // production unit with a read-only output directory logs a line instead of restart-looping.
 export { bootBuildDecision, isWritableDir } from "./bootBuild.ts";

package/src/dev/reloadClient.ts

@@ -19,6 +19,8 @@
  * Exported as a string because it is injected inline: `DevReloadMiddleware`
  * rewrites HTML responses with it for every view layer, and Inertia bakes it
  * into its cached template so streamed pages need no body rewrite.
+ *
+ * @internal
  */
 export const DEV_RELOAD_CLIENT: string =
   `<script>(function(){` +

package/src/dev/startDevMode.ts

@@ -31,7 +31,7 @@ export interface StartDevModeOptions {
    * and nothing to serve it to — `--only=queue` is supervision and a deck, and
    * the orchestrator that would call this never starts.
    */
-  build?: BuildHookFn;
+  build?: BuildHookFn | undefined;
   /** Everything the providers and the app contributed, already filtered. */
   processes: ResolvedDevProcess[];
   writer: OutputWriter;
@@ -39,7 +39,11 @@ export interface StartDevModeOptions {
   deckMode?: "tabs" | "stream" | undefined;
 }
 
-/** The server's card. Named so `--only=server` and `--without=server` read naturally. */
+/**
+ * The server's card. Named so `--only=server` and `--without=server` read naturally.
+ *
+ * @internal
+ */
 export const SERVER_PROCESS_NAME = "server";
 
 /**
@@ -47,6 +51,8 @@ export const SERVER_PROCESS_NAME = "server";
  *
  * Never returns: the orchestrator parks on an unresolved promise and the exit
  * happens in its signal handlers, after the deck has restored the terminal.
+ *
+ * @internal
  */
 export async function startDevMode(options: StartDevModeOptions): Promise<void> {
   const supervised = options.processes.filter((entry) => entry.name !== SERVER_PROCESS_NAME);

package/src/doctor/AppDoctor.ts

@@ -17,6 +17,7 @@ import { appKeyStrengthWarning } from "../support/appKey.ts";
 import { unroutedRoutesWarning } from "../support/unroutedRoutes.ts";
 import { isWritableDir } from "../dev/bootBuild.ts";
 import { isProdLike } from "../support/env.ts";
+import { throttlesKeyedOnSocket } from "./throttleIdentity.ts";
 
 /** One finding: ok is silent health, warn is worth reading, fail is broken now. */
 export interface DoctorCheckResult {
@@ -365,12 +366,53 @@ const secureHeadersCheck: DoctorCheck = {
   },
 };
 
-/** The core checks every app gets. */
+/**
+ * A rate limiter behind a proxy that was never told about the proxy keys every
+ * visitor to the same bucket, because the socket address is the proxy's. It then
+ * does the opposite of its job: one attacker spends the allowance for everybody.
+ *
+ * A warning rather than a failure, because the framework cannot see the deployment.
+ * An app served directly, with no proxy in front of it, is correctly configured
+ * exactly as it stands — and that app should not be blocked from deploying by a
+ * guess. What is worth saying is that the combination is almost always wrong, and
+ * that nothing else will ever tell you.
+ */
+const throttleIdentityCheck: DoctorCheck = {
+  id: "throttle-trusted-proxies",
+  label: "Rate-limit identity",
+  run(app) {
+    const exposed = throttlesKeyedOnSocket(app);
+    if (exposed.length === 0) return ok("every registered throttle can identify a client.");
+    if (!_isProductionEnv(app)) {
+      return ok(`${exposed.length} throttle(s) key on the socket address — fine locally.`);
+    }
+    const where = exposed
+      .slice(0, 3)
+      .map((t) => t.where)
+      .join(", ");
+    return warn(
+      `${exposed.length} throttle(s) (${where}${exposed.length > 3 ? ", …" : ""}) key on the ` +
+        `socket address and no trustedProxies is set. Behind a reverse proxy that address is ` +
+        `the proxy's for every request, so all visitors share one bucket and one of them can ` +
+        `lock out the rest.`,
+      "If a proxy fronts this app, set trustedProxies to how many — `ThrottleMiddleware.with({ " +
+        "maxAttempts: 5, trustedProxies: 1 })`, or `app.throttle.trustedProxies` for all of " +
+        "them. If nothing fronts it, this is already correct.",
+    );
+  },
+};
+
+/**
+ * The core checks every app gets.
+ *
+ * @internal
+ */
 export const builtinDoctorChecks: DoctorCheck[] = [
   appKeyCheck,
   allowedOriginsCheck,
   corsWildcardCheck,
   secureHeadersCheck,
+  throttleIdentityCheck,
   bootAssetWriteCheck,
   syncVsMigrationsCheck,
   unroutedRoutesCheck,