@zerotal/core 1.0.0

package/src/facade/Facade.ts

@@ -0,0 +1,101 @@
+/**
+ * The facade factory: wraps a named container binding in a Proxy so it can be
+ * used like a static object while still resolving lazily from the live
+ * container on every access.
+ */
+import type { Application } from "../application/Application.ts";
+import { currentApp } from "../application/currentApp.ts";
+import type { ContainerBindings } from "../container/types.ts";
+import {
+  FacadeAccessedBeforeBootError,
+  FacadeBindingMissingError,
+} from "../errors/ContainerErrors.ts";
+
+/**
+ * Create a typed facade over a named container binding.
+ *
+ * The returned object delegates every property access to the live instance
+ * resolved from the container **on each access** — lazy, never cached at
+ * module load time.  This means:
+ *
+ *  - Importing `Config` before `Application.boot()` is safe.
+ *  - The binding is always the most recently registered singleton.
+ *
+ * Prerequisites:
+ *  - `Application.create()` must have been called.
+ *  - The singleton must have been pre-resolved (e.g. via `make()` in
+ *    `onBooting()`) because `makeSync()` only works for resolved singletons.
+ *
+ * Methods are automatically bound to the live instance so `this` is correct
+ * inside them regardless of how the caller stores the reference.
+ *
+ * @param key  The container binding name the facade resolves on each access.
+ * @returns A proxy typed as the bound instance; every access resolves live.
+ * @throws {FacadeAccessedBeforeBootError} If accessed before the application is
+ * created (e.g. at module scope on import).
+ * @throws {FacadeBindingMissingError} If the application exists but no binding is
+ * registered for `key` (a missing ServiceProvider).
+ *
+ * @example
+ * ```ts
+ * // packages/core/src/facade/facades/Config.ts
+ * export const Config = createFacade('config');
+ *
+ * // Anywhere in the application (after boot):
+ * Config.get('app.name');
+ * await Events.emit(new UserRegistered(id));
+ * ```
+ */
+/**
+ * Properties the language itself probes, which must never resolve the binding.
+ *
+ * Returning a facade from an `async` function makes the runtime read `.then` to
+ * decide whether it is a thenable. Answering that with a container lookup meant
+ * a facade could not be returned from an async function at all without throwing
+ * — from inside promise resolution, with a stack pointing at the proxy rather
+ * than at the caller. `Symbol.toPrimitive` and friends are the same trap for
+ * string coercion and inspection.
+ */
+const _PROBES: Array<string | symbol> = [
+  "then",
+  "catch",
+  "finally",
+  Symbol.toPrimitive,
+  Symbol.toStringTag,
+  Symbol.iterator,
+  Symbol.asyncIterator,
+  "inspect",
+  "constructor",
+  "nodejs.util.inspect.custom",
+];
+
+export function createFacade<K extends keyof ContainerBindings>(key: K): ContainerBindings[K] {
+  return new Proxy({} as ContainerBindings[K], {
+    get(_target, prop: string | symbol) {
+      // A probe is the runtime asking what this object *is*, not the application
+      // asking the binding to do something. Answer "nothing special" without
+      // touching the container.
+      if (_PROBES.includes(prop)) return undefined;
+
+      // Distinguish "app not created yet" (module-scope misuse) from "binding not
+      // registered" (a missing ServiceProvider) — they need very different fixes.
+      let app: Application;
+      try {
+        app = currentApp();
+      } catch {
+        throw new FacadeAccessedBeforeBootError(String(key));
+      }
+      let instance: ContainerBindings[K];
+      try {
+        instance = app.container.makeSync(key);
+      } catch {
+        throw new FacadeBindingMissingError(String(key));
+      }
+      const value = (instance as unknown as Record<string | symbol, unknown>)[prop];
+      if (typeof value === "function") {
+        return (value as (...args: unknown[]) => unknown).bind(instance);
+      }
+      return value;
+    },
+  });
+}

package/src/facade/facades/App.ts

