@zerotal/core 1.4.0 → 1.5.1

package/src/dev/DevSupervisor.ts

@@ -0,0 +1,363 @@
+/**
+ * Runs the dev processes and keeps them running.
+ *
+ * The supervisor owns lifetimes, not presentation: it spawns, watches, restarts,
+ * gives up, and reports — every line of output and every state change goes out
+ * through callbacks. The deck draws them; the stream writer prefixes them. Neither
+ * is imported here, which is what lets the whole thing be tested with a fake
+ * spawner and no terminal at all.
+ *
+ * ## One rule above the others
+ *
+ * A dev process dying must never take the server down. That is the whole
+ * difference from the build hook, where a failure aborts the reload on purpose.
+ * Here a crashed type-checker is an annoyance in one tab; if it could stop the
+ * server it would be a worse problem than the one the tab was added to solve.
+ */
+import type { ResolvedDevProcess } from "./DevProcess.ts";
+
+/** What the supervisor needs back from whatever it spawned. */
+export interface DevChild {
+  readonly stdout: ReadableStream<Uint8Array> | null;
+  readonly stderr: ReadableStream<Uint8Array> | null;
+  readonly exited: Promise<number>;
+  kill(signal?: number | NodeJS.Signals): void;
+}
+
+/** How the supervisor starts a child. Injected so tests need no real processes. */
+export type DevSpawnFn = (
+  argv: string[],
+  options: { cwd: string; env: Record<string, string | undefined> },
+) => DevChild;
+
+/** Where a process is in its life. */
+export type DevProcessState = "starting" | "running" | "restarting" | "exited" | "parked";
+
+/** A process as the deck sees it. */
+export interface DevProcessStatus {
+  name: string;
+  label: string;
+  color: ResolvedDevProcess["color"];
+  state: DevProcessState;
+  /** Exit code of the last run, when it has exited. */
+  exitCode?: number;
+  /** Consecutive failed starts. Reset once a run stays up. */
+  attempts: number;
+}
+
+/** How the supervisor reports what is happening. */
+export interface DevSupervisorHooks {
+  /** One line of a process's output. `stream` distinguishes stderr for colouring. */
+  onLine?: (name: string, line: string, stream: "stdout" | "stderr") => void;
+  /** A process changed state — repaint the tab. */
+  onState?: (status: DevProcessStatus) => void;
+}
+
+export interface DevSupervisorOptions extends DevSupervisorHooks {
+  cwd: string;
+  env?: Record<string, string | undefined>;
+  /** Defaults to `Bun.spawn` with output piped and **stdin ignored**. */
+  spawn?: DevSpawnFn;
+  /**
+   * 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[];
+  /** How long a run must last to be considered healthy. See {@link HEALTHY_AFTER_MS}. */
+  healthyAfterMs?: number;
+}
+
+/** Give up after this many consecutive failed starts. */
+const MAX_ATTEMPTS = 3;
+/** Backoff before retry N, in ms. */
+const BACKOFF_MS = [300, 900, 2_400];
+/**
+ * A run that stays up this long is treated as healthy, and the attempt counter
+ * resets. Without it a process that crashes once an hour eventually parks itself
+ * for a reason that has nothing to do with the current failure.
+ */
+const HEALTHY_AFTER_MS = 10_000;
+
+/** One supervised process's mutable state. */
+interface Entry {
+  definition: ResolvedDevProcess;
+  status: DevProcessStatus;
+  child?: DevChild | undefined;
+  abort?: AbortController | undefined;
+  /** Set while a deliberate stop or restart is in flight, so the exit is not "unexpected". */
+  stopping: boolean;
+  /** Cleared on stop so a parked retry cannot fire after shutdown. */
+  retryTimer?: ReturnType<typeof setTimeout> | undefined;
+  healthyTimer?: ReturnType<typeof setTimeout> | undefined;
+}
+
+export class DevSupervisor {
+  private readonly _entries = new Map<string, Entry>();
+  private readonly _cwd: string;
+  private readonly _env: Record<string, string | undefined>;
+  private readonly _spawn: DevSpawnFn;
+  private readonly _hooks: DevSupervisorHooks;
+  private readonly _backoff: number[];
+  private readonly _healthyAfter: number;
+  private _stopped = false;
+
+  constructor(options: DevSupervisorOptions) {
+    this._cwd = options.cwd;
+    this._env = options.env ?? { ...Bun.env };
+    this._spawn = options.spawn ?? _bunSpawn;
+    this._backoff = options.backoffMs ?? BACKOFF_MS;
+    this._healthyAfter = options.healthyAfterMs ?? HEALTHY_AFTER_MS;
+    this._hooks = {
+      ...(options.onLine && { onLine: options.onLine }),
+      ...(options.onState && { onState: options.onState }),
+    };
+  }
+
+  /** Every process currently known, in registration order. */
+  statuses(): DevProcessStatus[] {
+    return [...this._entries.values()].map((entry) => ({ ...entry.status }));
+  }
+
+  /** The definitions this supervisor was given, in registration order. */
+  definitions(): ResolvedDevProcess[] {
+    return [...this._entries.values()].map((entry) => entry.definition);
+  }
+
+  /**
+   * Start every process in `definitions`.
+   *
+   * Called twice by the orchestrator — once with the `after: "none"` set beside
+   * the first server spawn, once with `after: "server"` after it binds — so a
+   * process that talks to the server is not started against a closed port.
+   */
+  start(definitions: ResolvedDevProcess[]): void {
+    for (const definition of definitions) {
+      if (this._entries.has(definition.name)) continue;
+      const entry: Entry = {
+        definition,
+        status: {
+          name: definition.name,
+          label: definition.label,
+          color: definition.color,
+          state: "starting",
+          attempts: 0,
+        },
+        stopping: false,
+      };
+      this._entries.set(definition.name, entry);
+      this._launch(entry);
+    }
+  }
+
+  /**
+   * Restart one process by name, whatever state it is in.
+   *
+   * This is also the way out of `parked`: the attempt counter resets, because a
+   * developer asking for a restart has usually just fixed the thing that broke.
+   */
+  async restart(name: string): Promise<void> {
+    const entry = this._entries.get(name);
+    if (!entry || this._stopped) return;
+
+    entry.status.attempts = 0;
+    this._setState(entry, "restarting");
+    await this._stopEntry(entry);
+    if (this._stopped) return;
+    this._launch(entry);
+  }
+
+  /** Stop everything and stay stopped. Safe to call twice. */
+  async stopAll(): Promise<void> {
+    this._stopped = true;
+    await Promise.all([...this._entries.values()].map((entry) => this._stopEntry(entry)));
+  }
+
+  // ── Internals ──────────────────────────────────────────────────────────────
+
+  private _launch(entry: Entry): void {
+    if (this._stopped) return;
+    entry.stopping = false;
+    this._setState(entry, "starting");
+
+    const startedAt = Date.now();
+    entry.healthyTimer = setTimeout(() => {
+      entry.status.attempts = 0;
+    }, this._healthyAfter);
+
+    if (entry.definition.run) {
+      const abort = new AbortController();
+      entry.abort = abort;
+      this._setState(entry, "running");
+      void entry.definition
+        .run(abort.signal)
+        .then(() => this._onExit(entry, 0, startedAt))
+        .catch((error: unknown) => {
+          if (!abort.signal.aborted) this._emit(entry, _errorText(error), "stderr");
+          this._onExit(entry, abort.signal.aborted ? 0 : 1, startedAt);
+        });
+      return;
+    }
+
+    let child: DevChild;
+    try {
+      child = this._spawn(entry.definition.argv!, { cwd: this._cwd, env: this._env });
+    } catch (error) {
+      // A missing binary is the usual cause, and it fails every attempt
+      // identically — report it as output so the tab explains itself.
+      this._emit(entry, _errorText(error), "stderr");
+      this._onExit(entry, 1, startedAt);
+      return;
+    }
+
+    entry.child = child;
+    this._setState(entry, "running");
+    void this._pump(entry, child.stdout, "stdout");
+    void this._pump(entry, child.stderr, "stderr");
+    void child.exited.then((code) => this._onExit(entry, code, startedAt));
+  }
+
+  /**
+   * Decide what happens after a process ends.
+   *
+   * A deliberate stop reports nothing and schedules nothing — `restart()` and
+   * `stopAll()` own what comes next.
+   */
+  private _onExit(entry: Entry, code: number, startedAt: number): void {
+    if (entry.healthyTimer) clearTimeout(entry.healthyTimer);
+    entry.child = undefined;
+    entry.abort = undefined;
+    entry.status.exitCode = code;
+
+    if (entry.stopping || this._stopped) return;
+
+    // A run that lasted counts as healthy even if it then failed: the attempt
+    // budget is for start-up failure loops, not for every crash forever.
+    if (Date.now() - startedAt >= this._healthyAfter) entry.status.attempts = 0;
+
+    const policy = entry.definition.restart;
+    const shouldRestart = policy === "always" || (policy === "on-failure" && code !== 0);
+
+    if (!shouldRestart) {
+      this._setState(entry, "exited");
+      return;
+    }
+
+    entry.status.attempts += 1;
+    if (entry.status.attempts >= MAX_ATTEMPTS) {
+      this._setState(entry, "parked");
+      this._emit(
+        entry,
+        `[zerotal:dev] "${entry.definition.name}" failed ${MAX_ATTEMPTS} times — parked. ` +
+          `Press r with this tab focused to retry, or run \`bun zt dev --only=${entry.definition.name}\`.`,
+        "stderr",
+      );
+      return;
+    }
+
+    const delay = this._backoff[entry.status.attempts - 1] ?? this._backoff.at(-1)!;
+    this._setState(entry, "restarting");
+    entry.retryTimer = setTimeout(() => {
+      entry.retryTimer = undefined;
+      this._launch(entry);
+    }, delay);
+  }
+
+  /** Stop one process and wait for it to actually be gone. */
+  private async _stopEntry(entry: Entry): Promise<void> {
+    entry.stopping = true;
+    if (entry.retryTimer) {
+      clearTimeout(entry.retryTimer);
+      entry.retryTimer = undefined;
+    }
+    if (entry.healthyTimer) clearTimeout(entry.healthyTimer);
+
+    entry.abort?.abort();
+
+    const child = entry.child;
+    if (child) {
+      child.kill("SIGTERM");
+      // A child ignoring SIGTERM would otherwise hold the whole quit open, and a
+      // developer pressing q expects their shell back.
+      const force = setTimeout(() => child.kill("SIGKILL"), 1_500);
+      try {
+        await child.exited;
+      } catch {
+        // Already gone.
+      } finally {
+        clearTimeout(force);
+      }
+    }
+
+    entry.child = undefined;
+    entry.abort = undefined;
+  }
+
+  /** Split a piped stream into lines and hand each one to the hook. */
+  private async _pump(
+    entry: Entry,
+    stream: ReadableStream<Uint8Array> | null,
+    kind: "stdout" | "stderr",
+  ): Promise<void> {
+    if (!stream) return;
+    const decoder = new TextDecoder();
+    // A reader rather than `for await`: async iteration on a ReadableStream is a
+    // runtime extension Bun has and the DOM types do not, and reaching for a cast
+    // to paper over that would hide a real portability question.
+    const reader = stream.getReader();
+    let buffered = "";
+
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffered += decoder.decode(value, { stream: true });
+        const lines = buffered.split("\n");
+        // The last element is whatever came after the final newline — a partial
+        // line that must wait for the next chunk rather than being emitted as a
+        // short one, which is how progress bars end up shredded across tabs.
+        buffered = lines.pop() ?? "";
+        for (const line of lines) this._emit(entry, line.replace(/\r$/, ""), kind);
+      }
+    } catch {
+      // The stream closes under us when the process is killed; that is the
+      // normal end of a pump, not a failure worth reporting.
+    }
+
+    if (buffered) this._emit(entry, buffered, kind);
+  }
+
+  private _emit(entry: Entry, line: string, kind: "stdout" | "stderr"): void {
+    this._hooks.onLine?.(entry.definition.name, line, kind);
+  }
+
+  private _setState(entry: Entry, state: DevProcessState): void {
+    entry.status.state = state;
+    this._hooks.onState?.({ ...entry.status });
+  }
+}
+
+/**
+ * The real spawner.
+ *
+ * `stdin: "ignore"` is not a detail. The dev worker reads stdin for reload
+ * signals from the orchestrator, and a second process holding a claim on the
+ * same terminal input makes that behaviour undebuggable — the reload silently
+ * goes to whoever won.
+ */
+function _bunSpawn(
+  argv: string[],
+  options: { cwd: string; env: Record<string, string | undefined> },
+): DevChild {
+  return Bun.spawn(argv, {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    cwd: options.cwd,
+    env: options.env,
+  });
+}
+
+function _errorText(error: unknown): string {
+  return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}

