@zerotal/core 1.0.0

package/src/application/ExceptionHandler.ts

@@ -0,0 +1,183 @@
+/**
+ * Turns unhandled exceptions into HTTP responses. Defines the base
+ * `ExceptionHandler` apps subclass, plus the default error-to-response logic
+ * that negotiates HTML, JSON, redirects, and the dev stack-trace page.
+ */
+import type { HttpContext } from "../pipeline/HttpContext.ts";
+import type { ZerotalError } from "../errors/ZerotalError.ts";
+import { renderDevErrorPage, renderHttpErrorPage } from "./DevErrorPage.ts";
+import { devSurfacesEnabled } from "../support/env.ts";
+
+/**
+ * Base class for application-level exception handling.
+ *
+ * Register a subclass with `app.withExceptionHandler(Handler)` in
+ * bootstrap/app.ts. The framework calls `report()` then `render()` for
+ * every unhandled exception thrown by a route handler or middleware.
+ *
+ * @example
+ * // app/exceptions/Handler.ts
+ * import { ExceptionHandler } from '@zerotal/core';
+ *
+ * export class Handler extends ExceptionHandler {
+ *   override async render(err: unknown, ctx: HttpContext): Promise<Response> {
+ *     if (err instanceof ModelNotFoundError) {
+ *       return Response.json({ message: 'Not found' }, { status: 404 });
+ *     }
+ *     return super.render(err, ctx);
+ *   }
+ * }
+ */
+export abstract class ExceptionHandler {
+  // Explicit constructor so JSC's function-coverage counter attributes
+  // the super() call from subclasses to this entry.
+  constructor() {}
+
+  protected dontReport: Array<new (...args: never[]) => unknown> = [];
+
+  private static readonly _alwaysSilent = new Set([
+    "ValidationRedirectError",
+    "ValidationJsonError",
+    "ValidationError",
+    "PrecognitionResponse",
+    "NotFoundError",
+  ]);
+
+  protected shouldReport(error: unknown): boolean {
+    const name = (error as { name?: string } | null)?.name;
+    if (name && ExceptionHandler._alwaysSilent.has(name)) return false;
+    for (const Type of this.dontReport) {
+      if (error instanceof (Type as unknown as new (...args: never[]) => object)) return false;
+    }
+    return true;
+  }
+
+  async report(error: unknown, _ctx?: HttpContext): Promise<void> {
+    if (!this.shouldReport(error)) return;
+    console.error("[Zerotal] Unhandled error:", error);
+  }
+
+  async render(error: unknown, ctx: HttpContext): Promise<Response> {
+    return ExceptionHandler.defaultRender(error, ctx);
+  }
+
+  /**
+   * Shared error → Response logic.
+   *
+   * Response format depends on what the client accepts:
+   *
+   *   Browser (Accept: text/html)  → styled HTML page (all error classes)
+   *   Inertia XHR (X-Inertia: true) → JSON (Inertia shows its own modal)
+   *   API client (Accept: application/json) → JSON
+   *
+   * Error-class routing:
+   *   1. ValidationRedirectError → 303 redirect (always, any client)
+   *   2. ValidationJsonError     → 422 JSON (always — the errors object IS the response)
+   *   3. ZerotalError 4xx           → styled 4xx HTML or JSON depending on client
+   *   4. Everything else         → dev stack-trace page or minimal 500
+   */
+  static async defaultRender(error: unknown, ctx?: HttpContext): Promise<Response> {
+    // Fail closed for debug output: the dev stack-trace page needs either a
+    // developer-supervised process (the `serve --dev` worker) or an explicitly
+    // non-prod APP_ENV. An unset/unknown/`staging` environment is treated as
+    // production, so a deploy that forgets to set it never leaks stack traces
+    // or source context to clients.
+    const isProduction = !devSurfacesEnabled();
+    const wantsHtml = _wantsHtml(ctx);
+
+    // ── Always-redirect: never render as HTML or JSON ─────────────────────
+    const name = (error as { name?: string } | null)?.name;
+
+    if (name === "ValidationRedirectError") {
+      const { redirectTo } = error as { redirectTo: string };
+      return new Response(null, {
+        status: 303,
+        headers: { Location: redirectTo },
+      });
+    }
+
+    // ── Precognition: the error builds its own 204/422 response ───────────────
+    if (name === "PrecognitionResponse") {
+      return (error as { toResponse(): Response }).toResponse();
+    }
+
+    // ── Validation errors: structured JSON (form submits use redirect above) ─
+    if (name === "ValidationJsonError") {
+      const { errors } = error as { errors: Record<string, string> };
+      return Response.json({ message: "Validation failed", errors }, { status: 422 });
+    }
+
+    // ── Named HTTP errors (4xx / 5xx ZerotalError subclasses) ────────────────
+    if (error instanceof Error && "status" in error) {
+      const httpError = error as ZerotalError;
+      const status = httpError.status;
+      const extraHeaders = (error as { headers?: Record<string, string> }).headers;
+
+      if (wantsHtml) {
+        if (!isProduction && status >= 500) {
+          return _withHeaders(renderDevErrorPage(error, ctx), extraHeaders);
+        }
+        return _withHeaders(
+          renderHttpErrorPage(status, httpError.message, httpError.code, ctx),
+          extraHeaders,
+        );
+      }
+
+      return Response.json(
+        { message: httpError.message, code: httpError.code },
+        { status, ...(extraHeaders ? { headers: extraHeaders } : {}) },
+      );
+    }
+
+    // ── Unknown / unhandled errors (genuine bugs) ─────────────────────────
+    if (!isProduction && wantsHtml) {
+      return renderDevErrorPage(error, ctx);
+    }
+
+    if (!isProduction) {
+      // API client in dev: JSON with message.
+      const message = error instanceof Error ? error.message : String(error);
+      return Response.json({ message, code: "E_INTERNAL" }, { status: 500 });
+    }
+
+    // Production: no internals exposed.
+    if (wantsHtml) {
+      return renderHttpErrorPage(500, "Internal Server Error", undefined, ctx);
+    }
+    return Response.json({ message: "Internal Server Error" }, { status: 500 });
+  }
+}
+
+/** Merge extra headers into a (possibly pending) Response and return it. */
+async function _withHeaders(
+  res: Response | Promise<Response>,
+  headers?: Record<string, string>,
+): Promise<Response> {
+  const resolved = await res;
+  if (headers) {
+    for (const [key, value] of Object.entries(headers)) resolved.headers.set(key, value);
+  }
+  return resolved;
+}
+
+/**
+ * True when the client will render an HTML response.
+ *
+ * Covers both regular browser navigation AND Inertia XHR — Inertia sends
+ * `Accept: text/html` and shows non-Inertia HTML responses in its error
+ * modal (iframe overlay), which is exactly what we want for the dev page.
+ *
+ * Returns false only for pure JSON clients (`Accept: application/json`).
+ */
+function _wantsHtml(ctx?: HttpContext): boolean {
+  try {
+    if (!ctx?.request) return false;
+    const accept = ctx.request.headers.get("Accept") ?? "";
+    // Pure JSON clients — return JSON.
+    if (accept.startsWith("application/json")) return false;
+    // Browsers and Inertia XHR both include text/html in Accept.
+    return accept.includes("text/html");
+  } catch {
+    return false;
+  }
+}

