@schlessera/brain-ui-server 0.32.0 → 0.33.1

package/src/brain/client.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "fs";
 import { join } from "path";
+import type { Logger } from "@opentelemetry/api-logs";
 import { subprocessEnv } from "../config/env.js";
 import type {
   BrainSearchResult,
@@ -48,6 +49,13 @@ interface ExecResult {
   exitCode: number;
 }
 
+/**
+ * First core release whose parser understands `--`. The ui-server inserts the
+ * separator before user input, so an older brain repo pin would lose every
+ * positional silently.
+ */
+export const MIN_BRAIN_CLI_VERSION = "0.33.0";
+
 /**
  * argv prefix for invoking the brain CLI inside `brainPath`.
  *
@@ -67,6 +75,88 @@ export function brainCliCommand(brainPath: string): string[] {
   return ["bun", "scripts/brain-cli.ts"];
 }
 
+interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: boolean;
+}
+
+function parseVersion(value: string): ParsedVersion | null {
+  const match = value.match(
+    // Full SemVer 2.0.0 grammar: prerelease and build metadata are
+    // dot-separated NON-EMPTY identifiers. A loose `[0-9A-Za-z.-]+` would
+    // accept "0.32.9-.." and treat garbage as a real prerelease, which the
+    // comparison below would then refuse to boot on instead of warning.
+    /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
+  );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] !== undefined,
+  };
+}
+
+function isBelowMinimum(found: ParsedVersion, minimum: ParsedVersion): boolean {
+  for (const key of ["major", "minor", "patch"] as const) {
+    if (found[key] !== minimum[key]) return found[key] < minimum[key];
+  }
+  return found.prerelease && !minimum.prerelease;
+}
+
+/** Probe the brain repo's own CLI pin, refusing only known-incompatible versions. */
+export function probeBrainCliVersion(brainPath: string, log: Logger): void {
+  let result: ReturnType<typeof Bun.spawnSync>;
+  try {
+    result = Bun.spawnSync([...brainCliCommand(brainPath), "--version"], {
+      cwd: brainPath,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: subprocessEnv("brainCli", { NO_COLOR: "1" }),
+      timeout: 5_000,
+    });
+  } catch (error) {
+    log.emit({
+      severityText: "WARN",
+      body: "brain CLI version probe failed; continuing",
+      attributes: {
+        reason: error instanceof Error ? error.message : String(error),
+      },
+    });
+    return;
+  }
+
+  if (result.exitCode !== 0) {
+    log.emit({
+      severityText: "WARN",
+      body: "brain CLI version probe failed; continuing",
+      attributes: { "exit.code": result.exitCode },
+    });
+    return;
+  }
+
+  const foundText = new TextDecoder().decode(result.stdout).trim();
+  const found = parseVersion(foundText);
+  const minimum = parseVersion(MIN_BRAIN_CLI_VERSION)!;
+  if (!found) {
+    log.emit({
+      severityText: "WARN",
+      body: "brain CLI returned an unparseable version; continuing",
+      attributes: { version: foundText },
+    });
+    return;
+  }
+
+  if (isBelowMinimum(found, minimum)) {
+    throw new Error(
+      `brain CLI version ${foundText} is incompatible: version ${MIN_BRAIN_CLI_VERSION} ` +
+        `or newer is required; bump the brain repo's @schlessera/brain pin before deploying.`
+    );
+  }
+}
+
 export function createBrainClient(opts: { brainPath: string }): BrainClient {
   const { brainPath } = opts;
 
@@ -76,7 +166,7 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
       stdout: "pipe",
       stderr: "pipe",
       // Force JSON output when not a TTY
-      env: subprocessEnv({ NO_COLOR: "1" }),
+      env: subprocessEnv("brainCli", { NO_COLOR: "1" }),
     });
 
     const [stdout, stderr] = await Promise.all([
@@ -108,11 +198,12 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
     },
 
     async search(query, opts) {
-      const args = ["search", query];
+      const args = ["search"];
       if (opts?.type) args.push("--type", opts.type);
       if (opts?.tag) args.push("--tag", opts.tag);
       if (opts?.limit) args.push("--limit", String(opts.limit));
       if (opts?.mode) args.push("--mode", opts.mode);
+      args.push("--", query);
 
       const result = await execBrain(args);
       const parsed = parseJsonOutput<BrainSearchResponse | BrainSearchResult[]>(result);
@@ -146,7 +237,7 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
     },
 
     async read(path) {
-      const result = await execBrain(["read", path]);
+      const result = await execBrain(["read", "--", path]);
       if (result.exitCode !== 0) {
         throw new Error(`brain read failed: ${result.stderr}`);
       }
@@ -178,10 +269,11 @@ export function createBrainClient(opts: { brainPath: string }): BrainClient {
     },
 
     async add(content, opts) {
-      const args = ["add", content];
+      const args = ["add"];
       if (opts?.type) args.push("--type", opts.type);
       if (opts?.title) args.push("--title", opts.title);
       if (opts?.tags) args.push("--tags", opts.tags.join(","));
+      args.push("--", content);
 
       const result = await execBrain(args);
       if (result.exitCode !== 0) {

package/src/config/env.ts

@@ -21,6 +21,8 @@ import { SEVERITIES, type Severity } from "../observability/types.js";
 import { envFlag } from "./env-core.js";
 import {
   filterSubprocessEnv,
+  parseSubprocessEnvExtra,
+  type SubprocessEnvAudience,
   WEB_SEARCH_PROVIDERS,
 } from "@schlessera/brain-ui-sdk/server";
 
@@ -69,6 +71,16 @@ export const ENV_VARS: readonly EnvVarDescriptor[] = [
     default: "/root",
     required: false,
   },
+  {
+    name: "BRAIN_UI_SUBPROCESS_ENV_EXTRA",
+    description:
+      "Comma-separated environment variable names to admit to every child " +
+      "audience when an operator integration needs a variable outside the " +
+      "shipped allowlist. Names are trimmed; malformed entries are ignored; " +
+      "the control variable itself is never forwarded.",
+    default: "(empty)",
+    required: false,
+  },
   {
     name: "PI_CODING_AGENT_DIR",
     description:
@@ -105,8 +117,11 @@ export const ENV_VARS: readonly EnvVarDescriptor[] = [
   },
   {
     name: "DB_PATH",
-    description: "SQLite file for the UI's own database (sessions, passkeys, settings).",
-    default: "./brain-ui.db",
+    description:
+      "SQLite file for the UI's own database (sessions, passkeys, settings). " +
+      "The server factory defaults to ./brain-ui.db; brain-ui-cron defaults " +
+      "to the container path /data/db/brain-ui.db.",
+    default: "./brain-ui.db (server); /data/db/brain-ui.db (brain-ui-cron)",
     required: false,
   },
   {
@@ -494,6 +509,20 @@ export interface ServerConfig {
 
 type EnvRecord = Record<string, string | undefined>;
 
+/** Configuration resolved specifically for the standalone cron bin. */
+export interface CronConfig {
+  /** Brain repository inspected by the crontab emitter. */
+  brainPath: string;
+  /** The deployment database; unlike createApp(), the bin defaults to the container path. */
+  dbPath: string;
+  /** Allowlisted brain CLI environment used only to discover module cron entries. */
+  moduleDiscoveryEnv: EnvRecord;
+  /** Allowlisted environment for the scheduled child, before the span sink is added. */
+  childEnv: EnvRecord;
+  /** Valid operator-added names, also used when emitting /etc/environment. */
+  subprocessEnvExtraNames: string[];
+}
+
 function list(raw: string | undefined): string[] {
   return (raw ?? "")
     .split(",")
@@ -663,13 +692,63 @@ export function resolveServerConfig(env: EnvRecord = process.env): ServerConfig
 }
 
 /**
- * The filtered parent environment for spawned subprocesses (brain CLI,
- * whatsup), plus explicit overrides. The shared descriptor strips server-only
- * material while retaining all known subprocess capabilities and unknown
- * variables. This reads `process.env`, so it lives behind this chokepoint.
+ * Resolve the standalone cron bin's paths and allowlisted scheduled-job
+ * environment. The escape hatch is parsed here, at this package's sole env
+ * chokepoint, and its control variable is held back from the child.
+ */
+export function resolveCronConfig(
+  env: EnvRecord = process.env,
+  admittedNames: readonly string[] = []
+): CronConfig {
+  const subprocessEnvExtraNames = parseSubprocessEnvExtra(
+    [env.BRAIN_UI_SUBPROCESS_ENV_EXTRA, ...admittedNames].join(",")
+  );
+  return {
+    brainPath: env.BRAIN_PATH || "/data/brain",
+    dbPath: env.DB_PATH || "/data/db/brain-ui.db",
+    moduleDiscoveryEnv: filterPackageSubprocessEnv(
+      env,
+      "brainCli",
+      subprocessEnvExtraNames
+    ),
+    childEnv: filterPackageSubprocessEnv(
+      env,
+      "cron",
+      subprocessEnvExtraNames
+    ),
+    subprocessEnvExtraNames,
+  };
+}
+
+/**
+ * Build a package-owned child environment from an environment value.
+ */
+function filterPackageSubprocessEnv(
+  env: EnvRecord,
+  audience: SubprocessEnvAudience,
+  extraNames: readonly string[] = [],
+  extra: Record<string, string> = {}
+): EnvRecord {
+  const operatorNames = parseSubprocessEnvExtra(
+    env.BRAIN_UI_SUBPROCESS_ENV_EXTRA
+  );
+  return {
+    ...filterSubprocessEnv(env, audience, [...operatorNames, ...extraNames]),
+    ...extra,
+  };
+}
+
+/**
+ * The allowlisted parent environment for a spawned subprocess, plus explicit
+ * overrides. The agent default preserves this exported helper's historical
+ * no-argument use; every ui-server spawn names its actual audience.
  */
-export function subprocessEnv(extra: Record<string, string> = {}): EnvRecord {
-  return { ...filterSubprocessEnv(process.env), ...extra };
+export function subprocessEnv(
+  audience: SubprocessEnvAudience = "agent",
+  extra: Record<string, string> = {},
+  extraNames: readonly string[] = []
+): EnvRecord {
+  return filterPackageSubprocessEnv(process.env, audience, extraNames, extra);
 }
 
 /**

package/src/cron/digest.ts

@@ -0,0 +1,45 @@
+/** The standalone daily activity-digest job. Failures are deliberately loud. */
+import { generateActivityDigest } from "../activity/digest.js";
+import { createUiDb } from "../db/client.js";
+
+interface TextSink {
+  write(text: string): unknown;
+}
+
+export interface DigestOptions {
+  dbPath: string;
+  stdout?: TextSink;
+  stderr?: TextSink;
+}
+
+export interface DigestDependencies {
+  createDb?: typeof createUiDb;
+  generateDigest?: typeof generateActivityDigest;
+}
+
+/** Generate and persist one digest, returning a process-compatible status. */
+export function runDigest(
+  options: DigestOptions,
+  dependencies: DigestDependencies = {}
+): number {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const openDb = dependencies.createDb ?? createUiDb;
+  const generate = dependencies.generateDigest ?? generateActivityDigest;
+  let db: ReturnType<typeof createUiDb> | undefined;
+
+  try {
+    db = openDb(options.dbPath);
+    const digest = generate(db);
+    stdout.write(
+      `[brain-digest] generated: ${digest.runs} runs, ${digest.failures} failures, $${digest.costUsd.toFixed(2)}\n`
+    );
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(`[brain-digest] failed: ${message}\n`);
+    return 1;
+  } finally {
+    db?.close();
+  }
+}

package/src/cron/emit.ts

@@ -0,0 +1,262 @@
+import {
+  parseSubprocessEnvExtra,
+  SUBPROCESS_ENV,
+  type SubprocessEnvAudience,
+} from "@schlessera/brain-ui-sdk/server";
+
+/** One cron manifest entry in `brain module list --json`. */
+export interface BrainModuleListCronEntry {
+  name: string;
+  schedule: string;
+  command: string;
+}
+
+/** One enabled module in the core CLI's module-list payload. */
+export interface BrainModuleListEnabledModule {
+  name: string;
+  key: string;
+  description: string | null;
+  types: string[];
+  commands: string[];
+  cron: BrainModuleListCronEntry[];
+}
+
+/** One disabled-but-available module in the core CLI's module-list payload. */
+export interface BrainModuleListAvailableModule {
+  key: string;
+  description: string | null;
+  enabled: false;
+}
+
+/** The payload emitted by `brain module list --json`. */
+export interface BrainModuleListPayload {
+  enabled: BrainModuleListEnabledModule[];
+  available: BrainModuleListAvailableModule[];
+}
+
+export interface EmitCrontabOptions {
+  /** Null means the core CLI was unavailable or did not return JSON. */
+  modules: BrainModuleListPayload | null;
+  /** Command prefix that records and runs one job. */
+  wrapperCommand: string;
+  /** Command executed inside the wrapper's `digest` job. */
+  digestCommand: string;
+  /** Complete `PATH=...` crontab line. */
+  pathLine: string;
+  /** System crontab user field. */
+  user: string;
+  /** Whether `scripts/jobs/scrape-all.ts` exists in the brain repository. */
+  legacyScraperPresent: boolean;
+  /** Valid names carried into each wrapper so the run process re-admits them. */
+  subprocessEnvExtraNames?: readonly string[];
+}
+
+const MODULE_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const CRON_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const CRON_SCHEDULE = /^[-0-9*,/ ]{1,100}$/;
+const CRON_COMMAND = /^[A-Za-z0-9 _.:=@,/-]{1,200}$/;
+
+// These use ^...$ without the `m` flag deliberately. In JavaScript `$`
+// matches only at the true end of the string, so these are the correct
+// translation of the bash jq/Oniguruma guards, which needed \A...\z because
+// Oniguruma's `$` can match before a trailing newline.
+function validModuleName(value: unknown): value is string {
+  return typeof value === "string" && MODULE_NAME.test(value);
+}
+
+function validCronEntry(value: unknown): value is BrainModuleListCronEntry {
+  if (!value || typeof value !== "object") return false;
+  const entry = value as Partial<BrainModuleListCronEntry>;
+  return (
+    typeof entry.name === "string" &&
+    CRON_NAME.test(entry.name) &&
+    typeof entry.schedule === "string" &&
+    CRON_SCHEDULE.test(entry.schedule) &&
+    typeof entry.command === "string" &&
+    CRON_COMMAND.test(entry.command)
+  );
+}
+
+function assertSingleLine(name: string, value: string): void {
+  if (/[\0\r\n]/.test(value)) {
+    throw new Error(`${name} must be a single line`);
+  }
+}
+
+/**
+ * Emit `/etc/cron.d/brain-ui` with the same byte layout as the deployment
+ * shell's historical `generate_crontab` function.
+ */
+export function emitCrontab(options: EmitCrontabOptions): string {
+  const {
+    modules,
+    wrapperCommand,
+    digestCommand,
+    pathLine,
+    user,
+    legacyScraperPresent,
+    subprocessEnvExtraNames = [],
+  } = options;
+
+  assertSingleLine("wrapperCommand", wrapperCommand);
+  assertSingleLine("digestCommand", digestCommand);
+  assertSingleLine("pathLine", pathLine);
+  assertSingleLine("user", user);
+
+  const validatedExtraNames = parseSubprocessEnvExtra(
+    subprocessEnvExtraNames.join(",")
+  );
+  const wrapper =
+    validatedExtraNames.length === 0
+      ? wrapperCommand
+      : `${wrapperCommand} --subprocess-env-extra ${validatedExtraNames.join(",")}`;
+
+  const lines = [
+    "# Generated by entrypoint.sh — regenerated on each container start.",
+    pathLine,
+    "",
+    "# Base jobs",
+    `0 2 * * * ${user} cd /data/brain && ${wrapper} sync -- sh -c 'brain sync && brain index' 2>&1 | logger -t brain-sync`,
+    `0 3 * * * ${user} cd /data/brain && ${wrapper} validate -- brain validate 2>&1 | logger -t brain-validate`,
+    `0 7 * * * ${user} cd /data/brain && ${wrapper} maintain -- brain maintain 2>&1 | logger -t brain-maintain`,
+    `30 7 * * * ${user} cd /data/brain && ${wrapper} digest -- ${digestCommand} 2>&1 | logger -t brain-digest`,
+    "",
+    "# Module jobs (from enabled modules' cron manifests, when exposed)",
+  ];
+
+  const enabled = modules && Array.isArray(modules.enabled) ? modules.enabled : [];
+  if (modules === null) {
+    lines.push("# (brain module list unavailable — module cron skipped)");
+  } else {
+    for (const module of enabled) {
+      if (!module || typeof module !== "object" || !validModuleName(module.name)) continue;
+      const entries = Array.isArray(module.cron) ? module.cron : [];
+      for (const entry of entries) {
+        if (!validCronEntry(entry)) continue;
+        const jobName = `${module.name}-${entry.name}`;
+        lines.push(
+          `${entry.schedule} ${user} cd /data/brain && ${wrapper} ${jobName} -- brain ${entry.command} 2>&1 | logger -t brain-${jobName}`
+        );
+      }
+    }
+  }
+
+  const jobsModuleEnabled = enabled.some(
+    (module) =>
+      module &&
+      typeof module === "object" &&
+      Array.isArray(module.commands) &&
+      module.commands.includes("jobs")
+  );
+  // Keep the historical standalone scraper fallback for brain repositories
+  // that have not moved their jobs workflow to an enabled module.
+  if (!jobsModuleEnabled && legacyScraperPresent) {
+    lines.push(
+      `0 4 * * * ${user} cd /data/brain && ${wrapper} jobs -- bun scripts/jobs/scrape-all.ts --api-only 2>&1 | logger -t brain-jobs`
+    );
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * NODE_ENV is in the descriptor because Bun uses it to choose `.env.<mode>` in
+ * every child spawned by the server. Scheduled jobs take a different path:
+ * they historically receive their environment through pam_env without
+ * NODE_ENV, and adding it would change which brain-repo env file their Bun
+ * commands load. The 0.33.1 allowlist keeps that historical behavior while
+ * widening the explicitly approved capability settings below.
+ */
+export const CRON_ENV_EXCLUSIONS: ReadonlySet<string> = new Set(["NODE_ENV"]);
+
+/**
+ * The order the shell emitted `/etc/environment` in. pam_env does not care,
+ * but the historical golden is byte-exact and this is what it is compared
+ * against.
+ *
+ * Order lives HERE, not in the SDK descriptor: the SET is owned by
+ * `SUBPROCESS_ENV`'s cron audience (see {@link CRON_ENV_NAMES}, which fails
+ * loudly if the two ever disagree), and making an unrelated file's declaration
+ * order load-bearing for a cosmetic property would be a trap for whoever next
+ * tidies it.
+ */
+const CRON_ENV_ORDER: readonly string[] = [
+  "PATH",
+  "BRAIN_PATH",
+  "BRAIN_ROOT",
+  "TZ",
+  "XDG_BIN_HOME",
+  "DB_PATH",
+  "BRAIN_RERANK_MODE",
+  "SCRAPE_CHROME_URL",
+  "CHROME_CDP_URL",
+  "SCRAPE_CHROME_PATH",
+  "SCRAPE_CHROME_NO_SANDBOX",
+  "SCRAPE_USER_AGENT",
+  "SCRAPE_RESPECT_ROBOTS",
+  "GEMINI_API_KEY",
+  "GEMINI_BASE_URL",
+  "OPENAI_API_KEY",
+  "OPENAI_BASE_URL",
+  "GITHUB_TOKEN",
+  "BRAIN_UI_SYNC_GITHUB_TOKEN",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "BRAIN_UI_PRICING_DISCOVERY",
+  "BRAIN_UI_PRICING_TTL_HOURS",
+];
+
+/**
+ * Names emitted into `/etc/environment`: the SDK's cron audience minus the
+ * explicit exclusions, in {@link CRON_ENV_ORDER}.
+ *
+ * A variable that joins or leaves the cron audience and is not accounted for
+ * here throws at module load rather than silently changing what scheduled jobs
+ * can see.
+ */
+export const CRON_ENV_NAMES = Object.freeze(
+  (() => {
+    const audience = Object.entries(SUBPROCESS_ENV)
+      .filter(([, audiences]) =>
+        (audiences as readonly SubprocessEnvAudience[]).includes("cron")
+      )
+      .map(([name]) => name)
+      .filter((name) => !CRON_ENV_EXCLUSIONS.has(name));
+    const ordered = new Set(CRON_ENV_ORDER);
+    const missing = audience.filter((name) => !ordered.has(name));
+    const extra = CRON_ENV_ORDER.filter((name) => !audience.includes(name));
+    if (missing.length > 0 || extra.length > 0) {
+      throw new Error(
+        "cron environment list drifted from SUBPROCESS_ENV's cron audience: " +
+          `unordered=[${missing.join(", ")}] unknown=[${extra.join(", ")}]`
+      );
+    }
+    return CRON_ENV_ORDER.slice();
+  })()
+);
+
+/** Emit the pam_env input consumed by scheduled jobs. */
+export function emitEnvironment(
+  env: Record<string, string | undefined>,
+  extraNames: readonly string[] = []
+): string {
+  const lines: string[] = [];
+  const names = [
+    ...CRON_ENV_NAMES,
+    ...parseSubprocessEnvExtra(extraNames.join(",")).filter(
+      (name) => !CRON_ENV_NAMES.includes(name)
+    ),
+  ];
+  for (const name of names) {
+    const value = env[name];
+    // Match the shell's `[ -n ]`: both unset and empty values are omitted.
+    if (!value) continue;
+    // /etc/environment has no shell-safe interpolation layer. Reject anything
+    // that could terminate/escape the quoted value or create another line.
+    if (/[\0"\\\r\n]/.test(value)) {
+      throw new Error(`cannot emit unsafe /etc/environment value for ${name}`);
+    }
+    lines.push(`${name}="${value}"`);
+  }
+  return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}