@@ -0,0 +1,155 @@
+/**
+ * The `App` facade — static-style access to the running {@link Application}
+ * kernel and its IoC container.
+ *
+ * Resolves the live application singleton on every call, so it holds no
+ * module-level state and is safe to import anywhere. Every method throws if
+ * accessed before `Application.create()` (and, for resolution, `boot()`) has
+ * run, mirroring the behaviour of the other framework facades.
+ *
+ * Registration methods (`bind` / `singleton` / `scoped` / `value` / `alias` /
+ * `forget`) are **boot-time only**: once `boot()` completes the container is
+ * locked and they throw {@link ContainerLockedError}, because mutating the
+ * process-global container at request time would leak state across concurrent
+ * requests. Register during boot (bootstrap `app.bind()`, a `ServiceProvider`,
+ * or the `app/services` convention) and use a `scoped` binding for per-request
+ * state.
+ */
+import type { Application } from "../../application/Application.ts";
+import { currentApp } from "../../application/currentApp.ts";
+import type { Container } from "../../container/Container.ts";
+import type { BindingToken, ContainerBindings, Factory } from "../../container/types.ts";
+import { ContainerLockedError } from "../../errors/ContainerErrors.ts";
+
+/**
+ * Return the live container, throwing {@link ContainerLockedError} when the
+ * application has already booted. Used to gate every registration method.
+ */
+function _unlockedContainer(method: string): Container {
+  const app = currentApp();
+  if (app.booted) throw new ContainerLockedError(method);
+  return app.container;
+}
+
+/**
+ * Static facade for the application container.
+ *
+ * @example
+ * ```ts
+ * // Auto-wire a service class (resolves its @inject() graph):
+ * const users = await App.make(UsersService);
+ *
+ * // Resolve a named binding:
+ * const events = await App.make("events");
+ *
+ * // Register during boot (bootstrap/app.ts or a provider):
+ * App.singleton(Clock, () => new SystemClock());
+ * ```
+ */
+export const App = {
+  // ── Introspection ─────────────────────────────────────────────────────
+
+  /** The live IoC container of the running application. */
+  get container(): Container {
+    return currentApp().container;
+  },
+
+  /** The running {@link Application} instance. */
+  instance(): Application {
+    return currentApp();
+  },
+
+  /** The runtime environment: "web" | "console" | "worker" | "test" | "repl". */
+  environment(): Application["environment"] {
+    return currentApp().environment;
+  },
+
+  /** Whether the configured `app.env` is a production environment. */
+  isProduction(): boolean {
+    return ["production", "prod"].includes(_appEnv());
+  },
+
+  /** Whether the configured `app.env` is a local/development environment. */
+  isLocal(): boolean {
+    return ["local", "development", "dev"].includes(_appEnv());
+  },
+
+  // ── Resolution ────────────────────────────────────────────────────────
+
+  /**
+   * Resolve a binding — or auto-wire a class via its `@inject()`
+   * metadata — from the container asynchronously. This is the primary
+   * resolution method.
+   */
+  make<T>(token: BindingToken<T>, consumer?: unknown): Promise<T> {
+    return currentApp().container.make(token, consumer);
+  },
+
+  /**
+   * Resolve a binding synchronously. Only works for value bindings and
+   * already-resolved singletons; throws otherwise. Prefer {@link App.make}.
+   */
+  makeSync<T>(token: BindingToken<T>): T {
+    return currentApp().container.makeSync(token);
+  },
+
+  /**
+   * Construct a class by auto-wiring its dependencies, ignoring any registered
+   * binding for that token. Returns a brand-new instance every call.
+   */
+  build<T>(ctor: new (...args: unknown[]) => T): Promise<T> {
+    return currentApp().container.build(ctor);
+  },
+
+  /**
+   * Resolve a named binding without throwing — returns `undefined` when the
+   * token is not registered or cannot be resolved synchronously.
+   */
+  tryMake<K extends keyof ContainerBindings>(token: K): ContainerBindings[K] | undefined {
+    return currentApp().container.tryMake(token);
+  },
+
+  /** Whether a token is registered in the container. */
+  bound(token: BindingToken): boolean {
+    const container = currentApp().container;
+    return container.registry.has(container._resolveAlias(token));
+  },
+
+  // ── Registration (boot-time only) ─────────────────────────────────────
+
+  /** Register a transient binding — the factory runs on every resolution. */
+  bind<T>(token: BindingToken<T>, factory: Factory<T>): Container {
+    return _unlockedContainer("bind").bind(token, factory);
+  },
+
+  /** Register a singleton binding — resolved once and cached for the process lifetime. */
+  singleton<T>(token: BindingToken<T>, factory: Factory<T>): Container {
+    return _unlockedContainer("singleton").singleton(token, factory);
+  },
+
+  /** Register a request-scoped binding — resolved once per request scope. */
+  scoped<T>(token: BindingToken<T>, factory: Factory<T>): Container {
+    return _unlockedContainer("scoped").scoped(token, factory);
+  },
+
+  /** Register an already-constructed value under `token`. */
+  value<T>(token: BindingToken<T>, instance: T): Container {
+    return _unlockedContainer("value").value(token, instance);
+  },
+
+  /** Make resolving `from` resolve `to` instead. */
+  alias(from: unknown, to: unknown): Container {
+    return _unlockedContainer("alias").alias(from, to);
+  },
+
+  /** Remove a binding. Returns `true` if a binding existed for the token. */
+  forget(token: BindingToken): boolean {
+    return _unlockedContainer("forget").forget(token);
+  },
+} as const;
+
+/** Read the configured `app.env`, defaulting to "development" when unavailable. */
+function _appEnv(): string {
+  const config = currentApp().container.tryMake("config");
+  return config?.get<string>("app.env", "development") ?? "development";
+}

