@zerotal/core 1.0.0

package/src/dev/DevWsServer.ts

@@ -0,0 +1,45 @@
+/**
+ * Dev-reload WebSocket server.
+ *
+ * Manages the set of browser tabs connected to the /__dev/ws endpoint.
+ * When the DevOrchestrator detects a file change it writes "reload\n" to
+ * the dev-worker's stdin; ServeCommand reads that line and calls broadcast()
+ * here, pushing the message to every connected tab.
+ *
+ * The browser client (injected by InertiaProvider) reconnects automatically
+ * on close, so server restarts never create a reload loop.
+ */
+
+/** A connected dev-reload browser socket. */
+type DevSocket = {
+  data: Record<string, unknown>;
+  send(message: string): void;
+};
+
+const _clients = new Set<DevSocket>();
+
+/** Register a newly opened dev-reload socket. */
+export function open(socket: DevSocket): void {
+  _clients.add(socket);
+}
+
+/** Forget a closed dev-reload socket. */
+export function close(socket: DevSocket): void {
+  _clients.delete(socket);
+}
+
+/**
+ * Push a message to every connected dev browser tab.
+ * Stale sockets (closed tabs) are pruned lazily on send failure.
+ */
+export function broadcast(message: string): void {
+  const staleSockets: DevSocket[] = [];
+  for (const socket of _clients) {
+    try {
+      socket.send(message);
+    } catch {
+      staleSockets.push(socket);
+    }
+  }
+  for (const socket of staleSockets) _clients.delete(socket);
+}

package/src/dev/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Dev-only build and live-reload tooling (the `@zerotal/core/dev` subpath):
+ * the build hook, the reload middleware that injects the HMR client snippet,
+ * and the CSS/JS bundling helpers. Owns `Bun.build`, so it is kept off the
+ * kernel barrel and is inactive outside the dev worker.
+ *
+ * @internal — framework dev-server wiring; not part of the app-facing API.
+ *
+ * @packageDocumentation
+ */
+export { registerDevBuildHook } from "./DevBuildHook.ts";
+export type { BuildHookFn, BuildResult } from "./DevBuildHook.ts";
+export { DevReloadMiddleware, registerDevHtmlSnippet } from "./DevReloadMiddleware.ts";
+export type { DevHtmlSnippet } from "./DevReloadMiddleware.ts";
+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";
+// `AppAssetsConfig` (the app-level assets config shape) lives on @zerotal/core/config.

package/src/dev/reloadClient.ts

@@ -0,0 +1,39 @@
+/**
+ * The browser half of dev live-reload: an inline script injected into dev HTML
+ * responses. It connects to `/__dev/ws` and reloads the tab on two signals.
+ *
+ *   • `reload` — the orchestrator finished a rebuild triggered by a frontend
+ *     change and pushed it straight through the worker.
+ *
+ *   • `version:<token>` — sent by the worker the moment a socket opens. A
+ *     backend change also rebuilds assets, but it restarts the worker, and the
+ *     restart kills every socket: a `reload` pushed at that instant reaches
+ *     nobody, because the tab only reconnects a second later. So the tab
+ *     remembers the build token it first saw and reloads when a reconnect
+ *     reports a different one. That is how a rebuild riding along with a
+ *     server restart still reaches the browser.
+ *
+ * Reconnecting on close (rather than on error) is what keeps a server restart
+ * from wedging the page without spinning up a reload loop.
+ *
+ * Exported as a string because it is injected inline: `DevReloadMiddleware`
+ * rewrites HTML responses with it for every view layer, and Inertia bakes it
+ * into its cached template so streamed pages need no body rewrite.
+ */
+export const DEV_RELOAD_CLIENT: string =
+  `<script>(function(){` +
+  `var proto=location.protocol==='https:'?'wss:':'ws:';` +
+  `var build=null;` +
+  `function connect(){` +
+  `var ws=new WebSocket(proto+'//'+location.host+'/__dev/ws');` +
+  `ws.onmessage=function(e){` +
+  `var d=e.data;` +
+  `if(d==='reload'){location.reload();return;}` +
+  `if(d.indexOf('version:')===0){` +
+  `var v=d.slice(8);` +
+  `if(!v)return;` +
+  `if(build===null)build=v;` +
+  `else if(build!==v)location.reload();` +
+  `}};` +
+  `ws.onclose=function(){setTimeout(connect,1000);};` +
+  `}connect();})();</script>`;

package/src/env/Def.ts

