@zerotal/core 1.0.0

package/src/dev/CssPlugins.ts

@@ -0,0 +1,184 @@
+/**
+ * Asset-build helpers for dev mode: detecting the app's Tailwind plugin and
+ * bundling CSS and JavaScript entry points with Bun's native bundler (falling
+ * back to the Tailwind CLI when the plugin is absent).
+ */
+import type { BunPlugin } from "bun";
+import { pruneBuildOutput } from "./BuildOutput.ts";
+
+/**
+ * Detect and load `bun-plugin-tailwind` from the app's own node_modules.
+ *
+ * Bun ships first-class CSS support and `bun-plugin-tailwind` handles
+ * Tailwind v4 natively — no PostCSS or @tailwindcss/postcss needed.
+ * Apps only need:
+ *
+ *   bun add -d bun-plugin-tailwind
+ *
+ * Packages are resolved from the project CWD (not from @zerotal/core) so the
+ * plugin only needs to be in the app's own node_modules.
+ *
+ * Returns an empty array when `bun-plugin-tailwind` is not installed.
+ * The caller falls back to a `bunx @tailwindcss/cli` subprocess.
+ */
+export async function detectCssPlugins(cwd: string): Promise<BunPlugin[]> {
+  try {
+    const pluginPath = Bun.resolveSync("bun-plugin-tailwind", cwd);
+    const module = (await import(pluginPath)) as { default: BunPlugin };
+    return [module.default];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Build a CSS entry point using the Tailwind PostCSS plugin.
+ *
+ * Used by PulseProvider and ViewProvider to register a dev build hook
+ * for CSS-only apps (no JS bundle required).
+ *
+ * @param input   Absolute path to the CSS source (e.g. `${cwd}/resources/css/app.css`)
+ * @param outdir  Absolute path to the output directory (e.g. `${cwd}/public/css`)
+ * @param minify  Whether to minify the output (true in production)
+ */
+export async function buildCssBundle(
+  input: string,
+  outdir: string,
+  minify = false,
+): Promise<{ success: boolean; logs: unknown[] }> {
+  const cwd = process.cwd();
+  const plugins = await detectCssPlugins(cwd);
+
+  if (plugins.length > 0) {
+    // bun-plugin-tailwind is available — use Bun's native CSS bundler
+    return Bun.build({
+      entrypoints: [input],
+      outdir,
+      target: "browser",
+      minify,
+      plugins,
+    });
+  }
+
+  // Fallback: run the Tailwind CLI as a subprocess
+  // Works with just `tailwindcss` installed (no postcss needed).
+  try {
+    const outputFile = `${outdir}/${_basename(input)}`;
+    const commandArgs = [
+      "bun",
+      "x",
+      "--bun",
+      "@tailwindcss/cli",
+      "-i",
+      input,
+      "-o",
+      outputFile,
+      ...(minify ? ["--minify"] : []),
+    ];
+
+    const subprocess = Bun.spawn(commandArgs, {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const [exitCode, stderr] = await Promise.all([
+      subprocess.exited,
+      new Response(subprocess.stderr).text(),
+    ]);
+
+    return {
+      success: exitCode === 0,
+      logs: exitCode !== 0 ? [stderr] : [],
+    };
+  } catch (error) {
+    return { success: false, logs: [error] };
+  }
+}
+
+/**
+ * Bundle a JavaScript entry point for the browser using Bun's native bundler.
+ *
+ * Used by FlowProvider to bundle `resources/js/app.js` → `public/js/app.js`.
+ * Workspace package imports (e.g. `@zerotal/devtools/client`) are resolved
+ * from the app's own node_modules and tree-shaken into the output.
+ *
+ * @param input   Absolute path to the JS/TS entry (e.g. `${cwd}/resources/js/app.js`)
+ * @param outdir  Absolute path to the output directory (e.g. `${cwd}/public/js`)
+ * @param minify  Whether to minify the output (true in production)
+ */
+export async function buildJsBundle(
+  input: string,
+  outdir: string,
+  minify = false,
+): Promise<{ success: boolean; logs: unknown[] }> {
+  try {
+    return await Bun.build({
+      entrypoints: [input],
+      outdir,
+      target: "browser",
+      format: "esm",
+      minify,
+    });
+  } catch (error) {
+    return { success: false, logs: [error] };
+  }
+}
+
+function _basename(filePath: string): string {
+  return filePath.split("/").at(-1) ?? filePath;
+}
+
+/** The resolved `app.assets` config block (see {@link AppAssetsConfig}). */
+export interface AssetBuildConfig {
+  entrypoint: string | string[];
+  outDir: string;
+  prefix: string;
+  minify: boolean;
+}
+
+/**
+ * Bundle the app's configured asset entrypoint(s) with Bun's native bundler.
+ *
+ * Entry paths and `outDir` are resolved relative to `cwd`. A JS/TS entry that
+ * imports CSS emits a sibling stylesheet; Tailwind v4 is handled automatically
+ * when `bun-plugin-tailwind` is installed in the app. Called by `serve` (once)
+ * and by the dev build hook (on change) — see {@link buildConfiguredAssets}.
+ *
+ * Mirrors the Inertia build pipeline: `splitting` emits shared chunks from
+ * dynamic imports (per-page code-splitting), and sourcemaps are emitted in dev
+ * (external) but omitted in production. Entry filenames stay stable across
+ * builds — cache-busting is handled at reference time by `asset()` appending
+ * `?v=` in dev, not by hashed output names — while split chunks are named after
+ * their content and so change on every rebuild. The chunks the build replaces
+ * are swept up afterwards; see {@link pruneBuildOutput}.
+ */
+export async function buildConfiguredAssets(
+  assets: AssetBuildConfig,
+  cwd: string,
+): Promise<{ success: boolean; logs: unknown[] }> {
+  const entries = Array.isArray(assets.entrypoint) ? assets.entrypoint : [assets.entrypoint];
+  const entrypoints = entries.map((entry) => `${cwd}/${entry}`);
+  const outdir = `${cwd}/${assets.outDir}`;
+
+  try {
+    const plugins = await detectCssPlugins(cwd);
+    const result = await Bun.build({
+      entrypoints,
+      outdir,
+      target: "browser",
+      format: "esm",
+      // Per-page chunks from dynamic imports — same as `inertia:build`.
+      splitting: true,
+      // Sourcemaps for dev debugging; none in production (minified) builds.
+      sourcemap: assets.minify ? "none" : "external",
+      minify: assets.minify,
+      plugins,
+    });
+
+    if (result.success) await pruneBuildOutput(outdir, result.outputs);
+    return result;
+  } catch (error) {
+    return { success: false, logs: [error] };
+  }
+}

package/src/dev/DevBuildHook.ts

@@ -0,0 +1,74 @@
+/**
+ * The registry of frontend build routines used in dev mode. Lets view packages
+ * (`@zerotal/inertia`, `@zerotal/flow`) hand their build routine to the core
+ * DevOrchestrator without core importing them, avoiding a circular dependency.
+ *
+ * The registry holds one entry per package rather than a single routine,
+ * because an app can run more than one view layer at a time — an Inertia app
+ * that installs `@zerotal/monitor` pulls in Flow for the monitor panel, and
+ * both have a bundle to build. With a single slot the provider that booted last
+ * would silently replace the other's build, and the displaced package's assets
+ * would sit frozen at whatever the last manual build left on disk while the dev
+ * server cheerfully reported "rebuilding… ✓ ready" on every change.
+ */
+
+/** Outcome of a frontend build: whether it succeeded and any collected logs. */
+export interface BuildResult {
+  success: boolean;
+  logs?: unknown[];
+}
+
+/** A frontend build routine that resolves once the build finishes. */
+export type BuildHookFn = () => Promise<BuildResult>;
+
+const _hooks = new Map<string, BuildHookFn>();
+
+/**
+ * @internal Exported for view packages to wire their dev build into core.
+ *
+ * Register a frontend build routine for dev mode under a package name.
+ * Registering the same name twice replaces the earlier routine, so a provider
+ * may safely register on every boot.
+ *
+ * Called from provider boot (e.g. `InertiaProvider.onBooted()`) so the core
+ * DevOrchestrator can trigger a build without `@zerotal/core` importing the
+ * view package (which would create a circular dependency).
+ */
+export function registerDevBuildHook(name: string, fn: BuildHookFn): void {
+  _hooks.set(name, fn);
+}
+
+/** @internal Whether any package has a dev build routine registered. */
+export function hasDevBuildHooks(): boolean {
+  return _hooks.size > 0;
+}
+
+/** @internal Forget every registered routine (tests only). */
+export function _resetDevBuildHooks(): void {
+  _hooks.clear();
+}
+
+/**
+ * @internal Run every registered build routine and merge the outcomes.
+ *
+ * Routines run concurrently — they write to separate output directories — and
+ * one failing (or throwing) neither hides the others nor stops them. Logs are
+ * tagged with the package name so a failure points at the build that produced it.
+ */
+export async function runDevBuildHooks(): Promise<BuildResult> {
+  const results = await Promise.all(
+    Array.from(_hooks, async ([name, fn]): Promise<BuildResult> => {
+      try {
+        const result = await fn();
+        return { success: result.success, logs: (result.logs ?? []).map((l) => `[${name}] ${l}`) };
+      } catch (error) {
+        return { success: false, logs: [`[${name}] ${error}`] };
+      }
+    }),
+  );
+
+  return {
+    success: results.every((result) => result.success),
+    logs: results.flatMap((result) => result.logs ?? []),
+  };
+}

package/src/dev/DevOrchestrator.ts

@@ -0,0 +1,213 @@
+/**
+ * The supervisor process for dev mode: it builds assets, spawns the Zerotal
+ * server as a child, watches the filesystem, and restarts or rebuilds on change.
+ */
+import { watch } from "node:fs";
+import type { BuildHookFn } from "./DevBuildHook.ts";
+import { DEV_WORKER_ENV_VAR } from "../support/env.ts";
+
+/**
+ * Dev Orchestrator — Process 1 of the two-process dev mode.
+ *
+ * Responsibilities:
+ *   - Runs an initial pages-manifest sync + asset build before the server starts.
+ *   - Spawns the Zerotal server (Process 2) as a child process with stdin piped.
+ *   - Watches the filesystem and:
+ *       • Backend change  → debounced server restart (150 ms)
+ *       • Frontend change → debounced asset rebuild + browser reload signal (80 ms)
+ *   - Writes `reload\n` to the child's stdin after each successful rebuild so the
+ *     server can forward the signal to connected SSE clients.
+ *
+ * Process 2 is started with --dev-worker so it:
+ *   - Serves GET /__dev/events  (SSE reload endpoint)
+ *   - Reads stdin and calls DevReloadServer.broadcast('reload') on each `reload` line
+ */
+export class DevOrchestrator {
+  // Paths whose changes trigger a full server restart
+  private static readonly BACKEND = [
+    "app/",
+    "routes/",
+    "bootstrap/",
+    "config/",
+    "packages/",
+    "resources/app.html",
+  ];
+
+  // Paths whose changes trigger a frontend rebuild only
+  private static readonly FRONTEND = ["resources/pages/", "resources/js/", "resources/css/"];
+
+  // Always-ignored output / tool directories
+  private static readonly IGNORE = ["public/", ".zerotal/", "node_modules/", ".git/"];
+
+  // pages.generated.ts is written BY the build — ignore its own change event
+  private static readonly IGNORE_FILES = new Set(["resources/js/pages.generated.ts"]);
+
+  private _child: ReturnType<typeof Bun.spawn> | null = null;
+  private _restartTimer: ReturnType<typeof setTimeout> | null = null;
+  private _buildTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Per-build asset-version token — bumped on each build, busts `asset()` `?v=` URLs. */
+  private _assetVersion = Date.now().toString(36);
+
+  constructor(
+    private readonly _port: number,
+    private readonly _cwd: string,
+    private readonly _build: BuildHookFn,
+  ) {}
+
+  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._spawnServer();
+    this._watch();
+
+    // Park the process — cleanup happens in signal handlers registered by _watch()
+    await new Promise<never>(() => {});
+  }
+
+  // ── Server management ──────────────────────────────────────────────────────
+
+  private _spawnServer(): void {
+    this._child = Bun.spawn(
+      ["bun", Bun.main, "serve", "--port", String(this._port), "--dev-worker"],
+      {
+        stdin: "pipe",
+        stdout: "inherit",
+        stderr: "inherit",
+        cwd: this._cwd,
+        env: {
+          ...Bun.env,
+          APP_ENV: "web",
+          // Mark the worker as developer-supervised. APP_ENV above is the
+          // runtime mode, not a deployment name, so it cannot carry this —
+          // without the flag the worker looks production-like to every
+          // dev-surface gate and `serve --dev` renders bare 500s with no stack.
+          [DEV_WORKER_ENV_VAR]: "1",
+          ZT_ASSET_VERSION: this._assetVersion,
+        },
+      },
+    );
+
+    this._child.exited.then((code) => {
+      // Ignore expected exits (restart in progress or clean shutdown)
+      if (this._child && this._restartTimer === null && code !== 0) {
+        console.log(`  [zerotal:dev] server exited with code ${code}`);
+      }
+    });
+  }
+
+  private _scheduleRestart(): void {
+    if (this._restartTimer) clearTimeout(this._restartTimer);
+    this._restartTimer = setTimeout(async () => {
+      this._restartTimer = null;
+      console.log("  [zerotal:dev] ↻  backend change — rebuilding + restarting server...");
+
+      // Rebuild assets before respawning: server-rendered views (Flow pages in `app/`,
+      // controllers returning markup) contain Tailwind classes the stylesheet scans via
+      // `@source`, so a backend edit can introduce new classes. Without this, a new utility
+      // used in a page wouldn't appear until an unrelated `resources/` file changed. The
+      // fresh `_assetVersion` (bumped by _runBuild) is passed to the respawned worker, so the
+      // browser refetches the updated CSS.
+      await this._runBuild();
+
+      const previousChild = this._child;
+      this._child = null;
+
+      if (previousChild) {
+        previousChild.kill("SIGTERM");
+        const forceKill = setTimeout(() => previousChild.kill("SIGKILL"), 1_500);
+        await previousChild.exited;
+        clearTimeout(forceKill);
+      }
+
+      this._spawnServer();
+    }, 150);
+  }
+
+  // ── Build management ───────────────────────────────────────────────────────
+
+  private _scheduleBuild(path: string): void {
+    if (this._buildTimer) clearTimeout(this._buildTimer);
+    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._signalReload();
+      }
+    }, 80);
+  }
+
+  private async _runBuild(): Promise<boolean> {
+    try {
+      const result = await this._build();
+      if (!result.success) {
+        console.error("  [zerotal:dev] ✗  build failed:");
+        for (const entry of result.logs ?? []) {
+          console.error("    ", String(entry));
+        }
+        return false;
+      }
+      // Fresh token so the next `asset()` URL changes and the browser refetches.
+      this._assetVersion = Date.now().toString(36);
+      return true;
+    } catch (error) {
+      console.error("  [zerotal:dev] ✗  build error:", error);
+      return false;
+    }
+  }
+
+  private _signalReload(): void {
+    try {
+      // When spawned with `stdin: "pipe"` this is a FileSink (not a numeric fd).
+      // Carry the fresh asset-version token so the worker can update `asset()`
+      // URLs before broadcasting the browser reload.
+      const sink = this._child?.stdin as import("bun").FileSink | undefined;
+      sink?.write(`reload:${this._assetVersion}\n`);
+      sink?.flush?.();
+    } catch {
+      // Child may be in mid-restart — ignore
+    }
+  }
+
+  // ── File watcher ───────────────────────────────────────────────────────────
+
+  private _watch(): void {
+    const watcher = watch(this._cwd, { recursive: true }, (_event, filename) => {
+      if (!filename) return;
+
+      // Normalise to forward slashes (Windows reports backslashes).
+      const relativePath = filename.replace(/\\/g, "/");
+
+      // Skip hidden dirs, ignored dirs, and generated files.
+      if (relativePath.startsWith(".")) return;
+      if (DevOrchestrator.IGNORE.some((prefix) => relativePath.startsWith(prefix))) return;
+      if (DevOrchestrator.IGNORE_FILES.has(relativePath)) return;
+
+      if (
+        DevOrchestrator.BACKEND.some(
+          (prefix) => relativePath.startsWith(prefix) || relativePath === prefix.replace(/\/$/, ""),
+        )
+      ) {
+        this._scheduleRestart();
+      } else if (DevOrchestrator.FRONTEND.some((prefix) => relativePath.startsWith(prefix))) {
+        this._scheduleBuild(relativePath);
+      }
+    });
+
+    const cleanup = () => {
+      watcher.close();
+      this._child?.kill("SIGTERM");
+      process.exit(0);
+    };
+
+    process.on("SIGTERM", cleanup);
+    process.on("SIGINT", cleanup);
+  }
+}

