@zerotal/core 1.4.0 → 1.5.0

package/src/command/builtin/DeployCommand.ts

@@ -0,0 +1,315 @@
+/**
+ * `bun zt deploy:<env>` — run a release, and refuse to finish it when something is
+ * wrong.
+ *
+ * The framework already had the pieces: `zt doctor` finds silent misconfigurations,
+ * config validators refuse an insecure production boot, `assets:build` builds a
+ * release, `migrate` applies the schema. What it did not have was an order, and an
+ * order is the whole value. Every deployment failure this framework has shipped has
+ * the same shape — the HTML renders, the transport is dead, the health check passes
+ * — and every one of them is cheaper to find before the cutover than after it.
+ *
+ * So: **everything that can refuse runs before anything that mutates.** A bad origin
+ * list stops the deploy while the old release is still serving, rather than after
+ * the migration has run and the new process is live and inert.
+ *
+ * What this deliberately does NOT do is restart the service or reach another
+ * machine. It exits non-zero, and the thing that owns process lifecycle — systemd,
+ * a container runtime, a deploy script — restarts only on success. The framework
+ * has stayed out of that, and this keeps it out.
+ */
+import { Command } from "../Command.ts";
+import type { Application } from "../../application/Application.ts";
+import type { ConfigManager } from "../../config/ConfigManager.ts";
+import type { CommandRunner } from "../CommandRunner.ts";
+import { runDoctor } from "../../doctor/AppDoctor.ts";
+import { probeTransport } from "../../doctor/TransportProbe.ts";
+import { runConfigValidators } from "../../config/validation.ts";
+import { deployEnv } from "../../support/env.ts";
+import { DEFAULT_DEPLOY_STEPS, type DeployTarget } from "../../config/DeployConfig.ts";
+
+/**
+ * The pipeline. Subclassed per target by {@link makeDeployCommand}, which is what
+ * gives each environment its own command name.
+ *
+ * @internal Apps declare targets in `config/deploy.ts` and run `zt deploy:<env>`;
+ * the class is how the runner builds those commands, not something to construct.
+ */
+export abstract class DeployCommand extends Command {
+  /** The deployment this subclass releases to — `production`, `staging`, … */
+  static target = "";
+  static override needsApp = true;
+
+  static override flags = [
+    {
+      name: "dry-run",
+      type: "boolean" as const,
+      description: "Print the steps that would run, and run none of them",
+      default: false,
+    },
+    {
+      name: "skip-migrations",
+      type: "boolean" as const,
+      description: "Do not run pending migrations as part of this release",
+      default: false,
+    },
+    {
+      name: "probe",
+      type: "string" as const,
+      description:
+        "After the release, run a real WebSocket handshake against this URL (defaults to the target's `url`)",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    if (!app) throw new Error("deploy needs a booted application.");
+
+    const target = (this.constructor as typeof DeployCommand).target;
+    const dryRun = this.flags["dry-run"] === true;
+
+    this.section(`Deploy → ${target}`);
+
+    const steps = this._steps(app, target);
+    if (dryRun) return this._printPlan(app, target, steps);
+
+    await this._preflight(app, target);
+    await this._runSteps(app, steps);
+    await this._verify(app);
+    await this._probe(app, target);
+
+    this.newLine();
+    this.info(`${target} release complete. Restart the service to pick it up.`);
+  }
+
+  // ── Phase 1 — preflight, which mutates nothing ──────────────────────────────
+
+  /**
+   * Refuse the deploy before it touches anything. Three questions, in the order
+   * that makes a failure cheapest to act on: is this even the right machine, is
+   * the configuration safe to deploy, and does the app pass its own checks.
+   */
+  private async _preflight(app: Application, target: string): Promise<void> {
+    this.newLine();
+    this.section("Preflight");
+
+    // Is this the environment it claims to be? `deployEnv()` rather than APP_ENV,
+    // which by now holds the runtime mode. Getting this wrong is how a production
+    // pipeline migrates a staging database.
+    const actual = deployEnv();
+    if (actual !== target) {
+      throw new Error(
+        `This process was started as ${actual || "(unset)"}, not ${target}. ` +
+          `Run it with APP_ENV=${target} so the config it loads is the one you are deploying.`,
+      );
+    }
+    this.line(`✓ APP_ENV is ${target}`);
+
+    // Re-run the config validators with production semantics. Boot already ran
+    // them, but the findings only refuse a boot when the deployment is prod-like —
+    // so on any other machine they were warnings nobody read.
+    const config = this._config(app);
+    if (!config) throw new Error("deploy needs a config store to validate.");
+    const issues: string[] = [];
+    try {
+      runConfigValidators(app._configValidators, config, true, (m) => issues.push(m));
+    } catch (error) {
+      // Thrown when a fatal issue is found: that IS the answer, not a failure.
+      for (const issue of (error as { issues?: Array<{ namespace: string; message: string }> })
+        .issues ?? []) {
+        issues.push(`config(${issue.namespace}): ${issue.message}`);
+      }
+    }
+    if (issues.length > 0) {
+      for (const issue of issues) this.error(`✗ ${issue}`);
+      throw new Error(
+        `${issues.length} config problem(s) would refuse a ${target} boot. Fix them before deploying.`,
+      );
+    }
+    this.line(`✓ config is valid for a ${target} deployment`);
+
+    await this._doctor(app, "preflight");
+  }
+
+  // ── Phase 2 — build and migrate ─────────────────────────────────────────────
+
+  /** The `config` store, or undefined when there is none to read. */
+  private _config(app: Application): ConfigManager | undefined {
+    try {
+      return app.container.makeSync("config") as ConfigManager;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** This target's declared settings, if `config/deploy.ts` names it. */
+  private _target(app: Application, target: string): DeployTarget | undefined {
+    return this._config(app)?.get<DeployTarget | undefined>(`deploy.targets.${target}`, undefined);
+  }
+
+  /** The release steps for this target, minus any whose command is not registered. */
+  private _steps(app: Application, target: string): string[] {
+    const wanted = this._target(app, target)?.steps ?? DEFAULT_DEPLOY_STEPS;
+    let runner: CommandRunner | undefined;
+    try {
+      runner = app.container.makeSync("commands") as CommandRunner;
+    } catch {
+      runner = undefined;
+    }
+    // No registry to ask means nothing can be confirmed present — report the
+    // declared list rather than silently claiming the release has no steps.
+    if (!runner) return [...wanted];
+    return [...wanted].filter((name) => runner.has(name));
+  }
+
+  private async _runSteps(app: Application, steps: string[]): Promise<void> {
+    const runner = app.container.makeSync("commands") as CommandRunner;
+    const skipMigrations = this.flags["skip-migrations"] === true;
+
+    for (const name of steps) {
+      if (name === "migrate" && skipMigrations) {
+        this.newLine();
+        this.warn("! migrate skipped (--skip-migrations)");
+        continue;
+      }
+
+      this.newLine();
+      this.section(name);
+      const argv = name === "inertia:build" ? [name, "--production"] : [name];
+      const { code, output } = await runner.callInProcess(argv);
+      if (output.trim()) this.line(output.trimEnd());
+      if (code !== 0) throw new Error(`${name} failed — stopping before the release completes.`);
+    }
+  }
+
+  // ── Phase 3 — verify ────────────────────────────────────────────────────────
+
+  /** The doctor again, now that migrations have run and the schema has one story. */
+  private async _verify(app: Application): Promise<void> {
+    this.newLine();
+    this.section("Verify");
+    await this._doctor(app, "verify");
+  }
+
+  /**
+   * Run the doctor's checks directly rather than through the command, so a failure
+   * is a value this pipeline can report on rather than a process exit.
+   */
+  private async _doctor(app: Application, phase: string): Promise<void> {
+    const report = await runDoctor(app);
+    const failures = report.filter((e) => e.result.status === "fail");
+    const warnings = report.filter((e) => e.result.status === "warn");
+
+    for (const { check, result } of [...failures, ...warnings]) {
+      const line = `${result.status === "fail" ? "✗" : "!"} ${check.label} — ${result.message}`;
+      if (result.status === "fail") this.error(line);
+      else this.warn(line);
+      if (result.fix) this.line(`    fix: ${result.fix}`);
+    }
+
+    if (failures.length > 0) {
+      throw new Error(
+        `${failures.length} check(s) failed at ${phase}. ` +
+          `Nothing further has run — fix these and deploy again.`,
+      );
+    }
+    this.line(
+      `✓ ${report.length} checks passed${warnings.length ? `, ${warnings.length} warning(s)` : ""}`,
+    );
+  }
+
+  // ── Phase 4 — probe, when asked ─────────────────────────────────────────────
+
+  /**
+   * A real handshake against the deployed site. Off unless asked, because the
+   * release this command just built is not live until the service restarts — and
+   * the framework does not do that. Useful on a re-deploy, or from a second
+   * terminal after the restart.
+   */
+  private async _probe(app: Application, target: string): Promise<void> {
+    const declared = this._target(app, target);
+    const url = (this.flags["probe"] as string | undefined) ?? undefined;
+    if (!url) return;
+    const against = url === "true" ? declared?.url : url;
+    if (!against) {
+      throw new Error(
+        `--probe needs a URL, and config/deploy.ts declares no \`url\` for ${target}.`,
+      );
+    }
+
+    this.newLine();
+    this.section("Probe");
+    const paths = app.webSocketPaths();
+    if (paths.length === 0) {
+      this.line("✓ no WebSocket paths registered — nothing to probe.");
+      return;
+    }
+
+    const results = await probeTransport(against, paths);
+    let failures = 0;
+    for (const result of results) {
+      const line = `${result.ok ? "✓" : "✗"} ${result.url} — ${result.message}`;
+      if (result.ok) this.line(line);
+      else {
+        this.error(line);
+        failures++;
+      }
+      if (result.fix) this.line(`    fix: ${result.fix}`);
+    }
+    if (failures > 0) throw new Error(`${failures} transport path(s) are not reachable.`);
+  }
+
+  // ── --dry-run ───────────────────────────────────────────────────────────────
+
+  private _printPlan(app: Application, target: string, steps: string[]): void {
+    const actual = deployEnv();
+    this.line(
+      `APP_ENV       ${actual || "(unset)"}${actual === target ? "" : `  ✗ expected ${target}`}`,
+    );
+    this.line(`preflight     config validators, then ${"doctor"} checks`);
+    for (const name of steps) {
+      const skipped = name === "migrate" && this.flags["skip-migrations"] === true;
+      this.line(`step          ${name}${skipped ? "  (skipped: --skip-migrations)" : ""}`);
+    }
+    this.line(`verify        doctor checks again`);
+    this.newLine();
+    // Worth saying out loud: the app booted to get here, so "nothing ran" is not
+    // quite true — providers booted and the database connection was opened.
+    this.warn("Dry run — no steps executed. (The app was booted to resolve them.)");
+  }
+}
+
+/**
+ * Build the command for one deploy target.
+ *
+ * A subclass rather than the closure seam (`runner.registerCommand`), because that
+ * one hardcodes `needsApp = false` and this pipeline needs a booted app for the
+ * doctor, the config and the registered WebSocket paths.
+ *
+ * @internal Called by the runner for each declared target.
+ */
+export function makeDeployCommand(target: string): DeployCommandClass {
+  const Target = class extends DeployCommand {
+    static override commandName = `deploy:${target}`;
+    static override description = `Run the ${target} release pipeline`;
+    static override target = target;
+  };
+  Object.defineProperty(Target, "name", { value: `DeployCommand<${target}>` });
+  return Target;
+}
+
+/**
+ * A concrete deploy command. `typeof DeployCommand` cannot be used: the base is
+ * abstract, and the runner's registry holds constructible classes.
+ *
+ * @internal
+ */
+export interface DeployCommandClass {
+  new (): DeployCommand;
+  commandName: string;
+  description?: string;
+  needsApp?: boolean;
+  args: typeof DeployCommand.args;
+  flags: typeof DeployCommand.flags;
+  target: string;
+}

package/src/command/builtin/DevCommand.ts

@@ -0,0 +1,88 @@
+/**
+ * `bun zt dev` — the server plus every process a provider or the app registered,
+ * in one terminal, each in its own tab.
+ */
+import { ServeCommand } from "./ServeCommand.ts";
+import type { FlagDef } from "../Command.ts";
+
+/**
+ * `bun zt dev` — start dev mode: the server, the file watcher, and every
+ * registered dev process, drawn as a deck of tabs. Aliased as `d`.
+ *
+ * @remarks
+ * This *is* `serve --dev`, with the flags that only make sense when a deck is on
+ * screen. It subclasses rather than reimplements so the two cannot drift: an app
+ * that runs `serve --dev` in a script gets the same supervisor, the same
+ * processes and the same restart behaviour as one that runs `dev`.
+ *
+ * The flag names deliberately match the conventional ones, so a developer
+ * arriving from another framework needs no translation.
+ *
+ * @example
+ * ```bash
+ * bun zt dev                     # server + everything registered
+ * bun zt dev --only=server,queue # just these two
+ * bun zt dev --without=queue     # everything but the worker
+ * bun zt dev --list              # what would run, and who registered it
+ * bun zt dev --stream            # no TUI — prefixed lines, pipe-friendly
+ * ```
+ *
+ * @category Serving
+ */
+export class DevCommand extends ServeCommand {
+  static override commandName = "dev";
+  static override aliases = ["d"];
+  static override description = "Start dev mode: the server plus every registered dev process";
+  static override needsApp = true;
+
+  static override flags: FlagDef[] = [
+    { name: "port", short: "p", type: "number", description: "Port to listen on", default: 3000 },
+    {
+      name: "force",
+      type: "boolean",
+      description: "If the port is busy, stop the process holding it",
+      default: false,
+    },
+    {
+      name: "auto-port",
+      type: "boolean",
+      description: "If the port is busy, start on the next free port",
+      default: false,
+    },
+    {
+      name: "only",
+      type: "string",
+      description: "Run only these processes, comma-separated (e.g. server,queue)",
+    },
+    {
+      name: "without",
+      type: "string",
+      description: "Run everything except these processes, comma-separated",
+    },
+    {
+      name: "list",
+      type: "boolean",
+      description: "Print what would run, with the provider that registered each",
+      default: false,
+    },
+    {
+      name: "force-build",
+      type: "boolean",
+      description: "Rebuild assets even when the build cache says they are current",
+      default: false,
+    },
+    {
+      name: "stream",
+      type: "boolean",
+      description: "Interleave prefixed output instead of drawing tabs",
+      default: false,
+    },
+  ];
+
+  override async run(): Promise<void> {
+    // `dev` is `serve --dev` — set the flag the parent branches on rather than
+    // duplicating its port resolution, asset config and banner.
+    this.flags["dev"] = true;
+    await super.run();
+  }
+}

package/src/command/builtin/DoctorCommand.ts

@@ -0,0 +1,97 @@
+/**
+ * `bun zt doctor` — run every static sanity check against this app and print
+ * the findings with their fixes. Exits 1 when anything is broken outright.
+ *
+ * With `--url`, it also probes the deployed app's WebSocket transport from the outside,
+ * through whatever proxy is in front of it. That is the only way to see the failures that
+ * leave the app healthy from the inside and inert in the browser.
+ */
+import { Command } from "../Command.ts";
+import type { Application } from "../../application/Application.ts";
+import { runDoctor } from "../../doctor/AppDoctor.ts";
+import type { DoctorReportEntry } from "../../doctor/AppDoctor.ts";
+import { probeTransport } from "../../doctor/TransportProbe.ts";
+
+export class DoctorCommand extends Command {
+  static override commandName = "doctor";
+  static override description = "Check this app for silent misconfigurations";
+  static override needsApp = true;
+  static override flags = [
+    {
+      name: "url",
+      type: "string" as const,
+      description:
+        "Also probe the deployed app's WebSocket transport at this public URL, as a browser would",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    if (!app) throw new Error("doctor needs a booted application.");
+
+    const report = await runDoctor(app);
+    this.section("Doctor");
+    for (const entry of report) this._print(entry);
+
+    const probeFailures = await this._probeTransport(app);
+
+    const warns = report.filter((e) => e.result.status === "warn").length;
+    const fails = report.filter((e) => e.result.status === "fail").length + probeFailures;
+    this.newLine();
+    // Throw rather than `process.exit(1)` — same exit code from the CLI (the runner
+    // converts it), but composable. Exiting here killed any caller running the
+    // doctor through `callInProcess` before its buffered report could be flushed,
+    // so the failure arrived with no output explaining it.
+    if (fails > 0) {
+      throw new Error(`${fails} failing, ${warns} warning(s), ${report.length} check(s).`);
+    } else if (warns > 0) {
+      this.warn(`${warns} warning(s), ${report.length} check(s).`);
+    } else {
+      this.info(`All ${report.length} checks passed.`);
+    }
+  }
+
+  /**
+   * Probe each registered WebSocket path through the public URL. Returns the number of
+   * failures, so they weigh on the exit code the same as a failing check.
+   */
+  private async _probeTransport(app: Application): Promise<number> {
+    const url = this.flags["url"] as string | undefined;
+    if (!url) return 0;
+
+    const paths = app.webSocketPaths();
+    this.newLine();
+    this.section("Transport");
+
+    if (paths.length === 0) {
+      this.line("✓ No WebSocket paths registered — nothing to probe.");
+      return 0;
+    }
+    if (paths.every((p) => p === "*")) {
+      this.warn("! Only catch-all WebSocket handlers are registered; no path to probe.");
+      return 0;
+    }
+
+    const results = await probeTransport(url, paths);
+    let failures = 0;
+    for (const result of results) {
+      const line = `${result.ok ? "✓" : "✗"} ${result.url} — ${result.message}`;
+      if (result.ok) this.line(line);
+      else {
+        this.error(line);
+        failures++;
+      }
+      if (result.fix) this.line(`    fix: ${result.fix}`);
+    }
+    return failures;
+  }
+
+  private _print({ check, result }: DoctorReportEntry): void {
+    const mark = result.status === "ok" ? "✓" : result.status === "warn" ? "!" : "✗";
+    const line = `${mark} ${check.label} — ${result.message}`;
+    if (result.status === "ok") this.line(line);
+    else if (result.status === "warn") this.warn(line);
+    else this.error(line);
+    if (result.fix) this.line(`    fix: ${result.fix}`);
+  }
+}

package/src/command/builtin/MakeCommandCommand.ts

@@ -79,6 +79,8 @@ export class MakeCommandCommand extends Command {
         // Bun.write() creates any missing parent directories, so no mkdir is needed.
         return Bun.write(path, commandStub(name)).then(() => {
           this.info(`Created: ${path}`);
+          // app/commands/ is auto-discovered, so the command is immediately runnable.
+          this.info(`Run it with: bun zt.ts ${toKebab(name)}`);
         });
       });
   }

package/src/command/builtin/RouteTypesCommand.ts

@@ -0,0 +1,56 @@
+import { Command } from "../Command.ts";
+import type { FlagDef } from "../Command.ts";
+import { Router } from "../../router/Router.ts";
+import { writeRouteTypes, ROUTE_TYPES_FILE } from "../../router/routeTypes.ts";
+
+/**
+ * `bun zt route:types` — write `types/routes.generated.ts`, the name → pattern
+ * map that makes `route()` type-checked.
+ *
+ * Boots the application (`needsApp`) and reads `Router.namedRoutes`, so routes
+ * a provider registers programmatically and names set via a route file's
+ * `export const meta` are included — not just what the file-router's naming
+ * convention would produce.
+ *
+ * Commit the generated file: editors and CI need it without booting the app.
+ * `zt dev` refreshes it on every restart, and `--check` fails when the file on
+ * disk no longer matches the routes, which is the CI gate that keeps it honest.
+ *
+ * @category Diagnostics
+ */
+export class RouteTypesCommand extends Command {
+  static commandName = "route:types";
+  static description = "Generate types/routes.generated.ts for typed route() names";
+  static needsApp = true;
+  static args = [];
+  static flags: FlagDef[] = [
+    {
+      name: "check",
+      type: "boolean",
+      description: "Fail instead of writing when the generated file is out of date (for CI)",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const check = this.flags["check"] as boolean;
+    const result = await writeRouteTypes(Router.namedRoutes, { check });
+
+    if (check) {
+      if (result.changed) {
+        this.error(`${result.path} is out of date. Run: bun zt route:types`);
+        throw new Error("Route types are out of date.");
+      }
+      this.info(`${result.path} is up to date (${result.count} named routes).`);
+      return;
+    }
+
+    if (result.count === 0) {
+      this.warn("No named routes found — the generated map is empty.");
+    }
+
+    this.info(
+      `${result.changed ? "Wrote" : "Unchanged"}: ${ROUTE_TYPES_FILE} (${result.count} named routes)`,
+    );
+  }
+}