package/src/application/currentApp.ts

@@ -0,0 +1,73 @@
+/**
+ * The single ambient lookup in the framework: `currentApp()`.
+ *
+ * Everything that "feels global" — facades, `config()`, `Router.get(...)` sugar —
+ * is a thin window onto one owned, instance-scoped {@link Application}, reached
+ * through exactly one door. There is one process **default** application (set by
+ * {@link Application.create}), overridable within an {@link withApp} scope so two
+ * apps can coexist in one process (embedded test harnesses, multi-tenant control
+ * planes, migrating against a second app's config).
+ *
+ * The accessor consults the {@link withApp} scope first, then the process
+ * default. This is the only ambient app reference in the framework.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Application } from "./Application.ts";
+
+/** The process-default application. Set by {@link Application.create}; cleared on reset. */
+let _default: Application | undefined;
+
+/**
+ * Per-scope override. Code running inside {@link withApp} sees that app as the
+ * current one, so ambient lookups resolve to it instead of the process default.
+ */
+const _scope = new AsyncLocalStorage<Application>();
+
+/** @internal Set (or clear) the process-default application. Called by the application lifecycle. */
+export function setDefaultApp(app: Application | undefined): void {
+  _default = app;
+}
+
+/** @internal The process-default application, or `undefined` when none has been created. */
+export function defaultApp(): Application | undefined {
+  return _default;
+}
+
+/**
+ * The current application — the framework's one ambient accessor.
+ *
+ * Resolution order: the {@link withApp} scope override, then the process default.
+ *
+ * @throws {Error} when no application is available (none created and not inside a
+ * {@link withApp} scope).
+ */
+export function currentApp(): Application {
+  const app = _scope.getStore() ?? _default;
+  if (!app) {
+    throw new Error(
+      "No current application. Call Application.create() first, or run inside withApp(app, …).",
+    );
+  }
+  return app;
+}
+
+/** The current application, or `undefined` when none is available. Safe off-app (CLI bootstrap, tests). */
+export function tryCurrentApp(): Application | undefined {
+  return _scope.getStore() ?? _default;
+}
+
+/**
+ * Run `fn` with `app` as the current application for the duration of the call —
+ * and everything it `await`s — overriding the process default within this scope.
+ * The override is confined to the async context, so concurrent scopes never leak
+ * into one another.
+ *
+ * @example
+ * ```ts
+ * // Run a migration against a second app's config without disturbing the default.
+ * await withApp(secondApp, () => secondApp.container.make("db"));
+ * ```
+ */
+export function withApp<T>(app: Application, fn: () => T): T {
+  return _scope.run(app, fn);
+}