@@ -0,0 +1,232 @@
+/**
+ * `Def<T>` — the typed field definition produced by the `t` env builder, plus
+ * the field-specification and error types that back environment validation.
+ */
+
+// ── Required sentinel ─────────────────────────────────────────────────────────
+// Used as the third argument to .when() so the API reads naturally:
+//   STRIPE_KEY: t.string().when('NODE_ENV', 'production', t.required())
+
+const _REQUIRED = Symbol.for("@zerotal/env:required");
+
+/** The type of the {@link REQUIRED_MARKER} sentinel passed to `.when()`. */
+export type RequiredMarker = typeof _REQUIRED;
+
+/** Sentinel marking a field as required under a `.when()` condition. */
+export const REQUIRED_MARKER: RequiredMarker = _REQUIRED;
+
+// ── Internal field specification ──────────────────────────────────────────────
+
+/** The set of value kinds a field can declare. */
+export type FieldType = "string" | "number" | "boolean" | "enum" | "url" | "port";
+
+/** @internal A single conditional-requirement rule attached by `.when()`. */
+export interface ConditionSpec {
+  field: string;
+  value: string;
+  thenRequired: boolean;
+}
+
+/** @internal The fully resolved specification a `Def<T>` carries into validation. */
+export interface FieldSpec {
+  type: FieldType;
+  required: boolean;
+  defaultValue: unknown; // Already typed — skip re-parsing in parse().
+  enumValues?: readonly string[];
+  conditions: ConditionSpec[];
+}
+
+// ── Validation error ──────────────────────────────────────────────────────────
+
+/** A single field-level validation failure. Collected before the final throw. */
+export class EnvFieldError {
+  constructor(
+    readonly key: string,
+    readonly message: string,
+  ) {}
+
+  format(): string {
+    return `  ✗  ${this.key.padEnd(20)} ${this.message}`;
+  }
+}
+
+// ── Def<T> ────────────────────────────────────────────────────────────────────
+
+/**
+ * A typed field definition produced by the `t` builder.
+ * Carry it directly in `EnvSchema.define()` — the generic `T` is inferred automatically.
+ *
+ * @example
+ * ```ts
+ * PORT:     t.number().default(3000)      // Def<number>
+ * DB_HOST:  t.string().required()         // Def<string>
+ * NODE_ENV: t.enum([...]).required()      // Def<'development'|'production'|'testing'>
+ * API_KEY:  t.string().when('NODE_ENV', 'production', t.required())  // Def<string|undefined>
+ * ```
+ */
+export class Def<T> {
+  /** @internal — phantom property for TypeScript inference only, never set at runtime */
+  declare readonly _output: T;
+
+  /** @internal */
+  readonly _spec: FieldSpec;
+
+  constructor(spec: FieldSpec) {
+    this._spec = spec;
+  }
+
+  // ── Modifiers ────────────────────────────────────────────────────────────────
+
+  /**
+   * Mark the field as required.
+   * The output type becomes `NonNullable<T>` — `undefined` is removed.
+   *
+   * @example
+   * ```ts
+   * DB_HOST: t.string().required()  // string (throws at boot if missing)
+   * ```
+   */
+  required(): Def<NonNullable<T>> {
+    return new Def<NonNullable<T>>({ ...this._spec, required: true });
+  }
+
+  /**
+   * Provide a fallback value when the env variable is absent.
+   * The output type becomes `NonNullable<T>` — `undefined` is removed.
+   *
+   * @example
+   * ```ts
+   * PORT:  t.number().default(3000)         // number — always present
+   * DEBUG: t.boolean().default(false)       // boolean
+   * ```
+   */
+  default(value: NonNullable<T>): Def<NonNullable<T>> {
+    return new Def<NonNullable<T>>({
+      ...this._spec,
+      required: true,
+      defaultValue: value,
+    });
+  }
+
+  /**
+   * Make the field conditionally required.
+   * When `conditionField === conditionValue` at runtime, the field is validated
+   * as required. Otherwise it remains optional.
+   *
+   * The TypeScript type stays `T` (potentially `undefined`) because the condition
+   * is evaluated at runtime — access the value with a null-check or after calling
+   * EnvSchema.define() in the appropriate environment.
+   *
+   * Pass `t.required()` as the third argument (or omit — required is the default action).
+   *
+   * @example
+   * ```ts
+   * STRIPE_SECRET: t.string().when('NODE_ENV', 'production', t.required())
+   * ```
+   */
+  when(
+    conditionField: string,
+    conditionValue: string,
+    rule?: RequiredMarker | Def<unknown>,
+  ): Def<T> {
+    const thenRequired =
+      rule === undefined ||
+      rule === REQUIRED_MARKER ||
+      (rule instanceof Def && rule._spec.required);
+
+    return new Def<T>({
+      ...this._spec,
+      conditions: [
+        ...this._spec.conditions,
+        { field: conditionField, value: conditionValue, thenRequired },
+      ],
+    });
+  }
+
+  // ── Internal parse ────────────────────────────────────────────────────────────
+
+  /**
+   * @internal
+   * Parse and validate a raw env string, respecting conditions.
+   * Throws `EnvFieldError` on failure (collected by EnvSchema before the final throw).
+   */
+  _parse(key: string, raw: string | undefined, allEnv: Record<string, string | undefined>): T {
+    // Evaluate conditional requirements
+    for (const condition of this._spec.conditions) {
+      if (allEnv[condition.field] === condition.value && condition.thenRequired) {
+        if (raw === undefined || raw === "") {
+          throw new EnvFieldError(
+            key,
+            `required when ${condition.field}="${condition.value}" but is missing`,
+          );
+        }
+      }
+    }
+
+    // Apply default
+    if (raw === undefined || raw === "") {
+      if (this._spec.defaultValue !== undefined) {
+        return this._spec.defaultValue as T;
+      }
+      if (this._spec.required) {
+        throw new EnvFieldError(key, "is required but missing or empty");
+      }
+      return undefined as T;
+    }
+
+    // Type coercion & validation
+    switch (this._spec.type) {
+      case "string":
+        return raw as T;
+
+      case "url": {
+        try {
+          new URL(raw);
+        } catch {
+          throw new EnvFieldError(key, `must be a valid URL — got: "${raw}"`);
+        }
+        return raw as T;
+      }
+
+      case "number":
+      case "port": {
+        const parsed = Number(raw);
+        if (Number.isNaN(parsed) || !Number.isFinite(parsed)) {
+          throw new EnvFieldError(key, `must be a number — got: "${raw}"`);
+        }
+        if (
+          this._spec.type === "port" &&
+          (parsed < 1 || parsed > 65535 || !Number.isInteger(parsed))
+        ) {
+          throw new EnvFieldError(key, `must be a valid port number (1–65535) — got: ${parsed}`);
+        }
+        return parsed as T;
+      }
+
+      case "boolean": {
+        const normalized = raw.toLowerCase();
+        if (normalized === "true" || normalized === "1" || normalized === "yes") return true as T;
+        if (normalized === "false" || normalized === "0" || normalized === "no") return false as T;
+        throw new EnvFieldError(key, `must be a boolean (true/false/1/0/yes/no) — got: "${raw}"`);
+      }
+
+      case "enum": {
+        const values = this._spec.enumValues!;
+        if (!values.includes(raw)) {
+          throw new EnvFieldError(key, `must be one of [${values.join(", ")}] — got: "${raw}"`);
+        }
+        return raw as T;
+      }
+    }
+  }
+}
+
+// ── Infer the output type of a schema map ─────────────────────────────────────
+
+/** Infer the concrete type of a single `Def<T>`. */
+export type InferDef<D> = D extends Def<infer T> ? T : never;
+
+/** Infer the full output object type from an `EnvSchema.define()` schema map. */
+export type EnvOutput<S extends Record<string, Def<unknown>>> = {
+  readonly [K in keyof S]: InferDef<S[K]>;
+};