package/src/facade/facades/Artisan.ts

@@ -0,0 +1,63 @@
+/**
+ * The `Artisan` facade — runs registered CLI commands from inside a running
+ * application and captures their output instead of writing to the terminal.
+ */
+import { currentApp } from "../../application/currentApp.ts";
+import type { CommandRunner } from "../../command/CommandRunner.ts";
+
+/** Outcome of running a command through {@link Artisan}. */
+export interface ArtisanResult {
+  /** Process-style exit code: 0 = success, non-zero = failure. */
+  code: number;
+  /** Everything the command wrote via info/error/warn/etc. */
+  output: string;
+}
+
+/**
+ * Artisan facade — run any registered command from inside the application.
+ * Output is captured; nothing is written to the server terminal.
+ * Safe to call from controllers, services, scheduled tasks.
+ *
+ * Only use for fast commands. For long-running work, use Bun.spawn or worker.ts.
+ *
+ * See: plans/boot-modes.md §6
+ *
+ * @throws {Error} From {@link Artisan.call} when no CommandRunner is registered
+ * in the container (commands are only registered for `env='web'`).
+ *
+ * @example
+ * ```ts
+ * const { code, output } = await Artisan.call('cache:clear');
+ * const { code, output } = await Artisan.call('migrate', { '--fresh': true });
+ * return Response.json({ output, success: code === 0 });
+ * ```
+ */
+export const Artisan = {
+  async call(
+    commandName: string,
+    parameters: Record<string, string | boolean | number> = {},
+  ): Promise<ArtisanResult> {
+    const container = currentApp().container;
+    const runner = container.tryMake("commands") as CommandRunner | undefined;
+
+    if (!runner) {
+      throw new Error(
+        `Artisan.call('${commandName}') failed: no CommandRunner in container. ` +
+          `Register commands in AppServiceProvider.onBooted() for env='web'.`,
+      );
+    }
+
+    // Booleans become bare flags (only when true); everything else becomes a
+    // `key=value` token, mirroring how the CLI parses argv.
+    const commandArguments = [commandName];
+    for (const [key, value] of Object.entries(parameters)) {
+      if (typeof value === "boolean") {
+        if (value) commandArguments.push(key);
+      } else {
+        commandArguments.push(`${key}=${String(value)}`);
+      }
+    }
+
+    return runner.callInProcess(commandArguments);
+  },
+};

package/src/facade/facades/Config.ts