package/src/dev/DevReloadMiddleware.ts

@@ -0,0 +1,101 @@
+/**
+ * Dev-only HTML response injector.
+ *
+ * Registered globally by `Application.enableDevWs()` (i.e. only under
+ * `serve --dev-worker`), it rewrites every `text/html` response to inject:
+ *
+ *   1. A tiny live-reload client that connects to the `/__dev/ws` WebSocket and
+ *      reloads the page whenever the DevOrchestrator rebuilds assets.
+ *   2. Any snippets registered via {@link registerDevHtmlSnippet} — this is how
+ *      `@zerotal/devtools` auto-injects its in-page panel.
+ *
+ * This generalises what Inertia previously did in its own HTML template, so the
+ * reload client now works for *any* view layer (flow, flow-ui, JSX, plain HTML)
+ * with zero app wiring. Pages that already embed a `/__dev/ws` client (e.g. an
+ * Inertia template) are detected and not double-injected.
+ */
+import type { NextFn } from "../pipeline/types.ts";
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import { BaseMiddleware } from "../middleware/BaseMiddleware.ts";
+import { DEV_RELOAD_CLIENT } from "./reloadClient.ts";
+
+/** Produces an HTML fragment to inject before `</body>` for the given request. */
+export type DevHtmlSnippet = (ctx: HttpContext) => string;
+
+interface RegisteredSnippet {
+  name: string;
+  fn: DevHtmlSnippet;
+}
+
+const _snippets: RegisteredSnippet[] = [];
+
+/**
+ * Register an HTML snippet to inject into dev HTML responses (before `</body>`).
+ * Idempotent by `name`, so providers can register on every boot safely. Return
+ * an empty string from `fn` to skip injection for a given request (e.g. to avoid
+ * injecting into your own tool's pages).
+ *
+ * @example
+ * registerDevHtmlSnippet("devtools", (ctx) =>
+ *   ctx.url.pathname.startsWith("/__zerotal") ? "" : `<script src="/__zerotal/devtools/client.js"></script>`,
+ * );
+ */
+export function registerDevHtmlSnippet(name: string, fn: DevHtmlSnippet): void {
+  if (_snippets.some((s) => s.name === name)) return;
+  _snippets.push({ name, fn });
+}
+
+/** @internal — reset the registry (tests only). */
+export function _resetDevHtmlSnippets(): void {
+  _snippets.length = 0;
+}
+
+// The live-reload client is only meaningful when the /__dev/ws endpoint exists
+// (i.e. under `serve --dev-worker`). Snippets, by contrast, inject in any dev
+// mode — so devtools can share this middleware even under a plain `serve`.
+let _reloadClientActive = false;
+
+/** Enable injection of the live-reload client. Called by `Application.enableDevWs()`. */
+export function setDevReloadClientActive(active: boolean): void {
+  _reloadClientActive = active;
+}
+
+export class DevReloadMiddleware extends BaseMiddleware {
+  protected options: {} = {};
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const res = await next();
+    if (!(res instanceof Response)) return res;
+
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.includes("text/html")) return res;
+
+    let html: string;
+    try {
+      html = await res.clone().text();
+    } catch {
+      return res; // unreadable / streaming body — leave it alone
+    }
+
+    let injection = "";
+    // Inject the reload client only under dev-worker, and not when the page
+    // already embeds one (e.g. an Inertia template).
+    if (_reloadClientActive && !html.includes("/__dev/ws")) injection += DEV_RELOAD_CLIENT;
+    for (const snippet of _snippets) {
+      try {
+        injection += snippet.fn(http);
+      } catch {
+        /* a broken snippet must never break the page */
+      }
+    }
+    if (!injection) return res;
+
+    const body = html.includes("</body>")
+      ? html.replace("</body>", `${injection}\n</body>`)
+      : html + injection;
+
+    const headers = new Headers(res.headers);
+    headers.delete("content-length"); // body changed — let the runtime recompute
+    return new Response(body, { status: res.status, statusText: res.statusText, headers });
+  }
+}