package/src/env/EnvSchema.ts

@@ -0,0 +1,105 @@
+/**
+ * `EnvSchema` — defines and validates a strict, fully-typed environment schema
+ * at import time, collecting every failure into a single readable error.
+ */
+import { Def, EnvFieldError } from "./Def.ts";
+import type { EnvOutput } from "./Def.ts";
+import { ZerotalError } from "../errors/ZerotalError.ts";
+
+// ── Schema-level error ────────────────────────────────────────────────────────
+
+/**
+ * Thrown by `EnvSchema.define()` when one or more environment variables
+ * fail validation. Contains all failures, not just the first.
+ */
+export class EnvSchemaError extends ZerotalError {
+  readonly errors: EnvFieldError[];
+
+  constructor(errors: EnvFieldError[]) {
+    super(EnvSchemaError._format(errors), "E_ENV_SCHEMA", 500);
+    this.errors = errors;
+  }
+
+  private static _format(errors: EnvFieldError[]): string {
+    const lines = [
+      "",
+      "\x1b[31m[Zerotal Env]\x1b[0m Environment validation failed — the application cannot start.",
+      "",
+      ...errors.map((error) => error.format()),
+      "",
+      "Check your \x1b[33m.env\x1b[0m file and try again.",
+      "",
+    ];
+    return lines.join("\n");
+  }
+}
+
+// ── EnvSchema ─────────────────────────────────────────────────────────────────
+
+/**
+ * Define and validate a strict environment schema at import time.
+ *
+ * The schema is parsed once when the module is first imported. If any variable
+ * fails validation, the application refuses to start and prints every failure
+ * in a single readable error — not just the first one.
+ *
+ * All fields of the returned object are **read-only** and **fully typed**.
+ *
+ * @example
+ * ```ts
+ * // app/config/env.ts
+ * import { EnvSchema, t } from '@zerotal/core/env';
+ *
+ * export const env = EnvSchema.define({
+ *   PORT:          t.number().default(3000),
+ *   NODE_ENV:      t.enum(['development', 'production', 'testing']).required(),
+ *   DB_HOST:       t.string().required(),
+ *   DB_PASS:       t.string().when('NODE_ENV', 'production', t.required()),
+ *   STRIPE_SECRET: t.string().when('NODE_ENV', 'production', t.required()),
+ *   DEBUG:         t.boolean().default(false),
+ *   BASE_URL:      t.url().default('http://localhost:3000'),
+ * });
+ *
+ * // Anywhere else:
+ * import { env } from './config/env.ts';
+ * console.log(env.PORT);     // number — never undefined
+ * console.log(env.DB_HOST);  // string — validated at boot
+ * ```
+ */
+export const EnvSchema = {
+  /**
+   * Parse and validate all env variables against the schema.
+   *
+   * @param schema  A plain object whose values are `Def<T>` instances from `t.*`.
+   * @param source  Optional env source (defaults to `Bun.env`). Pass a plain
+   *                object in tests to avoid polluting the real environment.
+   *
+   * @throws EnvSchemaError when any variable fails validation.
+   */
+  define<S extends Record<string, Def<unknown>>>(
+    schema: S,
+    source: Record<string, string | undefined> = Bun.env as Record<string, string | undefined>,
+  ): EnvOutput<S> {
+    const errors: EnvFieldError[] = [];
+    const result: Record<string, unknown> = {};
+
+    for (const [key, def] of Object.entries(schema)) {
+      const raw = source[key];
+      try {
+        result[key] = def._parse(key, raw, source);
+      } catch (error) {
+        if (error instanceof EnvFieldError) {
+          errors.push(error);
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      throw new EnvSchemaError(errors);
+    }
+
+    return Object.freeze(result) as EnvOutput<S>;
+  },
+} as const;

package/src/env/index.ts

@@ -0,0 +1,34 @@
+/**
+ * The `@zerotal/core/env` subpath — a strict, fully-typed environment schema.
+ *
+ * Declare every variable your app reads with the {@link t} field builder
+ * (`t.string()`, `t.number()`, `t.enum([...])`, …) and hand the map to
+ * {@link EnvSchema.define}. The schema is parsed and validated once at import
+ * time: missing required vars, bad numbers, invalid URLs, and out-of-range
+ * ports all fail the boot with a single {@link EnvSchemaError} that lists every
+ * failure at once. The returned object is frozen and precisely typed, so
+ * `env.PORT` is `number` (never `undefined`) and enum fields narrow to their
+ * literals.
+ *
+ * @example
+ * ```ts
+ * import { EnvSchema, t } from "@zerotal/core/env";
+ *
+ * export const env = EnvSchema.define({
+ *   PORT:     t.number().default(3000),
+ *   NODE_ENV: t.enum(["development", "production", "testing"]).required(),
+ *   DB_HOST:  t.string().required(),
+ *   DB_PASS:  t.string().when("NODE_ENV", "production", t.required()),
+ *   BASE_URL: t.url().default("http://localhost:3000"),
+ * });
+ *
+ * console.log(env.PORT);    // number — never undefined
+ * console.log(env.DB_HOST); // string — validated at boot
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { EnvSchema, EnvSchemaError } from "./EnvSchema.ts";
+export { t } from "./t.ts";
+export { Def, EnvFieldError } from "./Def.ts";
+export type { EnvOutput, InferDef, FieldType } from "./Def.ts";

package/src/env/t.ts

@@ -0,0 +1,128 @@
+/**
+ * The `t` env-field builder — the entry point that produces typed `Def<T>`
+ * field definitions (`t.string()`, `t.number()`, `t.enum([...])`, …) for use
+ * with `EnvSchema.define()`.
+ */
+import { Def, REQUIRED_MARKER } from "./Def.ts";
+import type { RequiredMarker, FieldType, FieldSpec } from "./Def.ts";
+
+function _def<T>(type: FieldType, extra?: Partial<FieldSpec>): Def<T> {
+  return new Def<T>({ type, required: false, defaultValue: undefined, conditions: [], ...extra });
+}
+
+/**
+ * The `t` builder — the entry point for all field type definitions.
+ *
+ * Every method returns a `Def<T>` which can be further configured with
+ * `.required()`, `.default(val)`, or `.when(field, value, t.required())`.
+ *
+ * @example
+ * ```ts
+ * import { EnvSchema, t } from '@zerotal/core/env';
+ *
+ * export const env = EnvSchema.define({
+ *   PORT:     t.number().default(3000),
+ *   NODE_ENV: t.enum(['development', 'production', 'testing']).required(),
+ *   DB_HOST:  t.string().required(),
+ *   DB_PASS:  t.string().when('NODE_ENV', 'production', t.required()),
+ *   DEBUG:    t.boolean().default(false),
+ *   BASE_URL: t.url().required(),
+ * });
+ * ```
+ */
+export const t = {
+  /**
+   * A plain string environment variable.
+   *
+   * @example
+   * ```ts
+   * APP_NAME:  t.string().default('Zerotal App')  // string
+   * DB_HOST:   t.string().required()            // string
+   * REDIS_URL: t.string()                       // string | undefined
+   * ```
+   */
+  string(): Def<string | undefined> {
+    return _def<string | undefined>("string");
+  },
+
+  /**
+   * A numeric environment variable (parsed with `Number()`).
+   * Non-numeric values cause a boot-time error.
+   *
+   * @example
+   * ```ts
+   * PORT:    t.number().default(3000)  // number
+   * TIMEOUT: t.number().required()     // number
+   * ```
+   */
+  number(): Def<number | undefined> {
+    return _def<number | undefined>("number");
+  },
+
+  /**
+   * A boolean environment variable.
+   * Accepts: `true`, `false`, `1`, `0`, `yes`, `no` (case-insensitive).
+   *
+   * @example
+   * ```ts
+   * DEBUG:     t.boolean().default(false)  // boolean
+   * CACHE_HOT: t.boolean().required()      // boolean
+   * ```
+   */
+  boolean(): Def<boolean | undefined> {
+    return _def<boolean | undefined>("boolean");
+  },
+
+  /**
+   * An enum-constrained string variable.
+   * The value must be one of the provided literals — anything else causes a boot-time error.
+   * Pass the array `as const` (or inline) for accurate literal type inference.
+   *
+   * @example
+   * ```ts
+   * NODE_ENV: t.enum(['development', 'production', 'testing']).required()
+   * // output: 'development' | 'production' | 'testing'
+   * ```
+   */
+  enum<const V extends readonly string[]>(values: V): Def<V[number] | undefined> {
+    return _def<V[number] | undefined>("enum", { enumValues: values });
+  },
+
+  /**
+   * A URL-validated string. Parses with `new URL()` — invalid values cause a boot-time error.
+   *
+   * @example
+   * ```ts
+   * API_BASE: t.url().required()       // string (guaranteed valid URL)
+   * CDN_URL:  t.url().default('...')   // string
+   * ```
+   */
+  url(): Def<string | undefined> {
+    return _def<string | undefined>("url");
+  },
+
+  /**
+   * A validated TCP port number (integer 1–65535).
+   *
+   * @example
+   * ```ts
+   * PORT: t.port().default(3000)   // number
+   * ```
+   */
+  port(): Def<number | undefined> {
+    return _def<number | undefined>("port");
+  },
+
+  /**
+   * Sentinel value for use as the third argument to `.when()`.
+   * Signals that the field is required under the given condition.
+   *
+   * @example
+   * ```ts
+   * STRIPE_KEY: t.string().when('NODE_ENV', 'production', t.required())
+   * ```
+   */
+  required(): RequiredMarker {
+    return REQUIRED_MARKER;
+  },
+} as const;

package/src/errors/ConfigError.ts

@@ -0,0 +1,12 @@
+/**
+ * The error raised for invalid or missing configuration — a bad config file,
+ * an unknown key, or a value that fails its schema.
+ */
+import { ZerotalError } from "./ZerotalError.ts";
+
+/** Raised when configuration is invalid or missing. */
+export class ConfigError extends ZerotalError {
+  constructor(message: string) {
+    super(message, "E_CONFIG_ERROR", 500);
+  }
+}