package/src/assets/assets.ts

@@ -0,0 +1,79 @@
+/**
+ * Front-end asset URL helper and asset versioning.
+ *
+ * `asset(path)` builds the public URL for a built asset, honouring the
+ * configured `app.assets.prefix`. In dev it appends `?v=<version>` so the
+ * browser re-fetches a rebuilt file on the next reload: the entry points named
+ * here keep the same filename from one build to the next, so nothing in the URL
+ * would otherwise change and the query string has to do the busting. (Bundlers
+ * content-hash the code-split *chunks* an entry pulls in, but those URLs live
+ * inside the bundle and are never passed through this helper.) In production
+ * the clean path is returned unchanged.
+ *
+ * The version is a per-build token, bumped on every dev rebuild (see
+ * {@link bumpAssetVersion}) and propagated from the dev orchestrator to the
+ * server worker over its reload channel. This mirrors Inertia's asset-version
+ * model — one token per build, busting every asset at once.
+ */
+
+let _prefix = "/";
+let _dev = false;
+let _version = "";
+
+/**
+ * Configure the asset helper from resolved app config. Called once at boot.
+ *
+ * @param opts.prefix  URL prefix built assets are served under (`app.assets.prefix`).
+ * @param opts.dev     Whether `?v=` cache-busting should be applied (dev only).
+ */
+export function configureAssets(opts: { prefix?: string; dev?: boolean }): void {
+  if (opts.prefix !== undefined) _prefix = opts.prefix;
+  if (opts.dev !== undefined) _dev = opts.dev;
+}
+
+/** Replace the current asset version (e.g. a build token from the orchestrator). */
+export function setAssetVersion(version: string): void {
+  _version = version;
+}
+
+/** The current asset version, or `""` when unset. */
+export function assetVersion(): string {
+  return _version;
+}
+
+/**
+ * Bump the asset version to a fresh token and return it.
+ *
+ * Called by the dev orchestrator after each successful rebuild so the next
+ * `asset()` URL changes and the browser refetches the file.
+ */
+export function bumpAssetVersion(): string {
+  _version = Date.now().toString(36);
+  return _version;
+}
+
+/**
+ * Build the public URL for a front-end asset.
+ *
+ * @param path  Asset path relative to the asset prefix (leading slash optional).
+ * @returns     `<prefix>/<path>`, with `?v=<version>` appended in dev.
+ *
+ * @example
+ *   asset("/app.css")   // prod → "/app.css"
+ *   asset("app.css")    // dev  → "/app.css?v=lq3k7m"
+ */
+export function asset(path: string): string {
+  const url = _joinUrl(_prefix, path);
+  if (_dev && _version) {
+    const separator = url.includes("?") ? "&" : "?";
+    return `${url}${separator}v=${_version}`;
+  }
+  return url;
+}
+
+/** Join a URL prefix and an asset path with exactly one slash between them. */
+function _joinUrl(prefix: string, path: string): string {
+  const left = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+  const right = path.startsWith("/") ? path : `/${path}`;
+  return `${left}${right}` || "/";
+}

