@zerotal/core 1.4.0 → 1.5.0

package/src/application/DevErrorPage.ts

@@ -4,6 +4,8 @@
  * stack trace, source context, and request details.
  */
 import type { HttpContext } from "../pipeline/HttpContext.ts";
+import { _diagnoseError } from "./diagnostics.ts";
+import type { ErrorDiagnosis } from "./diagnostics.ts";
 import { devSurfacesEnabled } from "../support/env.ts";
 
 // ── HTTP error page (4xx / production 5xx) ────────────────────────────────────
@@ -236,6 +238,34 @@ function shortPath(full: string): string {
  * with its parsed stack trace, source context, and request details. Never
  * served in production.
  */
+/**
+ * The diagnosis panel, above the stack because that is where the answer is.
+ *
+ * The button posts the token it was given and replaces its own label with the
+ * outcome. On success the page reloads, because the point is to get back to what
+ * the developer was actually doing — and a failure says so in place rather than
+ * navigating away from the error that prompted it.
+ */
+function renderDiagnosis(d: ErrorDiagnosis): string {
+  const items = d.items?.length
+    ? `<ul class="dx-items">${d.items.map((i) => `<li>${esc(i)}</li>`).join("")}</ul>`
+    : "";
+  const action = d.action
+    ? `<div class="dx-actions">
+         <button class="dx-btn" id="dxRun"
+           data-url="${esc(d.action.url)}" data-token="${esc(d.action.token)}"
+           data-pending="${esc(d.action.pendingLabel ?? "Working…")}">${esc(d.action.label)}</button>
+         <span class="dx-status" id="dxStatus"></span>
+       </div>`
+    : "";
+  return `<div class="dx">
+  <div class="dx-title">${esc(d.title)}</div>
+  <div class="dx-detail">${esc(d.detail)}</div>
+  ${items}
+  ${action}
+</div>`;
+}
+
 export async function renderDevErrorPage(err: unknown, ctx?: HttpContext): Promise<Response> {
   const error = err instanceof Error ? err : new Error(String(err));
   const errClass = error.constructor?.name || "Error";
@@ -259,6 +289,11 @@ export async function renderDevErrorPage(err: unknown, ctx?: HttpContext): Promi
         .map(([k, v]) => ({ k, v }))
     : [];
 
+  // Runs before the page is assembled so a diagnosis can lead, above the stack.
+  // The stack for this error class is usually all framework frames — the answer
+  // is never in it, which is the whole reason this panel exists.
+  const diagnosis = await _diagnoseError(error, ctx);
+
   const appFrames = ctxFrames.filter((f) => f.isApp);
   const vendorFrames = ctxFrames.filter((f) => !f.isApp);
   const firstApp = appFrames[0] ?? ctxFrames[0];
@@ -327,6 +362,19 @@ table.info td{padding:5px 12px;vertical-align:top;border-bottom:1px solid #f1f5f
 table.info td:first-child{width:200px;color:#64748b;font-weight:500;white-space:nowrap}
 table.info td:last-child{font-family:monospace;color:#1e293b;word-break:break-all}
 
+/* ── Diagnosis ── */
+.dx{background:#fffbeb;border-bottom:1px solid #fde68a;padding:20px 32px}
+.dx-title{font-size:15px;font-weight:700;color:#92400e;margin-bottom:6px}
+.dx-detail{font-size:13px;color:#78350f;line-height:1.65;max-width:900px}
+.dx-items{margin:12px 0 0;padding-left:18px;font-family:monospace;font-size:12px;color:#78350f}
+.dx-items li{margin:3px 0}
+.dx-actions{margin-top:16px;display:flex;align-items:center;gap:12px;flex-wrap:wrap}
+.dx-btn{padding:8px 16px;background:#92400e;border:0;border-radius:6px;color:#fff;font-size:13px;font-weight:600;cursor:pointer;transition:opacity .15s}
+.dx-btn:hover{opacity:.9}
+.dx-btn:disabled{opacity:.55;cursor:default}
+.dx-status{font-size:12px;color:#78350f}
+.dx-status.bad{color:#b91c1c;font-family:monospace}
+
 /* ── Footer ── */
 .footer{padding:12px 20px;background:#f8fafc;border-top:1px solid #e2e8f0;font-size:11px;color:#94a3b8;display:flex;gap:16px}
 </style>
@@ -352,6 +400,8 @@ table.info td:last-child{font-family:monospace;color:#1e293b;word-break:break-al
   </div>
 </div>
 
+${diagnosis ? renderDiagnosis(diagnosis) : ""}
+
 <!-- Body: frames + code -->
 <div class="body">
 
@@ -459,6 +509,38 @@ table.info td:last-child{font-family:monospace;color:#1e293b;word-break:break-al
 <script>
 const ctxData = ${JSON.stringify(ctxFrames.map((f) => f.file + ":" + f.line))};
 
+// The diagnosis button, when one was offered. Attached by id rather than inline
+// so the panel's markup carries no script, and disabled while in flight so a
+// double click cannot run the action twice.
+(function () {
+  const btn = document.getElementById('dxRun');
+  if (!btn) return;
+  const status = document.getElementById('dxStatus');
+  btn.addEventListener('click', async () => {
+    btn.disabled = true;
+    const original = btn.textContent;
+    btn.textContent = btn.dataset.pending;
+    status.className = 'dx-status';
+    status.textContent = '';
+    try {
+      const res = await fetch(btn.dataset.url, {
+        method: 'POST',
+        headers: { 'X-Zerotal-Diagnosis-Token': btn.dataset.token },
+      });
+      const body = await res.text();
+      if (!res.ok) throw new Error(body || ('HTTP ' + res.status));
+      status.textContent = body || 'Done. Reloading…';
+      // Back to what the developer was actually doing.
+      location.reload();
+    } catch (e) {
+      btn.disabled = false;
+      btn.textContent = original;
+      status.className = 'dx-status bad';
+      status.textContent = String(e && e.message ? e.message : e);
+    }
+  });
+})();
+
 const _errorMd = ${JSON.stringify({
     errClass,
     message,

package/src/application/diagnostics.ts

@@ -0,0 +1,111 @@
+/**
+ * Diagnoses for the development error page.
+ *
+ * The overlay is good at showing *what* threw and bad at saying what to do about
+ * it. `no such table: assets` is the canonical case: the message is exact, the
+ * stack is entirely framework frames, and the answer — "you have three
+ * migrations you have not run" — lives in a package `@zerotal/core` cannot
+ * import, because `@zerotal/orm` depends on it and not the other way round.
+ *
+ * So the overlay asks instead. A package registers a diagnoser, the error page
+ * runs them in order, and the first one that recognises the error contributes a
+ * panel. A diagnoser that recognises nothing returns `null` and costs a function
+ * call.
+ *
+ * @example
+ * ```ts
+ * registerErrorDiagnoser((error) => {
+ *   const missing = detectMissingTable(error);
+ *   if (!missing) return null;
+ *   return { title: `The ${missing} table does not exist.`, detail: "…" };
+ * });
+ * ```
+ */
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+
+/**
+ * A button the overlay may offer.
+ *
+ * Deliberately narrow: a `POST` to a same-origin path, carrying a token the page
+ * was given. It exists so a diagnosis can *fix* the thing it diagnosed, and the
+ * shape is constrained because that means a page rendered by a GET can change
+ * server state — see the safety note on {@link ErrorDiagnosis}.
+ */
+export interface DiagnosisAction {
+  /** Button text, e.g. `"Run 3 migrations"`. */
+  label: string;
+  /** Same-origin path the button posts to. */
+  url: string;
+  /** Single-use token minted for this render, required by the endpoint. */
+  token: string;
+  /** Text shown while the request is in flight. */
+  pendingLabel?: string;
+}
+
+/**
+ * What a diagnoser concluded.
+ *
+ * > ⚠️ **An `action` mutates server state from a page rendered by a GET.** A dev
+ * > server on `localhost:3000` is reachable by any site the developer has open in
+ * > another tab, so the endpoint behind one must: refuse outside development on
+ * > its own terms rather than trusting that the overlay is dev-only, require the
+ * > `token`, and check the origin. Whoever registers the endpoint owns all three
+ * > — this type only carries them to the page.
+ */
+export interface ErrorDiagnosis {
+  /** One line: what is actually wrong. */
+  title: string;
+  /** A short paragraph: why, and what to do. */
+  detail: string;
+  /** Supporting specifics — migration names, candidate files. Rendered as a list. */
+  items?: string[];
+  /** Offered only when the diagnosis is confident enough to be actionable. */
+  action?: DiagnosisAction;
+}
+
+export type ErrorDiagnoser = (
+  error: Error,
+  ctx?: HttpContext,
+) => ErrorDiagnosis | null | Promise<ErrorDiagnosis | null>;
+
+const _diagnosers: ErrorDiagnoser[] = [];
+
+/**
+ * Contribute a diagnosis to the development error page.
+ *
+ * Registered from a provider's `onRegister()`. Diagnosers run in registration
+ * order and the first non-null result wins, so a package should recognise only
+ * errors it genuinely owns.
+ */
+export function registerErrorDiagnoser(diagnoser: ErrorDiagnoser): void {
+  _diagnosers.push(diagnoser);
+}
+
+/**
+ * Run the registered diagnosers and return the first result.
+ *
+ * A diagnoser that throws is skipped: it runs while an error page is already
+ * being rendered, and failing there would replace a useful stack trace with a
+ * useless one.
+ *
+ * @internal
+ */
+export async function _diagnoseError(
+  error: Error,
+  ctx?: HttpContext,
+): Promise<ErrorDiagnosis | null> {
+  for (const diagnoser of _diagnosers) {
+    try {
+      const result = await diagnoser(error, ctx);
+      if (result) return result;
+    } catch {
+      // See above — a broken diagnoser must not take the error page with it.
+    }
+  }
+  return null;
+}
+
+/** Drop every registered diagnoser. Tests. @internal */
+export function _resetErrorDiagnosers(): void {
+  _diagnosers.length = 0;
+}

package/src/command/CommandRunner.ts

@@ -9,6 +9,8 @@ import { Command } from "./Command.ts";
 import type { ArgDef, FlagDef } from "./Command.ts";
 import { BufferWriter } from "./OutputWriter.ts";
 import { FrameworkEvents, CommandRan } from "../events/FrameworkEvents.ts";
+import { makeDeployCommand } from "./builtin/DeployCommand.ts";
+import { DEFAULT_DEPLOY_TARGETS } from "../config/DeployConfig.ts";
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
@@ -304,6 +306,18 @@ export class CommandRunner {
     for (const alias of aliases) this._registry.set(alias, thunk);
   }
 
+  /**
+   * Whether a command is registered, without resolving it.
+   *
+   * Lets a caller compose a pipeline out of whatever this app actually has —
+   * `zt deploy:<env>` skips `inertia:build` in an app with no Inertia rather than
+   * failing on it. Deliberately does not resolve the lazy thunk: asking whether a
+   * step exists should not import the package that provides it.
+   */
+  has(name: string): boolean {
+    return this._registry.has(name);
+  }
+
   // ── Boot ──────────────────────────────────────────────────────────────────
 
   /**
@@ -322,6 +336,7 @@ export class CommandRunner {
 
     const {
       ServeCommand,
+      DevCommand,
       ReplCommand,
       WorkerCommand,
       CompileCommand,
@@ -342,8 +357,11 @@ export class CommandRunner {
       MakeTestCommand,
       TestCommand,
       RouteListCommand,
+      RouteTypesCommand,
+      DoctorCommand,
       MakeProviderCommand,
       CssBuildCommand,
+      AssetsBuildCommand,
       LintPackagesCommand,
       MakePackageCommand,
     } = await import("./builtin/index.ts");
@@ -351,13 +369,23 @@ export class CommandRunner {
     // ServeCommand is always registered — usable from any environment.
     this.register(ServeCommand);
 
+    // So is `dev`, and it has to be: `setAppEnv("dev")` boots process 1 as `web`
+    // so that web-only providers are asked for their dev processes, which puts
+    // the command itself on the wrong side of the `!== "web"` gate below.
+    this.register(DevCommand);
+
     // reload + status are always available — they talk to the running server,
     // not the app itself, so they don't need an application instance.
     this.register(ReloadCommand);
     this.register(StatusCommand);
 
-    // route:list is an inspection command — always available regardless of mode.
+    // route:list and doctor are inspection commands — always available regardless of mode.
     this.register(RouteListCommand);
+    this.register(DoctorCommand);
+
+    // route:types reads the same booted router, so it is available wherever
+    // route:list is — including in CI containers that only ever run `--check`.
+    this.register(RouteTypesCommand, ["routes:types"]);
 
     // Non-web commands (console, worker, test).
     if (this._app._env !== "web") {
@@ -381,10 +409,63 @@ export class CommandRunner {
         MakeTestCommand,
         TestCommand,
         CssBuildCommand,
+        AssetsBuildCommand,
         LintPackagesCommand,
         MakePackageCommand,
       ]);
+
+      // One `deploy:<target>` per environment this app releases to. Console-only,
+      // like the other release commands — a running web server has no business
+      // migrating a database.
+      this._registerDeployTargets();
+
+      // `make:command` generates into `app/commands/`; the runner reads the same
+      // directory, so a generated command is runnable without registering a provider.
+      // App commands land last, after the built-ins, so a name collision resolves in
+      // the app's favour.
+      await this._discoverAppCommands();
+    }
+  }
+
+  /**
+   * Register `deploy:<target>` for each target in `config/deploy.ts`, or for
+   * `production` and `staging` when the app declares none.
+   *
+   * Runs after `boot()` has loaded config, so the targets are readable here for the
+   * same reason `_discoverAppCommands` can read the conventions block.
+   */
+  private _registerDeployTargets(): void {
+    let targets = DEFAULT_DEPLOY_TARGETS;
+    try {
+      const config = this._app.container.makeSync("config") as {
+        get(key: string, fallback?: unknown): unknown;
+      };
+      const declared = config.get("deploy.targets", undefined) as
+        Record<string, unknown> | undefined;
+      if (declared && Object.keys(declared).length > 0) targets = declared as typeof targets;
+    } catch {
+      /* no config store — the defaults are the answer */
+    }
+    for (const target of Object.keys(targets)) this.register(makeDeployCommand(target));
+  }
+
+  /**
+   * Auto-discover commands from the conventional directory (`app/commands/`, overridable
+   * via `app.conventions.paths.commands`). Gated by `app.conventions.enabled`, like every
+   * other convention. Best-effort: a missing directory registers nothing.
+   */
+  private async _discoverAppCommands(root: string = process.cwd()): Promise<string[]> {
+    let raw: { enabled?: boolean; paths?: Record<string, string> } = {};
+    try {
+      const config = this._app.container.makeSync("config") as {
+        get(key: string): unknown;
+      };
+      raw = (config.get("app.conventions") ?? {}) as typeof raw;
+    } catch {
+      /* config not resolvable — use the defaults */
     }
+    if (raw.enabled === false) return [];
+    return this.discover(`${root}/${raw.paths?.["commands"] ?? "app/commands"}`);
   }
 
   // ── Private resolution ────────────────────────────────────────────────────

package/src/command/builtin/AssetsBuildCommand.ts

@@ -0,0 +1,102 @@
+import { Command } from "../Command.ts";
+import type { Application } from "../../application/Application.ts";
+import type { ConfigManager } from "../../config/ConfigManager.ts";
+import { buildConfiguredAssets, type AssetBuildConfig } from "../../dev/CssPlugins.ts";
+
+/**
+ * `bun zt assets:build` — build every frontend bundle this app declares, in one step,
+ * as part of a release rather than as a side effect of starting the server.
+ *
+ * `serve` builds at boot, which is right in development and awkward in production: it
+ * makes the server process need write access to its own output directory, so a properly
+ * hardened unit (`ProtectSystem=strict`) restart-loops on a read-only filesystem. Running
+ * this at deploy time means `serve` finds the output already there, skips the build, and
+ * needs no write access at all.
+ *
+ * Covers both sources of bundles:
+ *   - `app.assets` from `config/app.ts` (whatever entrypoints it names)
+ *   - Flow's conventional entry points, `resources/css/app.css` and `resources/js/app.js`
+ *
+ * Inertia apps build with `bun zt inertia:build` instead — this does not duplicate it.
+ *
+ * @category Build & assets
+ */
+export class AssetsBuildCommand extends Command {
+  static override commandName = "assets:build";
+  static override description = "Build all configured frontend bundles for a release";
+  static override needsApp = true;
+
+  static override flags = [
+    {
+      name: "minify",
+      short: "m",
+      type: "boolean" as const,
+      description: "Minify the output",
+      default: true,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const cwd = process.cwd();
+    const minify = this.flags["minify"] as boolean;
+    let built = 0;
+    let failed = 0;
+
+    const assets = this._assetsConfig();
+    if (assets) {
+      const entries = Array.isArray(assets.entrypoint)
+        ? assets.entrypoint.join(", ")
+        : assets.entrypoint;
+      this.info(`Building assets: ${entries} → ${assets.outDir}/`);
+      const result = await buildConfiguredAssets({ ...assets, minify }, cwd);
+      if (result.success) built++;
+      else {
+        failed++;
+        this.error("Asset build failed:");
+        for (const log of result.logs ?? []) console.error(log);
+      }
+    }
+
+    // Flow's own bundles. Built by entry-point convention rather than config, which is
+    // why they are easy to forget in a release script and easy to discover here.
+    const { buildCssBundle, buildJsBundle } = await import("../../dev/CssPlugins.ts");
+    const conventional = [
+      { entry: "resources/css/app.css", outDir: "public/css", build: buildCssBundle },
+      { entry: "resources/js/app.js", outDir: "public/js", build: buildJsBundle },
+    ];
+    for (const { entry, outDir, build } of conventional) {
+      if (!(await Bun.file(`${cwd}/${entry}`).exists())) continue;
+      this.info(`Building ${entry} → ${outDir}/`);
+      const result = await build(`${cwd}/${entry}`, `${cwd}/${outDir}`, minify);
+      if (result.success) built++;
+      else {
+        failed++;
+        this.error(`${entry} build failed:`);
+        for (const log of result.logs ?? []) console.error(log);
+      }
+    }
+
+    if (built === 0 && failed === 0) {
+      this.info("No frontend bundles configured — nothing to build.");
+      return;
+    }
+    // Throw rather than `process.exit(1)`. The runner turns a throw into exit 1, so
+    // the CLI behaves identically — but a caller composing this through
+    // `callInProcess` gets a failed step it can report on, instead of having the
+    // whole process killed mid-pipeline with its buffered output never flushed.
+    if (failed > 0) {
+      throw new Error(`${failed} bundle(s) failed, ${built} succeeded.`);
+    }
+    this.info(`Built ${built} bundle(s).`);
+  }
+
+  /** Read the resolved `app.assets` config block, or undefined when not configured. */
+  private _assetsConfig(): AssetBuildConfig | undefined {
+    try {
+      const config = (this.app as Application).container.makeSync("config") as ConfigManager;
+      return config.get("app.assets") as AssetBuildConfig | undefined;
+    } catch {
+      return undefined;
+    }
+  }
+}