package/src/dev/bootBuild.ts

@@ -0,0 +1,94 @@
+/**
+ * Whether an asset bundle should be built as part of starting the server.
+ *
+ * `serve` rebuilds the frontend bundle at boot rather than trusting what was shipped,
+ * which is right in development and load-bearing in production for the wrong reason: it
+ * makes the server process require write access to its own output directory. A unit
+ * hardened the way a unit should be —
+ *
+ *     ProtectSystem=strict
+ *     ReadWritePaths=/opt/app/database /opt/app/storage
+ *
+ * — then fails at startup with `Read-only file system: writing chunk "./app.css"`, and
+ * restart-loops. The logs blame the filesystem rather than the boot-time build that made
+ * it a problem, so the fix looks like "grant more write access" when it should be "stop
+ * writing at boot".
+ *
+ * The policy here: in production, build only if the output directory is actually
+ * writable. A read-only output directory is a deployment that built its assets ahead of
+ * time and locked the tree down, which is the correct shape — so it is honoured with one
+ * log line rather than a crash. Everywhere else, and anywhere the directory is writable,
+ * behaviour is exactly as before.
+ */
+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. */
+export interface BootBuildDecision {
+  /** Whether to run the build. */
+  build: boolean;
+  /** Single-line explanation of a skip, worth logging. Absent when building. */
+  reason?: string;
+}
+
+/**
+ * Whether a directory can be written to, creating it if absent.
+ *
+ * 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.
+ */
+export async function isWritableDir(dir: string): Promise<boolean> {
+  const probe = `${dir}/.zerotal-write-probe-${process.pid}`;
+  try {
+    await mkdir(dir, { recursive: true });
+    await writeFile(probe, "");
+  } catch {
+    return false;
+  }
+  // Best-effort cleanup: the probe is already proof of writability, and failing to remove
+  // it should not turn a writable directory into an unwritable one.
+  try {
+    await unlink(probe);
+  } catch {
+    /* empty */
+  }
+  return true;
+}
+
+/**
+ * Decide whether to build the given output directories at boot.
+ *
+ * @param outDirs - Absolute paths the build writes into.
+ * @param env - The resolved `app.env` (or `APP_ENV`).
+ *
+ * @example
+ * ```ts
+ * const decision = await bootBuildDecision([`${cwd}/public/css`], config('app.env'));
+ * if (!decision.build) console.info(decision.reason);
+ * else await build();
+ * ```
+ */
+export async function bootBuildDecision(
+  outDirs: string[],
+  env: string | undefined,
+): Promise<BootBuildDecision> {
+  // `isProdLike` — so `staging` gets the same treatment. A staging box is hardened
+  // like a production one, and used to build at boot regardless of whether its output
+  // directory was writable: the one environment where the read-only crash was still
+  // reachable.
+  if (!isProdLike(env ?? "")) return { build: true };
+
+  const unwritable: string[] = [];
+  for (const dir of outDirs) {
+    if (!(await isWritableDir(dir))) unwritable.push(dir);
+  }
+  if (unwritable.length === 0) return { build: true };
+
+  return {
+    build: false,
+    reason:
+      `skipping the boot-time asset build: ${unwritable.join(", ")} is not writable. ` +
+      `Serving what was shipped — build assets at deploy time, before the process starts.`,
+  };
+}