package/src/assets/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Front-end asset URL helper and asset versioning (the `@zerotal/core/assets`
+ * subpath). {@link asset} builds the public URL for a built asset, appending a
+ * `?v=<version>` cache-buster in dev; the versioning helpers let the dev
+ * orchestrator bust every asset at once after a rebuild.
+ *
+ * @example
+ * ```ts
+ * import { asset } from "@zerotal/core/assets";
+ *
+ * asset("/app.css"); // prod → "/app.css"; dev → "/app.css?v=lq3k7m"
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { asset, assetVersion, setAssetVersion } from "./assets.ts";

package/src/auth/AuthenticatedUser.ts

@@ -0,0 +1,18 @@
+/**
+ * The authenticated user for the current request.
+ * Extend this interface in your app via declaration merging to match your User model.
+ *
+ * @remarks
+ * The root-level alias of the kernel-owned {@link AuthenticatableUser} contract
+ * (from `@zerotal/core/contracts`) which it extends, so augmenting either
+ * interface resolves to the same shape.
+ *
+ * @example
+ * // app/models/User.ts
+ * declare module '@zerotal/core' {
+ *   interface AuthenticatedUser extends User {}
+ * }
+ */
+import type { AuthenticatableUser } from "../contracts/auth.ts";
+
+export interface AuthenticatedUser extends AuthenticatableUser {}

package/src/build/PackageLinter.ts

@@ -0,0 +1,146 @@
+/**
+ * Lints monorepo packages against the framework's conventions — provider
+ * location and metadata, config-factory shape, test presence, packaging, and
+ * error-base discipline — producing a structured report of violations.
+ */
+
+/** How serious a lint violation is. */
+export type Severity = 'high' | 'medium' | 'low';
+
+/** A single rule violation found in a package. */
+export interface Violation { rule: string; message: string; severity: Severity; }
+/** The full set of violations found in one package. */
+export interface PackageReport { package: string; violations: Violation[]; }
+
+interface PackageFiles {
+  source: Map<string, string>;
+  packageJson: Record<string, unknown> | null;
+  packageJsonRaw: string | null;
+}
+
+async function _readPackage(absoluteDir: string): Promise<PackageFiles> {
+  const source = new Map<string, string>();
+  try {
+    const glob = new Bun.Glob('src/**/*.{ts,tsx}');
+    for await (const relativePath of glob.scan({ cwd: absoluteDir, onlyFiles: true })) {
+      try { source.set(relativePath.replace(/\\/g, '/'), await Bun.file(`${absoluteDir}/${relativePath}`).text()); } catch {}
+    }
+  } catch {}
+  let packageJson: Record<string, unknown> | null = null;
+  let packageJsonRaw: string | null = null;
+  try {
+    packageJsonRaw = await Bun.file(`${absoluteDir}/package.json`).text();
+    packageJson = JSON.parse(packageJsonRaw) as Record<string, unknown>;
+  } catch {}
+  return { source, packageJson, packageJsonRaw };
+}
+
+function _isProviderPath(relativePath: string): boolean { return /Provider\.tsx?$/.test(relativePath); }
+
+function _checkProviderLocation(files: PackageFiles): Violation[] {
+  const providers = [...files.source.keys()].filter(_isProviderPath);
+  if (providers.length === 0) return [];
+  const violations: Violation[] = [];
+  for (const path of providers) if (!path.startsWith('src/provider/')) violations.push({ rule: 'provider-location', severity: 'high', message: `provider '${path}' must live at src/provider/` });
+  return violations;
+}
+
+function _checkProviderMetadata(files: PackageFiles): Violation[] {
+  const providers = [...files.source.entries()].filter(([path]) => _isProviderPath(path));
+  if (providers.length === 0) return [];
+  const violations: Violation[] = [];
+  for (const [path, content] of providers) {
+    const registersBinding = /container\.(singleton|value|bind)\s*\(/.test(content);
+    if (registersBinding && !/static\s+(override\s+)?provides\b/.test(content)) violations.push({ rule: 'provider-provides', severity: 'medium', message: `${path}: registers a binding but is missing 'static provides'` });
+    if (!/static\s+(override\s+)?environments\b/.test(content)) violations.push({ rule: 'provider-environments', severity: 'medium', message: `${path}: missing 'static environments'` });
+  }
+  return violations;
+}
+
+function _checkConfigFactory(files: PackageFiles): Violation[] {
+  const config = files.source.get('src/config.ts');
+  if (!config) return [];
+  const violations: Violation[] = [];
+  const match =
+    config.match(/export\s+function\s+([A-Za-z_]\w*)Config\s*(?:<[^>]*>)?\s*\(([^)]*)\)/) ??
+    config.match(/export\s+const\s+([A-Za-z_]\w*)Config\s*=\s*(?:<[^>]*>)?\s*\(([^)]*)\)/);
+  if (!match) { violations.push({ rule: 'config-factory', severity: 'medium', message: `src/config.ts: no '<Name>Config(...)' factory found` }); return violations; }
+  const [, namePrefix, params] = match;
+  const factoryName = `${namePrefix}Config`;
+  if (!/^[A-Z]/.test(factoryName)) violations.push({ rule: 'config-casing', severity: 'high', message: `config factory '${factoryName}' must be PascalCase` });
+  if (!/Partial\s*</.test(params ?? '')) violations.push({ rule: 'config-partial', severity: 'high', message: `config factory '${factoryName}' parameter must be Partial<...Shape>` });
+  return violations;
+}
+
+function _checkConfigDeepMerge(files: PackageFiles): Violation[] {
+  const config = files.source.get('src/config.ts');
+  if (!config) return [];
+  // Only applies when the file actually defines a <Name>Config factory.
+  const hasFactory =
+    /export\s+function\s+[A-Za-z_]\w*Config\s*(?:<[^>]*>)?\s*\(/.test(config) ||
+    /export\s+const\s+[A-Za-z_]\w*Config\s*=/.test(config);
+  if (!hasFactory) return [];
+  if (!/\bdeepMerge\s*\(/.test(config))
+    return [{ rule: 'config-deepmerge', severity: 'medium', message: `src/config.ts: the config factory must merge with deepMerge(defaults, options)` }];
+  return [];
+}
+
+function _checkTests(files: PackageFiles): Violation[] {
+  const hasTest = [...files.source.keys()].some((path) => /\.test\.tsx?$/.test(path));
+  return hasTest ? [] : [{ rule: 'tests', severity: 'high', message: 'package ships no *.test.ts(x) files' }];
+}
+
+function _checkPackaging(files: PackageFiles): Violation[] {
+  const packageJson = files.packageJson;
+  if (!packageJson) return [{ rule: 'package-json', severity: 'high', message: 'missing or invalid package.json' }];
+  const violations: Violation[] = [];
+  if (packageJson['type'] !== 'module') violations.push({ rule: 'esm', severity: 'medium', message: `package.json "type" must be "module"` });
+  if (!packageJson['exports'] && !packageJson['main'] && !packageJson['bin']) violations.push({ rule: 'exports', severity: 'medium', message: 'package.json must define "exports" or "main"' });
+  return violations;
+}
+
+function _checkErrorDiscipline(files: PackageFiles, packageName: string): Violation[] {
+  const violations: Violation[] = [];
+  for (const [path, content] of files.source) {
+    if (path.endsWith('.test.ts') || path.endsWith('.test.tsx')) continue;
+    if (packageName === '@zerotal/core' && path.endsWith('errors/ZerotalError.ts')) continue;
+    // Client-bundle code can't import the server-only ZerotalError; it defines its
+    // own native-Error base (e.g. FlowClientError) for the CSP-safe runtime.
+    if (/(^|\/)client\//.test(path)) continue;
+    if (/\bclass\s+\w+\s+extends\s+Error\b/.test(content)) violations.push({ rule: 'error-base', severity: 'medium', message: `${path}: error classes must extend ZerotalError, not Error` });
+  }
+  return violations;
+}
+
+/** Lint every package under `packagesDir` and return a report per package. */
+export async function lintPackages(packagesDir: string): Promise<PackageReport[]> {
+  const reports: PackageReport[] = [];
+  let entries: string[];
+  try {
+    const glob = new Bun.Glob('*/package.json');
+    entries = [];
+    for await (const relativePath of glob.scan({ cwd: packagesDir, onlyFiles: true })) entries.push(relativePath.replace(/\\/g, '/').split('/')[0]!);
+  } catch { return reports; }
+  entries.sort();
+  for (const dir of entries) {
+    const absoluteDir = `${packagesDir}/${dir}`;
+    const files = await _readPackage(absoluteDir);
+    const packageName = (files.packageJson?.['name'] as string | undefined) ?? `@zerotal/${dir}`;
+    const violations: Violation[] = [
+      ..._checkProviderLocation(files),
+      ..._checkProviderMetadata(files),
+      ..._checkConfigFactory(files),
+      ..._checkConfigDeepMerge(files),
+      ..._checkTests(files),
+      ..._checkPackaging(files),
+      ..._checkErrorDiscipline(files, packageName),
+    ];
+    reports.push({ package: packageName, violations });
+  }
+  return reports;
+}
+
+/** Total the violation count across all package reports. */
+export function countViolations(reports: PackageReport[]): number {
+  return reports.reduce((total, report) => total + report.violations.length, 0);
+}

package/src/build/PackageScaffold.ts

@@ -0,0 +1,127 @@
+/**
+ * Generates the source files for a new `@zerotal/*` package — its package.json,
+ * config factory, manager, service provider, facade, and a starter test — ready
+ * to write to disk.
+ */
+
+/**
+ * Normalise a raw package name into its kebab-case `token` (without the
+ * `@zerotal/` scope) and its PascalCase form.
+ */
+export function packageNames(rawName: string): { token: string; pascal: string } {
+  const token = rawName.trim().toLowerCase().replace(/^@zerotal\//, '').replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+  const pascal = token.split('-').filter(Boolean).map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join('');
+  return { token, pascal };
+}
+
+/** Build the file map (path → contents) for a new package named `rawName`. */
+export function scaffoldPackage(rawName: string): Map<string, string> {
+  const { token, pascal } = packageNames(rawName);
+  const files = new Map<string, string>();
+
+  files.set('package.json', JSON.stringify({
+    name: `@zerotal/${token}`,
+    version: '0.0.1',
+    private: false,
+    type: 'module',
+    main: './src/index.ts',
+    types: './src/index.ts',
+    exports: { '.': './src/index.ts' },
+    scripts: {
+      build: 'bun build ./src/index.ts --outdir ./dist --target bun --format esm',
+      test: 'bun test',
+      typecheck: 'tsc --noEmit',
+    },
+    dependencies: { '@zerotal/core': 'workspace:*' },
+    devDependencies: { typescript: '*' },
+  }, null, 2) + '\n');
+
+  files.set('src/index.ts',
+`// @zerotal/${token} — public API barrel
+export { ${pascal}Provider } from './provider/${pascal}Provider.ts';
+export { ${pascal} } from './facades/${pascal}.ts';
+export { ${pascal}Manager } from './${pascal}Manager.ts';
+export { ${pascal}Config } from './config.ts';
+export type { ${pascal}ConfigShape } from './config.ts';
+`);
+
+  files.set('src/config.ts',
+`import { deepMerge } from '@zerotal/core';
+
+export interface ${pascal}ConfigShape {
+  /** Example option — replace with your package's real config. */
+  enabled: boolean;
+}
+
+const defaults: ${pascal}ConfigShape = {
+  enabled: true,
+};
+
+export function ${pascal}Config(options: Partial<${pascal}ConfigShape> = {}): ${pascal}ConfigShape {
+  return deepMerge(defaults, options);
+}
+`);
+
+  files.set(`src/${pascal}Manager.ts`,
+`import type { ${pascal}ConfigShape } from './config.ts';
+
+export class ${pascal}Manager {
+  constructor(private readonly config: ${pascal}ConfigShape) {}
+
+  isEnabled(): boolean {
+    return this.config.enabled;
+  }
+}
+`);
+
+  files.set(`src/provider/${pascal}Provider.ts`,
+`import { ServiceProvider } from '@zerotal/core';
+import type { AppEnvironment, ConfigManager } from '@zerotal/core';
+import { ${pascal}Manager } from '../${pascal}Manager.ts';
+import { ${pascal}Config, type ${pascal}ConfigShape } from '../config.ts';
+
+declare module '@zerotal/core' {
+  interface ContainerBindings {
+    '${token}': ${pascal}Manager;
+  }
+}
+
+export class ${pascal}Provider extends ServiceProvider {
+  static override provides = ['${token}'] as const;
+  static override environments: AppEnvironment[] = ['web', 'console', 'test', 'repl'];
+
+  override onRegister(): void {
+    this.app.container.singleton('${token}', () => {
+      const config = this.app.container.makeSync('config') as ConfigManager;
+      const options = config.get<Partial<${pascal}ConfigShape>>('${token}', {});
+      return new ${pascal}Manager(${pascal}Config(options));
+    });
+  }
+
+  override async onBooted(): Promise<void> {
+    await this.app.container.make('${token}');
+  }
+}
+`);
+
+  files.set(`src/facades/${pascal}.ts`,
+`import { createFacade } from '@zerotal/core';
+
+export const ${pascal} = createFacade('${token}');
+`);
+
+  files.set(`src/${pascal}.test.ts`,
+`import { describe, it, expect } from 'bun:test';
+import { ${pascal}Manager } from './${pascal}Manager.ts';
+import { ${pascal}Config } from './config.ts';
+
+describe('${pascal}Manager', () => {
+  it('reflects its config', () => {
+    expect(new ${pascal}Manager(${pascal}Config()).isEnabled()).toBe(true);
+    expect(new ${pascal}Manager(${pascal}Config({ enabled: false })).isEnabled()).toBe(false);
+  });
+});
+`);
+
+  return files;
+}