@@ -0,0 +1,21 @@
+/**
+ * The `Config` facade — static-style access to the application configuration
+ * registered under the container's `config` binding.
+ */
+import { createFacade } from "../Facade.ts";
+
+/**
+ * Facade over the `config` binding for reading configuration values.
+ *
+ * Resolves the live `config` instance from the container on each access, so it
+ * is only usable after `Application.boot()` has run.
+ *
+ * @example
+ * ```ts
+ * import { Config } from "@zerotal/core/facades";
+ *
+ * Config.get("app.name");         // read with the app's config value type
+ * Config.require("app.key");      // throws ConfigError when unset
+ * ```
+ */
+export const Config = createFacade("config");

package/src/facade/facades/Events.ts

@@ -0,0 +1,19 @@
+/**
+ * The `Events` facade — static-style access to the application event emitter
+ * registered under the container's `events` binding.
+ */
+import { createFacade } from "../Facade.ts";
+
+/**
+ * Facade over the `events` binding ({@link Emitter}) for emitting events and
+ * registering listeners.
+ *
+ * @example
+ * ```ts
+ * import { Events } from "@zerotal/core/facades";
+ *
+ * Events.on(UserRegistered, SendWelcomeEmail);
+ * await Events.emit(new UserRegistered(user.id, user.email));
+ * ```
+ */
+export const Events = createFacade("events");

package/src/facade/facades/index.ts

@@ -0,0 +1,28 @@
+/**
+ * The `@zerotal/core/facades` subpath — the framework's static-style facades.
+ *
+ * A facade is a thin, always-safe-to-import handle over a named container
+ * binding: every property access resolves the live instance from the running
+ * application on demand, so facades hold no module-level state and stay correct
+ * across boots. {@link App} reaches the application kernel and IoC container,
+ * {@link Config} reads configuration, {@link Events} emits framework events, and
+ * {@link Artisan} runs registered CLI commands in-process. All of them require
+ * `Application.create()` (and, for resolution, `boot()`) to have run first.
+ *
+ * @example
+ * ```ts
+ * import { App, Config, Events, Artisan } from "@zerotal/core/facades";
+ *
+ * const name = Config.get("app.name");
+ * const users = await App.make("users");
+ * await Events.emit(new UserRegistered(user.id));
+ * const { code, output } = await Artisan.call("cache:clear");
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { App } from "./App.ts";
+export { Config } from "./Config.ts";
+export { Events } from "./Events.ts";
+export { Artisan } from "./Artisan.ts";
+export type { ArtisanResult } from "./Artisan.ts";

package/src/global.d.ts

@@ -0,0 +1,9 @@
+// Ambient declarations specific to this codebase.
+//
+// Bun, Node (`node:*`), and `bun:test` types come from `@types/bun` (→ bun-types).
+// Only declarations that bun-types does NOT provide live here.
+
+// Bun extends Request with route params (e.g. /users/:id → { id: '42' }).
+interface Request {
+  readonly params?: Record<string, string>;
+}

package/src/hash/Hash.ts

@@ -0,0 +1,60 @@
+/**
+ * Password hashing over `Bun.password` — argon2id by default, bcrypt optional.
+ * A zero-config core primitive available framework-wide (no provider required).
+ *
+ * @example
+ * import { Hash } from '@zerotal/core';
+ * const hash  = await Hash.make('secret123');
+ * const valid = await Hash.verify('secret123', hash); // true
+ */
+/** Supported password-hashing algorithms. */
+export type HashAlgorithm = "argon2id" | "argon2i" | "argon2d" | "bcrypt";
+
+class HashManager {
+  private _default: HashAlgorithm = "argon2id";
+
+  /** Set the default hashing algorithm. */
+  setDefault(algorithm: HashAlgorithm): void {
+    this._default = algorithm;
+  }
+
+  /** Hash a value. Store the returned string. */
+  async make(value: string, options: { algorithm?: HashAlgorithm } = {}): Promise<string> {
+    return Bun.password.hash(value, { algorithm: options.algorithm ?? this._default });
+  }
+
+  /** Verify a value against a stored hash (algorithm auto-detected from the hash). */
+  async verify(value: string, hash: string): Promise<boolean> {
+    try {
+      return await Bun.password.verify(value, hash);
+    } catch {
+      return false;
+    }
+  }
+
+  /** Alias of {@link verify}. */
+  async check(value: string, hash: string): Promise<boolean> {
+    return this.verify(value, hash);
+  }
+
+  /** True when a hash was made with a different algorithm than the current default. */
+  needsRehash(hash: string): boolean {
+    return this._default.startsWith("argon")
+      ? !hash.startsWith(`$${this._default}$`)
+      : !hash.startsWith("$2"); // bcrypt
+  }
+}
+
+/**
+ * Password hashing primitive (argon2id by default).
+ *
+ * @example
+ * ```ts
+ * import { Hash } from "@zerotal/core/security";
+ *
+ * const digest = await Hash.make("hunter2");
+ * await Hash.check("hunter2", digest);  // true
+ * Hash.needsRehash(digest);             // false — re-hash on next login when true
+ * ```
+ */
+export const Hash = new HashManager();