package/src/dev/DevReloadServer.ts

@@ -0,0 +1,85 @@
+/**
+ * Manages the set of active SSE connections for the dev auto-reload feature.
+ *
+ * Used by ServeCommand (--dev-worker mode):
+ *   - handleSSE()     — returns a streaming Response for GET /__dev/events
+ *   - broadcast(msg)  — pushes a message to every connected browser tab
+ *
+ * The Application registers the /__dev/events route before starting only when
+ * withDevReload() is called. Zero code runs in production.
+ */
+
+const _encoder = new TextEncoder();
+
+// Set of live stream controllers — one per connected browser tab.
+const _clients = new Set<ReadableStreamDefaultController<Uint8Array>>();
+
+let _pingTimer: ReturnType<typeof setInterval> | null = null;
+
+function _startPing(): void {
+  if (_pingTimer) return;
+  _pingTimer = setInterval(() => broadcast("ping"), 25_000);
+}
+
+function _stopPing(): void {
+  if (_pingTimer) {
+    clearInterval(_pingTimer);
+    _pingTimer = null;
+  }
+}
+
+/**
+ * Return a Server-Sent Events streaming Response.
+ * Pass this as the handler for GET /__dev/events.
+ */
+export function handleSSE(): Response {
+  let streamController: ReadableStreamDefaultController<Uint8Array> | null = null;
+
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      streamController = controller;
+      _clients.add(controller);
+      _startPing();
+      // Handshake event — confirms the connection is live.
+      controller.enqueue(_encoder.encode("data: connected\n\n"));
+    },
+    // `cancel(reason)` receives the cancellation reason, not the controller.
+    // Use the captured controller reference so we remove the correct entry.
+    cancel() {
+      if (streamController) {
+        _clients.delete(streamController);
+        streamController = null;
+      }
+      if (_clients.size === 0) _stopPing();
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-store",
+      Connection: "keep-alive",
+      "X-Accel-Buffering": "no", // disable nginx buffering for SSE
+    },
+  });
+}
+
+/**
+ * Push a message to all connected browser tabs.
+ * Stale controllers (closed tabs) are silently pruned.
+ */
+export function broadcast(message: string): void {
+  const payload = _encoder.encode(`data: ${message}\n\n`);
+  const staleControllers: ReadableStreamDefaultController<Uint8Array>[] = [];
+
+  for (const controller of _clients) {
+    try {
+      controller.enqueue(payload);
+    } catch {
+      staleControllers.push(controller);
+    }
+  }
+
+  for (const controller of staleControllers) _clients.delete(controller);
+  if (_clients.size === 0) _stopPing();
+}