@zerotal/core 1.3.0 → 1.5.0

package/src/dev/DevOrchestrator.ts

@@ -6,6 +6,31 @@ import { watch } from "node:fs";
 import type { BuildHookFn } from "./DevBuildHook.ts";
 import { DEV_WORKER_ENV_VAR } from "../support/env.ts";
 
+/**
+ * How the orchestrator reports to whatever is presenting dev mode.
+ *
+ * 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.
+ */
+export interface DevOrchestratorHooks {
+  /**
+   * Take the server's output instead of letting it inherit the terminal.
+   *
+   * Providing this is what turns the server into a card in the deck rather than
+   * a process shouting over the tab bar.
+   */
+  onServerLine?: (line: string, stream: "stdout" | "stderr") => void;
+  /** The server's own lifecycle, so its tab can show state like any other. */
+  onServerState?: (state: "starting" | "running" | "restarting" | "parked") => void;
+  /** Dev-mode's own narration — rebuilds, restarts, failures. */
+  onNotice?: (text: string, level: "info" | "warn" | "error") => void;
+  /** Called once the first server has bound, for `after: "server"` processes. */
+  onServerReady?: () => void | Promise<void>;
+  /** Called on SIGINT/SIGTERM, before the process exits. */
+  onCleanup?: () => void | Promise<void>;
+}
+
 /**
  * Dev Orchestrator — Process 1 of the two-process dev mode.
  *
@@ -73,33 +98,64 @@ export class DevOrchestrator {
     private readonly _port: number,
     private readonly _cwd: string,
     private readonly _build: BuildHookFn,
+    private readonly _hooks: DevOrchestratorHooks = {},
   ) {}
 
   async start(): Promise<void> {
-    console.log("  [zerotal:dev] ⚙  building assets...");
-    const buildSucceeded = await this._runBuild();
-    if (!buildSucceeded) {
-      console.warn("  [zerotal:dev] ⚠  initial build failed — starting server anyway");
+    this._say("  [zerotal:dev] ⚙  building assets...");
+    const started = Bun.nanoseconds();
+    const build = await this._runBuild();
+
+    if (!build.ok) {
+      this._say("  [zerotal:dev] ⚠  initial build failed — starting server anyway", "warn");
+    } else if (build.skipped) {
+      // Said out loud on purpose. A boot that prints "building assets…" and then
+      // nothing looks like a hang, and a developer who cannot tell a skip from a
+      // stall deletes `.zerotal/` and stops trusting the cache.
+      this._say(`  [zerotal:dev] ✓  assets unchanged — reused the last build (${_ms(started)})`);
     }
 
     // Same retry as a restart: the commonest reason the first bind fails is an orphaned
     // server from a previous run that has not finished exiting.
     await this._spawnServerWithRetry();
+
+    // Only now are `after: "server"` processes started — a process that talks to
+    // the server would otherwise spend its first attempts against a closed port
+    // and burn its restart budget before the server ever bound.
+    await this._hooks.onServerReady?.();
+
     this._watch();
 
     // Park the process — cleanup happens in signal handlers registered by _watch()
     await new Promise<never>(() => {});
   }
 
+  /** Narrate, through the deck when one is present and the console otherwise. */
+  private _say(text: string, level: "info" | "warn" | "error" = "info"): void {
+    if (this._hooks.onNotice) {
+      this._hooks.onNotice(text, level);
+      return;
+    }
+    if (level === "error") console.error(text);
+    else if (level === "warn") console.warn(text);
+    else console.log(text);
+  }
+
   // ── Server management ──────────────────────────────────────────────────────
 
   private _spawnServer(): ReturnType<typeof Bun.spawn> {
+    // Piped only when something is listening. Left inherited otherwise, so the
+    // server writes straight to the terminal exactly as it always has — routing
+    // it through a hook that discards would be how dev mode goes silent.
+    const routed = this._hooks.onServerLine !== undefined;
+    this._hooks.onServerState?.("starting");
+
     const child = Bun.spawn(
       ["bun", Bun.main, "serve", "--port", String(this._port), "--dev-worker"],
       {
         stdin: "pipe",
-        stdout: "inherit",
-        stderr: "inherit",
+        stdout: routed ? "pipe" : "inherit",
+        stderr: routed ? "pipe" : "inherit",
         cwd: this._cwd,
         env: {
           ...Bun.env,
@@ -116,19 +172,62 @@ export class DevOrchestrator {
 
     this._child = child;
 
+    if (routed) {
+      void this._pipe(child.stdout as ReadableStream<Uint8Array>, "stdout");
+      void this._pipe(child.stderr as ReadableStream<Uint8Array>, "stderr");
+    }
+
     void child.exited.then((code) => {
       // Report only the *current* server dying unexpectedly. Comparing against
       // `this._child` identity matters: reading the field alone reported an exit that a
       // restart had deliberately caused, because by then the field held the replacement.
       // A restart in flight owns its own reporting.
       if (this._child === child && this._restartInFlight === null && code !== 0) {
-        console.log(`  [zerotal:dev] server exited with code ${code}`);
+        this._say(`  [zerotal:dev] server exited with code ${code}`);
+        this._hooks.onServerState?.("parked");
       }
     });
 
     return child;
   }
 
+  /** Split the server child's piped output into lines and hand them to the deck. */
+  private async _pipe(
+    stream: ReadableStream<Uint8Array> | null,
+    kind: "stdout" | "stderr",
+  ): Promise<void> {
+    if (!stream) return;
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffered = "";
+
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffered += decoder.decode(value, { stream: true });
+        const lines = buffered.split("\n");
+        buffered = lines.pop() ?? "";
+        for (const line of lines) this._hooks.onServerLine?.(line.replace(/\r$/, ""), kind);
+      }
+    } catch {
+      // The stream ends when the server is replaced — the normal case on every
+      // restart, not something to report.
+    }
+
+    if (buffered) this._hooks.onServerLine?.(buffered, kind);
+  }
+
+  /**
+   * Restart the server on request — the deck's `r` key on the server tab.
+   *
+   * Goes through the same path a file change takes, so it rebuilds assets first
+   * and folds into a restart already running rather than racing it for the port.
+   */
+  restartServer(): Promise<void> {
+    return this._requestRestart();
+  }
+
   private _scheduleRestart(): void {
     if (this._restartTimer) clearTimeout(this._restartTimer);
     this._restartTimer = setTimeout(() => {
@@ -168,7 +267,8 @@ export class DevOrchestrator {
   }
 
   private async _restartOnce(): Promise<void> {
-    console.log("  [zerotal:dev] ↻  backend change — rebuilding + restarting server...");
+    this._say("  [zerotal:dev] ↻  backend change — rebuilding + restarting server...");
+    this._hooks.onServerState?.("restarting");
 
     // Rebuild assets before respawning: server-rendered views (Flow pages in `app/`,
     // controllers returning markup) contain Tailwind classes the stylesheet scans via
@@ -216,7 +316,10 @@ export class DevOrchestrator {
         Bun.sleep(DevOrchestrator.BIND_SETTLE_MS).then(() => false),
       ]);
 
-      if (!settled) return; // still running → it bound the port
+      if (!settled) {
+        this._hooks.onServerState?.("running"); // still running → it bound the port
+        return;
+      }
       if (this._child !== child) return; // superseded by a newer restart
 
       this._child = null;
@@ -225,10 +328,12 @@ export class DevOrchestrator {
       }
     }
 
-    console.error(
+    this._hooks.onServerState?.("parked");
+    this._say(
       `  [zerotal:dev] ✗  server did not start after ${DevOrchestrator.RESPAWN_ATTEMPTS} attempts.\n` +
         `     Port ${this._port} may be held by another process — the error above says which.\n` +
         `     Dev mode is still watching; fix the cause and save to retry.`,
+      "error",
     );
   }
 
@@ -239,32 +344,43 @@ export class DevOrchestrator {
     this._buildTimer = setTimeout(async () => {
       this._buildTimer = null;
       const label = path.startsWith("resources/pages/") ? "page" : "asset";
-      console.log(`  [zerotal:dev] ⚙  ${label} changed — rebuilding...`);
-
-      const buildSucceeded = await this._runBuild();
-      if (buildSucceeded) {
-        console.log("  [zerotal:dev] ✓  ready — reloading browser");
+      this._say(`  [zerotal:dev] ⚙  ${label} changed — rebuilding...`);
+
+      const build = await this._runBuild();
+      if (build.ok) {
+        // Still reload on a skip: the change that triggered this may have been
+        // to a file the bundles do not contain (a server-rendered template),
+        // and the browser has no other way to learn about it.
+        this._say(
+          build.skipped
+            ? "  [zerotal:dev] ✓  bundles unchanged — reloading browser"
+            : "  [zerotal:dev] ✓  ready — reloading browser",
+        );
         this._signalReload();
       }
     }, 80);
   }
 
-  private async _runBuild(): Promise<boolean> {
+  private async _runBuild(): Promise<{ ok: boolean; skipped: boolean }> {
     try {
       const result = await this._build();
       if (!result.success) {
-        console.error("  [zerotal:dev] ✗  build failed:");
+        this._say("  [zerotal:dev] ✗  build failed:", "error");
         for (const entry of result.logs ?? []) {
-          console.error("    ", String(entry));
+          this._say(`     ${String(entry)}`, "error");
         }
-        return false;
+        return { ok: false, skipped: false };
       }
-      // Fresh token so the next `asset()` URL changes and the browser refetches.
-      this._assetVersion = Date.now().toString(36);
-      return true;
+
+      // A skipped build wrote nothing, so the files the browser already holds
+      // are still current — bumping the token would force a pointless refetch
+      // of every asset on the page.
+      if (result.skipped !== true) this._assetVersion = Date.now().toString(36);
+
+      return { ok: true, skipped: result.skipped === true };
     } catch (error) {
-      console.error("  [zerotal:dev] ✗  build error:", error);
-      return false;
+      this._say(`  [zerotal:dev] ✗  build error: ${String(error)}`, "error");
+      return { ok: false, skipped: false };
     }
   }
 
@@ -306,13 +422,32 @@ export class DevOrchestrator {
       }
     });
 
-    const cleanup = () => {
-      watcher.close();
-      this._child?.kill("SIGTERM");
-      process.exit(0);
-    };
+    process.on("SIGTERM", () => void this.shutdown(watcher));
+    process.on("SIGINT", () => void this.shutdown(watcher));
+  }
 
-    process.on("SIGTERM", cleanup);
-    process.on("SIGINT", cleanup);
+  /**
+   * Stop everything dev mode owns, then exit.
+   *
+   * `onCleanup` runs *before* the exit and is awaited, because it is what stops
+   * the supervised processes and hands the terminal back. Exiting first would
+   * leave orphaned children and a shell in raw mode — the bug this ordering
+   * exists to prevent.
+   */
+  async shutdown(watcher?: { close(): void }): Promise<never> {
+    watcher?.close();
+    try {
+      await this._hooks.onCleanup?.();
+    } catch {
+      // A failing cleanup must not stop the rest of the shutdown; whatever it
+      // could not release, exiting releases anyway.
+    }
+    this._child?.kill("SIGTERM");
+    process.exit(0);
   }
 }
+
+/** Elapsed time since a `Bun.nanoseconds()` reading, as `"12ms"`. */
+function _ms(since: number): string {
+  return `${Math.round((Bun.nanoseconds() - since) / 1e6)}ms`;
+}

package/src/dev/DevProcess.ts

@@ -0,0 +1,221 @@
+/**
+ * The dev-process registry: what `bun zt dev` runs alongside the server.
+ *
+ * An app with a queue needs a worker running next to its server, and today that
+ * is a second terminal the developer has to remember to restart by hand. Every
+ * package with a companion process has the same gap — a type-checker, a Stripe
+ * listener, a Tailwind watcher — and until now there was no way for a package to
+ * close it, because the dev runner only knew about the server.
+ *
+ * A provider contributes one by overriding `devProcesses()`, the same shape as
+ * `replContext()`: the package declares what it needs, the tooling decides what
+ * to do with it.
+ *
+ * ## Why this is not the build hook
+ *
+ * `registerDevBuildHook` exists for *builds*, and a build is a step that has to
+ * finish before the server restarts — a failure there aborts the reload, which is
+ * correct, because serving a page against a half-built bundle is worse than not
+ * reloading. A process is the opposite: it runs for as long as dev mode does, and
+ * its death must never take the server with it. Two different lifetimes, two
+ * different failure rules, two different mechanisms.
+ */
+import type { ServiceProvider } from "../provider/ServiceProvider.ts";
+
+/** What a provider or an app declares when it contributes a dev process. */
+export interface DevProcessDefinition {
+  /**
+   * Stable identity, and what the user types in `--only` / `--without`.
+   *
+   * Registering a name twice replaces the earlier definition rather than adding
+   * a second entry, so an app can swap out a provider's worker for its own.
+   */
+  name: string;
+  /**
+   * What to run, in one of three forms:
+   *
+   * - `"queue:work"` — a bare string is a `zt` command, resolved against the
+   *   app's own entrypoint, so it picks up the same bootstrap the CLI does.
+   * - `["stripe", "listen"]` — raw argv, for a tool that is not a zt command.
+   * - `() => [...]` — the same, computed at startup when the argv depends on
+   *   config the provider can only read once the app has booted.
+   *
+   * Mutually exclusive with {@link run}.
+   */
+  command?: string | string[] | (() => string[]);
+  /**
+   * Run in-process instead of spawning, for work that has no separate binary.
+   * The signal aborts on shutdown and on a restart.
+   *
+   * Mutually exclusive with {@link command}.
+   */
+  run?: (signal: AbortSignal) => Promise<void>;
+  /**
+   * Whether to run at all. A function is resolved **once**, at startup, so a
+   * provider can consult its own config — and so a process cannot flicker in
+   * and out of the deck while dev mode is running.
+   */
+  enabled?: boolean | (() => boolean | Promise<boolean>);
+  /** Restart policy. Defaults to `"on-failure"`. */
+  restart?: "always" | "on-failure" | "never";
+  /**
+   * `"server"` waits for the server to be up before starting — for a process
+   * that talks to it. Defaults to `"none"`, which starts immediately.
+   */
+  after?: "server" | "none";
+  /** Display name for the tab. Defaults to {@link name}. */
+  label?: string;
+  /** Tab colour. Auto-assigned from the palette when omitted. */
+  color?: DevProcessColor;
+}
+
+/** The colours a deck tab can take. Named, not ANSI codes, so the deck owns the rendering. */
+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. */
+export interface ResolvedDevProcess {
+  name: string;
+  label: string;
+  color: DevProcessColor;
+  /** Settled argv, when this is a spawned process. */
+  argv?: string[];
+  /** The in-process body, when this is a `run` process. */
+  run?: (signal: AbortSignal) => Promise<void>;
+  restart: "always" | "on-failure" | "never";
+  after: "server" | "none";
+  /**
+   * Who registered it — a provider class name, or `"app.dev.processes"`.
+   *
+   * Kept so `zt dev --list` can answer "why is this running?", which is the
+   * question a developer actually has when an unfamiliar tab appears.
+   */
+  registrant: string;
+}
+
+/** The `app.dev` config block. */
+export interface DevConfigShape {
+  /** App-level processes, registered after every provider's. */
+  processes?: DevProcessDefinition[];
+  /** Names to drop, whoever registered them. */
+  disable?: string[];
+}
+
+/** The bits of `Application` this module needs — kept structural to avoid a cycle. */
+interface ProviderHost {
+  _activeProviders: ServiceProvider[];
+}
+
+/** The bits of `ConfigManager` this module needs. */
+interface ConfigReader {
+  get<T>(key: string, fallback?: T): T | undefined;
+}
+
+/**
+ * Gather every dev process the booted app has to offer.
+ *
+ * Collection order is providers in boot order, then `app.dev.processes`, so an
+ * app always gets the last word. Name collisions replace in place rather than
+ * appending, which keeps the deck's tab order stable when an app overrides one.
+ *
+ * @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`.
+ */
+export async function collectDevProcesses(
+  app: ProviderHost,
+  config?: ConfigReader,
+): Promise<ResolvedDevProcess[]> {
+  const devConfig = config?.get<DevConfigShape>("app.dev") ?? {};
+  const declared = new Map<string, { definition: DevProcessDefinition; registrant: string }>();
+
+  for (const provider of app._activeProviders) {
+    const contributed = provider.devProcesses?.() ?? [];
+    const registrant = provider.constructor.name;
+    for (const definition of contributed) {
+      _assertShape(definition, registrant);
+      declared.set(definition.name, { definition, registrant });
+    }
+  }
+
+  for (const definition of devConfig.processes ?? []) {
+    _assertShape(definition, "app.dev.processes");
+    declared.set(definition.name, { definition, registrant: "app.dev.processes" });
+  }
+
+  const disabled = new Set(devConfig.disable ?? []);
+  const resolved: ResolvedDevProcess[] = [];
+  let paletteIndex = 0;
+
+  for (const { definition, registrant } of declared.values()) {
+    if (disabled.has(definition.name)) continue;
+    if (!(await _isEnabled(definition))) continue;
+
+    // Consumed only by processes that survived the filters, so removing one
+    // does not re-colour the others.
+    const color = definition.color ?? _PALETTE[paletteIndex++ % _PALETTE.length]!;
+
+    resolved.push({
+      name: definition.name,
+      label: definition.label ?? definition.name,
+      color,
+      ...(definition.command !== undefined ? { argv: _toArgv(definition.command) } : {}),
+      ...(definition.run !== undefined ? { run: definition.run } : {}),
+      restart: definition.restart ?? "on-failure",
+      after: definition.after ?? "none",
+      registrant,
+    });
+  }
+
+  return resolved;
+}
+
+/**
+ * Reject a definition that cannot be run, naming who registered it.
+ *
+ * Both errors are authoring mistakes in a provider the developer may not own, so
+ * the message has to say which package to go and look at.
+ */
+function _assertShape(definition: DevProcessDefinition, registrant: string): void {
+  if (!definition.name) {
+    throw new Error(`[Zerotal] ${registrant} registered a dev process with no name.`);
+  }
+  const hasCommand = definition.command !== undefined;
+  const hasRun = definition.run !== undefined;
+  if (hasCommand === hasRun) {
+    throw new Error(
+      `[Zerotal] Dev process "${definition.name}" (from ${registrant}) must set exactly one of ` +
+        `\`command\` or \`run\`, not ${hasCommand ? "both" : "neither"}.`,
+    );
+  }
+}
+
+/** Resolve `enabled` once. Anything that throws is treated as "not enabled". */
+async function _isEnabled(definition: DevProcessDefinition): Promise<boolean> {
+  const enabled = definition.enabled;
+  if (enabled === undefined) return true;
+  if (typeof enabled !== "function") return enabled;
+  try {
+    return await enabled();
+  } catch {
+    // A provider probing config that is absent should leave its process out,
+    // not fail dev mode for every other process in the deck.
+    return false;
+  }
+}
+
+/**
+ * Settle a `command` into argv.
+ *
+ * A bare string is a zt command and runs through `Bun.main` — the app's own
+ * entrypoint — so it boots the same providers and reads the same config the
+ * developer's `bun zt queue:work` would. Splitting on whitespace is deliberate
+ * and shallow: anything needing quoting should use the array form.
+ */
+function _toArgv(command: string | string[] | (() => string[])): string[] {
+  if (typeof command === "function") return command();
+  if (Array.isArray(command)) return command;
+  return ["bun", Bun.main, ...command.split(/\s+/).filter(Boolean)];
+}

package/src/dev/DevReloadMiddleware.ts

@@ -61,7 +61,7 @@ export function setDevReloadClientActive(active: boolean): void {
 }
 
 export class DevReloadMiddleware extends BaseMiddleware {
-  protected options: {} = {};
+  protected options: Record<string, never> = {};
 
   async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
     const res = await next();