@schlessera/brain-ui-server 0.15.0 → 0.17.0

package/src/agent/backend.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "@opentelemetry/api-logs";
 import { createRequire } from "module";
 import type { AgentConfig } from "../config/env.js";
 import type { ProviderInfo } from "@schlessera/brain-ui-sdk";
@@ -13,7 +14,7 @@ import type {
  * tests install fakes by constructing a registry, not by mutating a module.
  *
  * BOTH backend packages are optional peers loaded lazily (the same
- * `createRequire` path): a deployment installs the one its AGENT_BACKEND
+ * dynamic-import path): a deployment installs the one its AGENT_BACKEND
  * names, and the other never has to be present — at runtime AND at
  * type-check time (see the structural mirrors below).
  *
@@ -47,6 +48,33 @@ import type {
  * incompatible drift slide.
  */
 
+/**
+ * Mirror of the backends' `BackendLogFn` — the minimal log seam a backend
+ * accepts. A callback rather than a Logger so the backend packages carry no
+ * telemetry dependency; {@link toBackendLog} adapts the registry's Logger.
+ */
+export type BackendLogFn = (
+  level: "debug" | "info" | "warn" | "error",
+  message: string,
+  attrs?: Record<string, string | number | boolean>
+) => void;
+
+const LEVEL_SEVERITY = {
+  debug: "DEBUG",
+  info: "INFO",
+  warn: "WARN",
+  error: "ERROR",
+} as const;
+
+function toBackendLog(log: Logger): BackendLogFn {
+  return (level, message, attrs) =>
+    log.emit({
+      severityText: LEVEL_SEVERITY[level],
+      body: message,
+      ...(attrs ? { attributes: attrs } : {}),
+    });
+}
+
 /** Mirror of the Claude package's `InferenceProfileInput` (declarative shape). */
 export interface ClaudeProfileInput {
   id: string;
@@ -94,6 +122,8 @@ export interface ClaudeBackendModule {
     brainPath: string;
     claudeCodePath?: string;
     profiles?: ClaudeProfile[] | (() => ClaudeProfile[]);
+    confirmBashPatterns?: readonly string[];
+    log?: BackendLogFn;
   }) => AgentBackend;
   createModelSource: (options: {
     brainPath: string;
@@ -145,6 +175,12 @@ export interface BackendRegistryOptions {
    * sessions pinned to it. Defaults to "nothing hidden".
    */
   getHiddenModelIds?: () => string[];
+  /**
+   * Where the registry and its backends report. Adapted to the backends'
+   * minimal callback ({@link BackendLogFn}) before crossing the package
+   * boundary. Absent means silence.
+   */
+  log?: Logger;
 }
 
 export interface BackendRegistry {
@@ -257,6 +293,59 @@ function missingBackendError(primary: "claude" | "pi"): Error {
  * The `resolve` parameter exists for tests (simulating an absent package);
  * production callers pass nothing.
  */
+/** The specifier an ERR_MODULE_NOT_FOUND failed on, or null for any other error. */
+function moduleNotFoundSpecifier(error: unknown): string | null {
+  if (typeof error !== "object" || error === null) return null;
+  const { code, specifier, message } = error as {
+    code?: unknown;
+    specifier?: unknown;
+    message?: unknown;
+  };
+  if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") return null;
+  // Bun's ResolveMessage (not an Error instance) carries the failing
+  // specifier as a property; Node quotes it in the message instead.
+  if (typeof specifier === "string") return specifier;
+  if (typeof message === "string") {
+    const quoted = /Cannot find (?:package|module) '([^']+)'/.exec(message);
+    if (quoted) return quoted[1];
+  }
+  return null;
+}
+
+/**
+ * Load an optional backend package, mapping ONLY "the backend package itself
+ * is not installed" to the actionable install hint. Everything else — the
+ * backend missing one of its OWN transitive deps, a syntax error, a throwing
+ * top-level — is a different failure whose original error IS the diagnostic,
+ * so it is rethrown untouched. The distinction rides on ERR_MODULE_NOT_FOUND
+ * naming the specifier it failed on: a transitive miss names the transitive
+ * dep, not the backend, and must not read as "backend not installed".
+ *
+ * `await import()` rather than `createRequire()(...)`: the backend packages
+ * are ESM, and a CJS require of them under plain Node dies with
+ * ERR_REQUIRE_ESM — which the old blanket catch then reported as "not
+ * installed" on a machine where the package was sitting right there.
+ *
+ * The `importer` parameter exists for tests (simulating absent or broken
+ * packages); production callers pass nothing.
+ */
+export async function loadBackendModule(
+  // "claude" | "pi" spelled out, NOT keyof typeof BACKEND_SPECIFIERS: the
+  // keyof form drags the table's literal string types — the backend
+  // specifiers — into the emitted .d.ts, which the declaration-surface gate
+  // rightly refuses.
+  key: "claude" | "pi",
+  importer: (specifier: string) => Promise<unknown> = (specifier) => import(specifier)
+): Promise<unknown> {
+  const specifier = BACKEND_SPECIFIERS[key];
+  try {
+    return await importer(specifier);
+  } catch (error) {
+    if (moduleNotFoundSpecifier(error) === specifier) throw missingBackendError(key);
+    throw error;
+  }
+}
+
 export function assertBackendResolvable(
   agent: AgentConfig,
   resolve: (specifier: string) => void = (specifier) => {
@@ -278,6 +367,7 @@ export function createBackendRegistry(
 ): BackendRegistry {
   const { brainPath, agent } = options;
   const getHidden = options.getHiddenModelIds ?? (() => []);
+  const backendLog = options.log ? toBackendLog(options.log) : undefined;
 
   let cachedRegistry: Promise<RegistrySnapshot> | null = null;
   let modelSource: ClaudeModelSource | null = null;
@@ -391,18 +481,12 @@ export function createBackendRegistry(
   /**
    * NEITHER backend package is a hard dependency — a deployment installs the
    * one its AGENT_BACKEND names (both, if it switches). Loaded lazily through
-   * the same `createRequire` path so the server still boots without the unused
-   * one; when the configured backend's package is absent, fail with an
-   * actionable message.
+   * {@link loadBackendModule} so the server still boots without the unused
+   * one; only "the package is absent" maps to the actionable install hint,
+   * any other load failure surfaces as itself.
    */
-  function buildClaudeBackend(): AgentBackend {
-    const require = createRequire(import.meta.url);
-    let claude: ClaudeBackendModule;
-    try {
-      claude = require("@schlessera/brain-backend-claude");
-    } catch {
-      throw missingBackendError("claude");
-    }
+  async function buildClaudeBackend(): Promise<AgentBackend> {
+    const claude = (await loadBackendModule("claude")) as ClaudeBackendModule;
     if (typeof claude.createClaudeBackend !== "function") {
       throw new Error(
         '"@schlessera/brain-backend-claude" does not export createClaudeBackend.'
@@ -422,6 +506,12 @@ export function createBackendRegistry(
     return claude.createClaudeBackend({
       brainPath,
       claudeCodePath: agent.claudeCodePath,
+      ...(backendLog ? { log: backendLog } : {}),
+      // Omitted entirely when unconfigured, so the backend's own defaults
+      // apply; an explicit [] passes through and disables confirmation.
+      ...(agent.confirmBashPatterns !== null
+        ? { confirmBashPatterns: agent.confirmBashPatterns }
+        : {}),
       // A function, not an array: discovery refreshes in the background and the
       // new roster has to be visible without restarting the process.
       profiles: () =>
@@ -429,31 +519,30 @@ export function createBackendRegistry(
     });
   }
 
-  function buildPiBackend(): AgentBackend {
-    const require = createRequire(import.meta.url);
-    let mod: { createPiBackend?: (opts: { brainPath: string }) => AgentBackend };
-    try {
-      mod = require("@schlessera/brain-backend-pi");
-    } catch {
-      throw missingBackendError("pi");
-    }
+  async function buildPiBackend(): Promise<AgentBackend> {
+    const mod = (await loadBackendModule("pi")) as {
+      createPiBackend?: (opts: { brainPath: string; log?: BackendLogFn }) => AgentBackend;
+    };
     if (typeof mod.createPiBackend !== "function") {
       throw new Error(
         '"@schlessera/brain-backend-pi" does not export createPiBackend.'
       );
     }
-    return mod.createPiBackend({ brainPath });
+    return mod.createPiBackend({
+      brainPath,
+      ...(backendLog ? { log: backendLog } : {}),
+    });
   }
 
   async function buildRegistry(): Promise<RegistrySnapshot> {
     const primary = agent.backend || "claude";
 
     if (primary === "pi") {
-      const pi = buildPiBackend();
+      const pi = await buildPiBackend();
       return buildSnapshot([pi], pi.id);
     }
 
-    const backends = [buildClaudeBackend()];
+    const backends = [await buildClaudeBackend()];
 
     // AGENT_BACKEND must name a configured backend. The in-process options are
     // "claude" (default) and "pi" (handled above). An unrecognized value is a
@@ -470,10 +559,15 @@ export function createBackendRegistry(
     return cachedRegistry;
   }
 
-  return makeRegistry(getRegistry, getHidden, async () => {
-    await getRegistry();
-    return modelSource;
-  });
+  return makeRegistry(
+    getRegistry,
+    getHidden,
+    async () => {
+      await getRegistry();
+      return modelSource;
+    },
+    options.log
+  );
 }
 
 /**
@@ -485,13 +579,14 @@ export function createBackendRegistry(
 export function createStaticBackendRegistry(
   backends: AgentBackend[],
   defaultBackendId = backends[0]?.id ?? "",
-  options: { getHiddenModelIds?: () => string[] } = {}
+  options: { getHiddenModelIds?: () => string[]; log?: Logger } = {}
 ): BackendRegistry {
   const snapshot = buildSnapshot(backends, defaultBackendId);
   return makeRegistry(
     async () => snapshot,
     options.getHiddenModelIds ?? (() => []),
-    async () => null
+    async () => null,
+    options.log
   );
 }
 
@@ -499,7 +594,8 @@ export function createStaticBackendRegistry(
 function makeRegistry(
   getRegistry: () => Promise<RegistrySnapshot>,
   getHidden: () => string[],
-  getModelSource: () => Promise<ModelDiscoverySource | null>
+  getModelSource: () => Promise<ModelDiscoverySource | null>,
+  log?: Logger
 ): BackendRegistry {
   let profileSnapshot: ProfileSnapshot | null = null;
 
@@ -536,11 +632,11 @@ function makeRegistry(
     try {
       return new Set(getHidden());
     } catch (err) {
-      console.warn(
-        `[models] Could not read hidden models: ${
-          err instanceof Error ? err.message : String(err)
-        }`
-      );
+      log?.emit({
+        severityText: "WARN",
+        body: "could not read hidden models; treating none as hidden",
+        attributes: { error: err instanceof Error ? err.message : String(err) },
+      });
       return new Set();
     }
   }

package/src/app.ts

@@ -1,12 +1,11 @@
 import { Hono } from "hono";
 import type { Context } from "hono";
 import type { Database } from "bun:sqlite";
-import { logger } from "hono/logger";
 import { cors } from "hono/cors";
 import { serveStatic } from "hono/bun";
 import { join } from "path";
 import { resolveServerConfig, type ServerConfig } from "./config/env.js";
-import { healthRoutes, createStatusRoutes } from "./routes/health.js";
+import { createHealthRoutes, createStatusRoutes } from "./routes/health.js";
 import { createBrainRoutes } from "./routes/brain.js";
 import { createSessionRoutes } from "./routes/sessions.js";
 import { createVoiceRoutes } from "./routes/voice.js";
@@ -45,6 +44,7 @@ import { WsHost } from "./ws/host.js";
 import { createWsUpgrade, websocket } from "./ws/connection.js";
 import { createSessionCatalog } from "./ws/session-catalog.js";
 import type { KeytermSettings } from "./voice/keyterm-builder.js";
+import { createObservability, type Observability } from "./observability/index.js";
 
 export type { AppRenderer };
 
@@ -81,6 +81,12 @@ export interface CreateAppOptions {
   turnTimeoutMs?: number;
   /** Backend registry override (tests/embedders); default is built from config. */
   registry?: BackendRegistry;
+  /**
+   * Where this app reports. Defaults to the console consumer; a test passes
+   * `createRecordingObservability()` and then asserts on what the server
+   * actually said, through the same emission path production uses.
+   */
+  observability?: Observability;
 }
 
 /** What `createApp` hands back to the deployment shell. */
@@ -99,6 +105,8 @@ export interface BrainUiApp {
   db: Database;
   /** The WebSocket coordinator (turn state, clients, catalog, registry). */
   wsHost: WsHost;
+  /** Where this app reports — resolved or injected. */
+  observability: Observability;
   /** True while any session has a running turn. */
   isTurnActive(): boolean;
   /** Cancel every running turn (used on shutdown). Returns true if any was. */
@@ -136,14 +144,19 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   // silently fall back to the resolved path.
   const config: ServerConfig =
     options.dbPath !== undefined ? { ...resolved, dbPath: options.dbPath } : resolved;
+  // First thing built, because everything below may want to report — including
+  // the auth validation that can refuse to boot and the migration runner.
+  const observability =
+    options.observability ?? createObservability({ minSeverity: config.logLevel });
   const auth: AuthRuntime = { ...config.auth, host: config.host };
 
   const app = new Hono();
-  const authMode = resolveAuthMode(auth);
+  const authLog = observability.logger("auth");
+  const authMode = resolveAuthMode(auth, authLog);
   // Validate inside the factory, not the bin entry: every consumer of the app
   // (a deployment bin, tests, another embedder) gets the same refuse-to-boot
   // guarantee on an unsafe auth configuration.
-  assertAuthConfig(authMode, auth);
+  assertAuthConfig(authMode, auth, authLog);
   assertPasskeyConfig(config.webauthn);
   // A missing (or unrecognized) agent backend refuses to boot HERE, not on the
   // first turn — otherwise /api/health reports healthy while every turn is
@@ -154,38 +167,69 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   // Per-instance state: the app's own database, the brain CLI wrapper, the
   // backend registry, and the WebSocket host. No module-level singletons —
   // two apps with different configuration coexist in one process.
-  const db = createUiDb(config.dbPath);
+  const dbLog = observability.logger("db");
+  const db = createUiDb(config.dbPath, { log: dbLog });
   const brain = createBrainClient({ brainPath: config.brainPath });
-  const cron = createCronScheduler({ db, brain });
+  const cron = createCronScheduler({ db, brain, log: observability.logger("cron") });
   const registry =
     options.registry ??
     createBackendRegistry({
       brainPath: config.brainPath,
       agent: config.agent,
-      getHiddenModelIds: () => getHiddenModelIds(db),
+      getHiddenModelIds: () => getHiddenModelIds(db, dbLog),
+      log: observability.logger("agent"),
     });
   const host = new WsHost({
     registry,
-    catalog: createSessionCatalog(() => db),
+    observability,
+    catalog: createSessionCatalog(() => db, dbLog),
     ...(options.appName ? { appName: options.appName } : {}),
     ...(options.turnTimeoutMs ? { turnTimeoutMs: options.turnTimeoutMs } : {}),
     maxConcurrentSessions: () => config.maxConcurrentSessions,
+    wsRate: config.wsRate,
   });
   const wsUpgrade = createWsUpgrade(host);
+  // One instrument for every way a login can fail — passkey ceremonies and
+  // password logins land in the same series, split by attributes.
+  const authFailures = observability.meter("auth").createCounter("auth.failures", {
+    description: "Failed authentication ceremonies, by reason",
+  });
   const passkeyCtx: PasskeyContext = {
     db,
     webauthn: config.webauthn,
     auth,
     allowedOrigins: config.allowedOrigins,
+    log: observability.logger("passkeys"),
+    failures: authFailures,
   };
   const keyterms: KeytermSettings = {
     brainPath: config.brainPath,
     cacheDir: config.voice.cacheDir,
     limit: config.voice.keytermLimit,
+    log: observability.logger("voice"),
   };
 
-  // Middleware
-  app.use("*", logger());
+  // Request logging through the observability layer, so BRAIN_UI_LOG_LEVEL
+  // governs it like every other emission (hono's logger() wrote raw console
+  // lines no threshold or consumer swap could touch). Path only — never the
+  // query string or body. /api/health is skipped: the Docker healthcheck
+  // polls it and would drown everything else out.
+  const httpLog = observability.logger("http");
+  app.use("*", async (c, next) => {
+    if (c.req.path === "/api/health") return next();
+    const startedAt = Date.now();
+    await next();
+    httpLog.emit({
+      severityText: "INFO",
+      body: "request",
+      attributes: {
+        method: c.req.method,
+        path: c.req.path,
+        status: c.res.status,
+        "duration.ms": Date.now() - startedAt,
+      },
+    });
+  });
 
   // CORS is only needed for a SPLIT topology where the client is served from a
   // different origin than the API. ALLOWED_ORIGINS is a comma-separated
@@ -208,7 +252,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   // probe and the login/logout routes are reachable without a session.
   // /api/status is intentionally NOT here — it leaks the git SHA, cron errors,
   // and a session oracle, so it lives behind the guard below.
-  app.route("/api", healthRoutes);
+  app.route("/api", createHealthRoutes({ db }));
   // Not under /api, and not behind the guard: this is where a system share
   // lands when no service worker was around to intercept it. See the route.
   app.route("/", shareTargetFallbackRoutes);
@@ -216,6 +260,8 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     "/api",
     authRoutes(authMode, auth, {
       passwordDisabled: (c) => passwordLoginDisabled(c, passkeyCtx),
+      log: authLog,
+      failures: authFailures,
     })
   );
   app.route("/api", passkeyPublicRoutes(authMode, passkeyCtx));
@@ -234,6 +280,9 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
       sourceCommit: config.sourceCommit,
       getCronStatus: () => cron.getCronStatus(),
       isTurnActive: () => host.coordinator.isTurnActive(),
+      // Undefined when the injected consumer cannot be read back (a real OTel
+      // SDK exports elsewhere), in which case the field is simply absent.
+      getMetrics: () => observability.metrics?.snapshot(),
     })
   );
   app.route(
@@ -242,15 +291,28 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   );
   app.route("/api", createSessionRoutes({ registry, db }));
   app.route("/api", createVoiceRoutes({ voice: config.voice, keyterms }));
-  app.route("/api", createFilesRoutes({ brainRoot: config.brainPath }));
   app.route(
     "/api",
-    createShareRoutes({ brainRoot: config.brainPath, allowedOrigins })
+    createFilesRoutes({ brainRoot: config.brainPath, log: observability.logger("files") })
+  );
+  app.route(
+    "/api",
+    createShareRoutes({
+      brainRoot: config.brainPath,
+      allowedOrigins,
+      log: observability.logger("share"),
+    })
   );
-  app.route("/api", createRenderRoutes(options.renderer));
+  app.route("/api", createRenderRoutes(options.renderer, observability.logger("render")));
   app.route("/api", createProviderRoutes({ registry }));
-  app.route("/api", createModelRoutes({ registry, db }));
-  app.route("/api", createGraphRoutes({ brainRoot: config.brainPath }));
+  app.route(
+    "/api",
+    createModelRoutes({ registry, db, log: observability.logger("models") })
+  );
+  app.route(
+    "/api",
+    createGraphRoutes({ brainRoot: config.brainPath, log: observability.logger("graph") })
+  );
 
   // WebSocket endpoint. Browsers can't set headers on the WS handshake, so the
   // upgrade authenticates via the session cookie (or IP/proxy header) INSIDE
@@ -269,8 +331,24 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
   if (options.staticRoot) {
     const staticRoot = options.staticRoot;
     app.use("/*", serveStatic({ root: staticRoot }));
-    // SPA fallback
-    app.get("*", serveStatic({ path: join(staticRoot, "index.html") }));
+
+    // SPA fallback, served directly rather than through serveStatic({ path }).
+    //
+    // That helper resolves its path the same way it resolves `root` — against
+    // the process working directory — so `join(staticRoot, "index.html")`
+    // only lands correctly when `staticRoot` is itself cwd-relative. It is in
+    // the shipped layout, which is why this went unnoticed; an embedder
+    // passing an absolute directory, or a process that changed cwd, got a
+    // fallback that silently 404ed every deep link. Reading the file
+    // ourselves removes the ambiguity for both cases.
+    const indexPath = join(staticRoot, "index.html");
+    app.get("*", async (c) => {
+      const file = Bun.file(indexPath);
+      if (!(await file.exists())) return c.notFound();
+      return new Response(file, {
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+      });
+    });
   }
 
   return {
@@ -280,6 +358,7 @@ export function createApp(options: CreateAppOptions = {}): BrainUiApp {
     authMode,
     db,
     wsHost: host,
+    observability,
     isTurnActive: () => host.coordinator.isTurnActive(),
     cancelActiveTurns: () => host.coordinator.cancelAll("Server shutting down"),
     close: () => {

package/src/config/env-core.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared core of every package's environment chokepoint — a SYNC-ENFORCED
+ * COPY, not a package.
+ *
+ * This file exists byte-identically as `src/config/env-core.ts` in every
+ * package that has an env chokepoint (`src/config/env.ts`), and the root test
+ * `tests/env-core-sync.test.ts` fails the build when any copy differs. To
+ * change it: edit ONE copy, copy the file verbatim into every package that
+ * has one (each `src/config/env-core.ts`), and rerun the sync test.
+ *
+ * Why a copy and not a `@schlessera/brain-env` package: the repo adds a seam
+ * only where a second implementation is plausible (docs/extending/README.md),
+ * and a new package for four fields and three small functions would churn the
+ * release manifest and every dependent's dependency list. Byte-equality
+ * enforced by a test gives the same single-source-of-truth guarantee without
+ * the edge. (`scripts/env-docs.ts` imports the canonical copy in
+ * `packages/core` directly — it is a root script, not published code.)
+ *
+ * What belongs here: the descriptor contract the env-docs generator and the
+ * env-parity gate consume, the dynamic-read escape hatch, and the boolean
+ * parsing helpers. What does NOT belong here: `resolveEnv` — each package's
+ * resolver reads its own variables into its own shape and stays in that
+ * package's `env.ts`.
+ */
+
+/** One environment variable a package reads. */
+export interface EnvVarSpec {
+  /** Variable name as it appears in the environment. */
+  name: string;
+  /** What it controls. */
+  description: string;
+  /**
+   * Behaviour when the variable is unset. Omitted or null when there is no
+   * meaningful default to state.
+   */
+  default?: string | null;
+  /**
+   * `true` when the package cannot do its job at all without it, `false`
+   * when optional; a string states the CONDITION under which it becomes
+   * required (e.g. "AUTH_MODE=password") — flattening that to a boolean
+   * would lose the only part a reader needs.
+   */
+  required: boolean | string;
+}
+
+/** A family of reads whose variable NAME is data, not code. */
+export interface DynamicEnvReadSpec {
+  /** Where the variable name comes from. */
+  source: string;
+  /** What the value is used for. */
+  description: string;
+}
+
+/**
+ * Call-time read of a single variable whose name is data (see the package's
+ * `DYNAMIC_ENV_READS`) or whose presence gates a feature. Never cache the
+ * result at module scope.
+ */
+export function readEnvVar(
+  name: string,
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  return env[name];
+}
+
+const TRUTHY_TOKENS: readonly string[] = ["1", "true", "on", "yes"];
+const FALSY_TOKENS: readonly string[] = ["0", "false", "off", "no"];
+
+/**
+ * The one way a token-valued boolean environment variable is parsed.
+ *
+ * Truthy: 1 / true / on / yes. Falsy: 0 / false / off / no. Matching is
+ * case-insensitive after trimming. Unset, empty, or any unrecognised token
+ * returns `defaultValue` — a typo in a flag must never silently flip a
+ * behaviour; it falls back to the documented default instead.
+ */
+export function envFlag(value: string | undefined, defaultValue: boolean): boolean {
+  if (value === undefined) return defaultValue;
+  const token = value.trim().toLowerCase();
+  if (TRUTHY_TOKENS.includes(token)) return true;
+  if (FALSY_TOKENS.includes(token)) return false;
+  return defaultValue;
+}
+
+/**
+ * Presence-based boolean: set to ANY non-empty value means on. This is the
+ * `NO_COLOR` convention (https://no-color.org) — `NO_COLOR=0` still disables
+ * color — so it must NOT go through `envFlag`. Use only for variables whose
+ * documented contract is presence, not a token.
+ */
+export function envPresent(value: string | undefined): boolean {
+  return value !== undefined && value !== "";
+}