package/src/health/Health.ts

@@ -0,0 +1,221 @@
+/**
+ * Health checks — a small registry of named probes plus the report/route logic
+ * behind the framework's `/health` endpoint.
+ *
+ * A check returns (or resolves to) a {@link HealthResult}; throwing, or
+ * returning `{ status: 'down' }`, marks it unhealthy. Checks flagged `critical`
+ * drive the overall status (and the HTTP 503 response); non-critical failures
+ * degrade the report without failing readiness.
+ *
+ * @example
+ * import { Health } from '@zerotal/core';
+ *
+ * Health.register('database', async () => {
+ *   await DB.raw('select 1');
+ * }, { critical: true });
+ *
+ * Health.register('cache', async () => {
+ *   await Cache.put('__health', '1', 5);
+ *   return { meta: { driver: 'redis' } };
+ * });
+ */
+
+/** Overall and per-check health status. */
+export type HealthStatus = "ok" | "degraded" | "down";
+
+/** What a health check returns to describe its own state. */
+export interface HealthResult {
+  /** Defaults to `ok` when a check returns without throwing. */
+  status?: HealthStatus;
+  message?: string;
+  meta?: Record<string, unknown>;
+}
+
+/** A single health probe; may run sync or async and may return nothing for "ok". */
+export type HealthCheckFn = () => Promise<HealthResult | void> | HealthResult | void;
+
+/** The outcome of running one check, as it appears in the aggregate report. */
+export interface HealthCheckReport {
+  status: HealthStatus;
+  message?: string;
+  durationMs: number;
+  critical: boolean;
+  meta?: Record<string, unknown>;
+}
+
+/** The full health report returned by the endpoint. */
+export interface HealthReport {
+  status: HealthStatus;
+  app: { name: string; version: string; environment: string; bootMs?: number };
+  /** Seconds since the process started. */
+  uptime: number;
+  timestamp: string;
+  checks: Record<string, HealthCheckReport>;
+}
+
+/** Application metadata the report needs that the registry can't know on its own. */
+export interface HealthRunMeta {
+  name: string;
+  version: string;
+  environment: string;
+  uptime: number;
+  /** Wall-clock boot time in milliseconds, surfaced in the report's `app` block. */
+  bootMs?: number;
+}
+
+class HealthRegistry {
+  private readonly _checks = new Map<string, { fn: HealthCheckFn; critical: boolean }>();
+
+  /** Register (or replace) a named check. `critical` checks can fail readiness. */
+  register(name: string, fn: HealthCheckFn, options: { critical?: boolean } = {}): this {
+    this._checks.set(name, { fn, critical: options.critical ?? false });
+    return this;
+  }
+
+  /** Remove a previously registered check by name. */
+  remove(name: string): this {
+    this._checks.delete(name);
+    return this;
+  }
+  /** Remove every registered check. */
+  clear(): this {
+    this._checks.clear();
+    return this;
+  }
+  /** Whether a check is registered under the given name. */
+  has(name: string): boolean {
+    return this._checks.has(name);
+  }
+  /** The names of all registered checks. */
+  get names(): string[] {
+    return [...this._checks.keys()];
+  }
+
+  /** Run every check and assemble the aggregate report. */
+  async run(meta: HealthRunMeta): Promise<HealthReport> {
+    const checks: Record<string, HealthCheckReport> = {};
+    let anyCriticalDown = false;
+    let anyDegraded = false;
+
+    await Promise.all(
+      [...this._checks.entries()].map(async ([name, { fn, critical }]) => {
+        const startedAt = Date.now();
+        let report: HealthCheckReport;
+        try {
+          const result = (await fn()) ?? {};
+          const status = result.status ?? "ok";
+          report = {
+            status,
+            durationMs: Date.now() - startedAt,
+            critical,
+            ...(result.message ? { message: result.message } : {}),
+            ...(result.meta ? { meta: result.meta } : {}),
+          };
+        } catch (error) {
+          report = {
+            status: "down",
+            durationMs: Date.now() - startedAt,
+            critical,
+            message: (error as Error)?.message ?? String(error),
+          };
+        }
+        if (report.status === "down" && critical) anyCriticalDown = true;
+        else if (report.status === "down" || report.status === "degraded") anyDegraded = true;
+        checks[name] = report;
+      }),
+    );
+
+    const status: HealthStatus = anyCriticalDown ? "down" : anyDegraded ? "degraded" : "ok";
+    return {
+      status,
+      app: {
+        name: meta.name,
+        version: meta.version,
+        environment: meta.environment,
+        ...(meta.bootMs !== undefined ? { bootMs: meta.bootMs } : {}),
+      },
+      uptime: meta.uptime,
+      timestamp: new Date().toISOString(),
+      checks,
+    };
+  }
+}
+
+/** Global health-check registry. */
+export const Health = new HealthRegistry();
+
+// ── Endpoint configuration + access control ───────────────────────────────────
+
+/** The health config, authored under the `health` key of `config/app.ts`. */
+export interface HealthConfigShape {
+  /** Serve the endpoint. Default: on outside production, off in production. */
+  enabled?: boolean;
+  /** Route path. Default: `/health`. */
+  path?: string;
+  /** Shared secret. Required in production; supplied via `?key=` or `X-Health-Key`. */
+  secret?: string;
+  /** Include per-check details. Set false for a bare `{ status }` body. Default: true. */
+  showDetails?: boolean;
+}
+
+/** The health config after defaults and back-compat have been applied. */
+export interface ResolvedHealthConfig {
+  enabled: boolean;
+  path: string;
+  secret?: string;
+  showDetails: boolean;
+}
+
+/**
+ * Resolve the health config against the environment. `legacyEnabled` maps the
+ * older `app.health` boolean onto `enabled` for back-compat.
+ */
+export function resolveHealthConfig(
+  raw: HealthConfigShape | undefined,
+  isProduction: boolean,
+  legacyEnabled?: boolean,
+): ResolvedHealthConfig {
+  const enabled = raw?.enabled ?? legacyEnabled ?? !isProduction;
+  return {
+    enabled,
+    path: raw?.path ?? "/health",
+    showDetails: raw?.showDetails ?? true,
+    ...(raw?.secret ? { secret: raw.secret } : {}),
+  };
+}
+
+/** The result of an access-control decision for the health endpoint. */
+export interface HealthAccess {
+  allowed: boolean;
+  /** HTTP status to use when `allowed` is false. */
+  code?: number;
+  reason?: string;
+}
+
+/**
+ * Decide whether a request may read the endpoint.
+ *  - A configured `secret` is always enforced (`?key=` or `X-Health-Key`).
+ *  - In production with no secret the endpoint is refused (503) — it must be
+ *    protected before it can be exposed.
+ *  - Otherwise (development, no secret) access is open.
+ */
+export function checkHealthAccess(
+  request: Request,
+  config: ResolvedHealthConfig,
+  isProduction: boolean,
+): HealthAccess {
+  if (config.secret) {
+    const provided =
+      new URL(request.url).searchParams.get("key") ?? request.headers.get("x-health-key");
+    if (provided === config.secret) return { allowed: true };
+    return { allowed: false, code: 401, reason: "Invalid or missing health key." };
+  }
+  if (isProduction) {
+    return {
+      allowed: false,
+      code: 503,
+      reason: "Health endpoint requires `app.health.secret` in production.",
+    };
+  }
+  return { allowed: true };
+}