package/src/dev/index.ts

@@ -9,6 +9,23 @@
  * @packageDocumentation
  */
 export { registerDevBuildHook } from "./DevBuildHook.ts";
+// The dev-process registry and its runners. The definition *types* are on the
+// main barrel (a provider's `devProcesses()` signature needs to name them);
+// everything that runs them is here, with the rest of the dev-server wiring.
+export { collectDevProcesses } from "./DevProcess.ts";
+export { DevSupervisor } from "./DevSupervisor.ts";
+export type {
+  DevChild,
+  DevSpawnFn,
+  DevProcessState,
+  DevProcessStatus,
+  DevSupervisorOptions,
+} from "./DevSupervisor.ts";
+export { createDeck, StreamDeck, TabsDeck } from "./DevDeck.ts";
+export type { Deck, DeckOptions } from "./DevDeck.ts";
+export { startDevMode, SERVER_PROCESS_NAME } from "./startDevMode.ts";
+export { DevOrchestrator } from "./DevOrchestrator.ts";
+export type { DevOrchestratorHooks } from "./DevOrchestrator.ts";
 export type { BuildHookFn, BuildResult } from "./DevBuildHook.ts";
 export { DevReloadMiddleware, registerDevHtmlSnippet } from "./DevReloadMiddleware.ts";
 export type { DevHtmlSnippet } from "./DevReloadMiddleware.ts";
@@ -16,4 +33,11 @@ export { DEV_RELOAD_CLIENT } from "./reloadClient.ts";
 export { detectCssPlugins, buildCssBundle, buildJsBundle } from "./CssPlugins.ts";
 export type { AssetBuildConfig } from "./CssPlugins.ts";
 export { pruneBuildOutput } 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";
+export type { BootBuildDecision } from "./bootBuild.ts";
+// Lets a view provider skip its own boot-time build when the orchestrator is
+// already driving builds through the hook above.
+export { isDevOrchestrated } from "../support/env.ts";
 // `AppAssetsConfig` (the app-level assets config shape) lives on @zerotal/core/config.

package/src/dev/startDevMode.ts

@@ -0,0 +1,145 @@
+/**
+ * What `bun zt dev` and `bun zt serve --dev` both run.
+ *
+ * One entry point on purpose. The two commands differ only in their flags —
+ * `dev` adds the deck controls — and a second copy of this wiring is how they
+ * would quietly stop agreeing about what dev mode consists of.
+ *
+ * The pieces it joins up:
+ *
+ * - `collectDevProcesses` asks the booted app what to run.
+ * - {@link DevSupervisor} runs it and keeps it running.
+ * - `createDeck` draws it, in tabs or as a prefixed stream.
+ * - {@link DevOrchestrator} owns the server and the file watcher, as before.
+ *
+ * The server is a card in the deck like any other, which is what makes
+ * `--only=server` mean something and lets its tab show `restarting` on a save.
+ */
+import { DevOrchestrator } from "./DevOrchestrator.ts";
+import { DevSupervisor } from "./DevSupervisor.ts";
+import type { DevProcessStatus } from "./DevSupervisor.ts";
+import { createDeck } from "./DevDeck.ts";
+import type { ResolvedDevProcess } from "./DevProcess.ts";
+import type { BuildHookFn } from "./DevBuildHook.ts";
+import type { OutputWriter } from "../command/OutputWriter.ts";
+
+export interface StartDevModeOptions {
+  port: number;
+  cwd: string;
+  /**
+   * The asset build. Optional because a run with no server has nothing to build
+   * and nothing to serve it to — `--only=queue` is supervision and a deck, and
+   * the orchestrator that would call this never starts.
+   */
+  build?: BuildHookFn;
+  /** Everything the providers and the app contributed, already filtered. */
+  processes: ResolvedDevProcess[];
+  writer: OutputWriter;
+  /** Force a renderer; omitted means tabs on a TTY, stream otherwise. */
+  deckMode?: "tabs" | "stream" | undefined;
+}
+
+/** The server's card. Named so `--only=server` and `--without=server` read naturally. */
+export const SERVER_PROCESS_NAME = "server";
+
+/**
+ * Run dev mode until the process is signalled.
+ *
+ * Never returns: the orchestrator parks on an unresolved promise and the exit
+ * happens in its signal handlers, after the deck has restored the terminal.
+ */
+export async function startDevMode(options: StartDevModeOptions): Promise<void> {
+  const supervised = options.processes.filter((entry) => entry.name !== SERVER_PROCESS_NAME);
+  const wantsServer = options.processes.some((entry) => entry.name === SERVER_PROCESS_NAME);
+
+  // The server's card is synthesised rather than registered, because the
+  // orchestrator — not the supervisor — owns its lifetime. It still gets a tab,
+  // a colour and a state, so from the deck's side it is one of the crowd.
+  const serverStatus: DevProcessStatus = {
+    name: SERVER_PROCESS_NAME,
+    label: SERVER_PROCESS_NAME,
+    color: "green",
+    state: "starting",
+    attempts: 0,
+  };
+
+  // Declared before the three objects that reference each other in a cycle: the
+  // deck's key handlers call the supervisor, the supervisor's output callbacks
+  // call the deck. Every one of them fires from a later turn of the event loop,
+  // by which point all three are assigned.
+  // eslint-disable-next-line prefer-const -- assigned below; the deck closes over both
+  let supervisor: DevSupervisor;
+  // eslint-disable-next-line prefer-const -- assigned below; the deck closes over both
+  let orchestrator: DevOrchestrator;
+
+  const deck = createDeck({
+    writer: options.writer,
+    ...(options.deckMode ? { mode: options.deckMode } : {}),
+    onRestart: (name) => {
+      // The server restarts through the orchestrator, which also rebuilds
+      // assets — restarting it any other way would leave the browser holding
+      // bundles from before whatever the developer just fixed.
+      if (name === SERVER_PROCESS_NAME) void orchestrator.restartServer();
+      else void supervisor.restart(name);
+    },
+    onQuit: () => void orchestrator.shutdown(),
+  });
+
+  supervisor = new DevSupervisor({
+    cwd: options.cwd,
+    onLine: (name, line, stream) => deck.line(name, line, stream),
+    onState: (status) => deck.state(status),
+  });
+
+  const build: BuildHookFn =
+    options.build ?? ((): Promise<{ success: boolean }> => Promise.resolve({ success: true }));
+
+  orchestrator = new DevOrchestrator(options.port, options.cwd, build, {
+    ...(wantsServer
+      ? {
+          onServerLine: (line, stream) => deck.line(SERVER_PROCESS_NAME, line, stream),
+          onServerState: (state) => {
+            serverStatus.state = state;
+            deck.state({ ...serverStatus });
+          },
+        }
+      : {}),
+    onNotice: (text) => deck.notice(text.trim()),
+    onServerReady: () => {
+      supervisor.start(supervised.filter((entry) => entry.after === "server"));
+    },
+    onCleanup: async () => {
+      await supervisor.stopAll();
+      deck.stop();
+    },
+  });
+
+  // Cards exist before anything can write to them, so early output has a tab to
+  // land in rather than being dropped for want of one.
+  deck.start([...(wantsServer ? [serverStatus] : []), ...supervised.map(_toStatus)]);
+
+  // Started before the server rather than after it: these declared they do not
+  // depend on it, and making them wait for a build they have nothing to do with
+  // is dead time on every boot.
+  supervisor.start(supervised.filter((entry) => entry.after === "none"));
+
+  if (!wantsServer) {
+    // `--only=queue`, say — supervised and drawn, with no server underneath.
+    // Still parks forever: quitting goes through the deck like everywhere else.
+    await new Promise<never>(() => {});
+    return;
+  }
+
+  await orchestrator.start();
+}
+
+/** The card a process starts life with, before the supervisor has run it. */
+function _toStatus(process: ResolvedDevProcess): DevProcessStatus {
+  return {
+    name: process.name,
+    label: process.label,
+    color: process.color,
+    state: "starting",
+    attempts: 0,
+  };
+}