@spfn/core 0.3.0-beta.4 → 0.3.0-beta.6

package/README.md

@@ -185,18 +185,144 @@ import type { AppRouter } from '@/server/router';
 
 export const api = createApi<AppRouter>();
 
-// anywhere — server component, client component, or server action:
+// the same client in a Server Component, a Client Component or a Server Action:
 const user = await api.getUser.call({ params: { id: '123' } });    // typed { id, name }
 const made = await api.createUser.call({ body: { name: 'A' } });
 ```
 
+That the client is isomorphic does not make the three callers interchangeable. **A page's
+initial data is awaited in the Server Component**, where
+`api.getUser.fetchOptions({ next: { revalidate, tags } }).call(…)` participates in
+Next.js caching and reaches the backend without a browser round trip. Fetching that same
+first paint from a `'use client'` component inside a `useEffect` is the anti-pattern: it
+ships a loading state and a second network hop for data the server already had. Client
+Components and Server Actions are for what happens after the first paint — interaction
+and mutation. Cache tags, revalidation and SSR cookie forwarding are in
+[the Next.js bridge docs](https://superfunction.xyz/docs/packages/core/nextjs).
+
+---
+
+## How does a repository talk to the database?
+
+Through `BaseRepository`. Extending it gives a repository two transaction-aware
+connections — `this.db` (write/primary) and `this.readDb` (the replica, when one is
+configured) — plus the CRUD set as protected methods.
+
+```typescript
+// server/repositories/order.ts
+import { BaseRepository } from '@spfn/core/db';
+import { desc } from 'drizzle-orm';
+import { orders } from '../entities/order';
+
+export class OrderRepository extends BaseRepository
+{
+    findRecentFor(userId: string)
+    {
+        return this._findMany(orders, { where: { userId }, orderBy: desc(orders.createdAt) });
+    }
+
+    place(data: { userId: string; total: number })
+    {
+        return this._create(orders, data);
+    }
+}
+
+export const orderRepo = new OrderRepository();
+```
+
+Handlers never import drizzle query builders; repositories do. `_findMany` reads through
+`this.readDb`, `_create` writes through `this.db`, and both getters resolve to the active
+transaction's connection when there is one — so the same method is correct inside a
+transaction and outside it. When a helper cannot express a query, drop to
+`this.readDb.select()…` inside the repository rather than in the handler. The full
+protected CRUD set is in [src/db](./src/db/README.md).
+
+---
+
+## Where do transactions and their side effects go?
+
+`Transactional()` covers the route case — commit on return, rollback on throw. Two rules
+decide the rest.
+
+**Nothing takes a `tx` parameter.** The transaction travels in AsyncLocalStorage, so
+`this.db` inside a repository already resolves to it. A service that accepts `tx` and
+threads it downward re-implements propagation that already happened, and the first caller
+that forgets to pass it writes outside the transaction. For a service, script or job with
+no route around it, open one with `runInTransaction(fn, options?)`;
+`runWithTransaction(tx, txId, fn)` is the lower-level primitive that binds an existing
+Drizzle transaction into the context.
+
+**Side effects go on the commit hooks, not inline.** An event emitted or a mail sent from
+inside the transaction still went out when the transaction later rolls back.
+
+| Hook | When it runs | What it is for |
+|---|---|---|
+| `onBeforeCommit(fn)` | Inside the still-open transaction, just before commit — a throw aborts and rolls back | Last-moment invariant checks, and statements that must land in the same commit |
+| `onAfterCommit(fn)` | After the root transaction commits, outside the transaction context; errors are logged, never thrown | Events, mail, cache invalidation — anything the outside world observes |
+| `onAfterRollback(fn)` | After the root transaction rolls back, before the causing error propagates; errors are logged, never thrown | Undoing external work that cannot roll itself back, such as an object already uploaded |
+
+All three import from `@spfn/core/db`, can be registered anywhere inside the transaction,
+and bubble to the **root** transaction — a nested block's callbacks fire on the outermost
+outcome, not on a savepoint's.
+
+```typescript
+import { runInTransaction, onAfterCommit } from '@spfn/core/db';
+
+export async function placeOrder(input: { userId: string; total: number })
+{
+    return runInTransaction(async () =>
+    {
+        const order = await orderRepo.place(input);   // no tx argument, at any depth
+        onAfterCommit(() => orderPlacedEvent.emit({ orderId: order.id }));
+
+        return order;
+    });
+}
+```
+
+---
+
+## What else can defineServerConfig configure?
+
+`.port()` and `.routes()` are the two every app calls. The rest of the builder is how an
+app wires its infrastructure without touching the server's boot sequence. Every method
+returns the builder; `.build()` ends the chain.
+
+| Method | What it configures |
+|---|---|
+| `.port(n)` / `.host(s)` | Where the server listens |
+| `.routes(router)` | The `defineRouter` router to mount, with its own `.use()` and `.packages()` |
+| `.jobs(router, config?)` | Background jobs — a `defineJobRouter`, plus pg-boss options |
+| `.events(router, config?)` | SSE streaming — a `defineEventRouter`, served at `GET /events/stream` |
+| `.websockets(router, config?)` | Bidirectional WebSockets — a `defineWSRouter`, served at `WS /ws` |
+| `.workflows(router, config?)` | `@spfn/workflow` orchestration; the engine starts once the database is ready |
+| `.lifecycle(hooks)` | Boot and shutdown hooks. Callable more than once; hooks run in registration order |
+| `.migrations(opts)` | The migration boot gate — `{ allowPending: true }` lets a server start behind its migrations |
+| `.database(opts)` | Connection and pool settings |
+| `.infrastructure(opts)` | Which infrastructure is initialized at boot |
+| `.healthCheck(opts)` | The health endpoint |
+| `.serverTime(clock)` | The clock behind `GET /_core/time`; normally left at the default |
+| `.middleware(opts)` | The built-in middleware — `ErrorHandler`, `RequestLogger` |
+| `.use(handlers)` | Additional global Hono middleware |
+| `.middlewares(named)` | Global middleware under names, so a route can `.skip([...])` it |
+| `.cors(opts)` | CORS |
+| `.rateLimit(opts)` | A global default limiter plus the named policies routes resolve against |
+| `.proxyGuard(opts)` | Trusted-proxy signature and origin verification, resolved to a `clientType` |
+| `.outboundFetch(opts)` | The SSRF policy `safeFetch` applies to outbound calls |
+| `.timeout(opts)` / `.shutdown(opts)` | Request timeouts and graceful shutdown |
+| `.debug(bool)` | Debug logging |
+
+The options each one takes are in [src/server](./src/server/README.md).
+
 ---
 
 ## Which import path do I use for what?
 
 There is **no root barrel**: `import … from '@spfn/core'` does not resolve. Every symbol
 comes from a subpath, and the table below is the complete public surface — one row per
-entry in `package.json` `exports`. Each module has its own README with the API detail.
+entry in `package.json` `exports`, with a single exclusion: `./client` is still listed in
+`exports` but the build no longer emits it, so it has no row (see [Pitfalls](#pitfalls)).
+Each module has its own README with the API detail.
 
 | Import path | Purpose | Doc |
 |-------------|---------|-----|
@@ -207,16 +333,17 @@ entry in `package.json` `exports`. Each module has its own README with the API d
 | `@spfn/core/nextjs/server` | Server-only: `createRpcProxy({ routeMap })`, `registerInterceptors`. Uses `next/headers`. | [src/nextjs](./src/nextjs/README.md) |
 | `@spfn/core/db` | PostgreSQL through Drizzle: CRUD helpers, `BaseRepository`, schema helpers, transactions, Postgres error mapping. One entry point for all of it. | [src/db](./src/db/README.md) |
 | `@spfn/core/db` → manager | Connection lifecycle, pool, primary/replica, health check, reconnect (`initDatabase`, `getDatabase`). Re-exported from `@spfn/core/db`. | [src/db/manager](./src/db/manager/README.md) |
-| `@spfn/core/db` → migrations | Which migrations each installed function package ships, and which the database has applied (`collectMigrationStatus`, `discoverFunctionMigrations`). What `spfn db status`, the boot gate and health all read. Re-exported from `@spfn/core/db`. | [src/db/migrations](./src/db/migrations/index.ts) |
+| `@spfn/core/db` → migrations | Which migrations each installed function package ships, and which the database has applied (`collectMigrationStatus`, `discoverFunctionMigrations`). What `spfn db status`, the boot gate and health all read. Re-exported from `@spfn/core/db`. | [src/db/migrations](https://github.com/fxylabs/spfn/blob/main/packages/core/src/db/migrations/index.ts) |
 | `@spfn/core/db` → schema | Drizzle column helpers (`id`, `uuid`, `timestamps`, `foreignKey`, `enumText`, `typedJsonb`, `softDelete`, …). Re-exported from `@spfn/core/db`. | [src/db/schema](./src/db/schema/README.md) |
 | `@spfn/core/db` → transaction | `Transactional()` middleware and `runInTransaction`; the transaction reaches every repository through AsyncLocalStorage. Re-exported from `@spfn/core/db`. | [src/db/transaction](./src/db/transaction/README.md) |
 | `@spfn/core/middleware` | Built-in Hono middleware: `ErrorHandler`, `RequestLogger` and its masking helper. | [src/middleware](./src/middleware/README.md) |
 | `@spfn/core/errors` | Serializable HTTP and database error classes, plus `ErrorRegistry` so an error survives the trip to the client as its own class. | [src/errors](./src/errors/README.md) |
 | `@spfn/core/security` | `safeFetch` — a drop-in `fetch` hardened against SSRF, including DNS rebinding, by pinning the connection to a validated IP. | [src/security](./src/security/README.md) |
-| `@spfn/core/authz` | Ownership guards. `requireOwner(resource, userId)` makes "load it, then check it belongs to the requester" one call, so a handler cannot forget it. | [src/authz/index.ts](./src/authz/index.ts) |
+| `@spfn/core/authz` | Ownership guards. `requireOwner(resource, userId)` makes "load it, then check it belongs to the requester" one call, so a handler cannot forget it. | [src/authz/index.ts](https://github.com/fxylabs/spfn/blob/main/packages/core/src/authz/index.ts) |
 | `@spfn/core/env` | Schema-based environment validation, isomorphic. | [src/env](./src/env/README.md) |
 | `@spfn/core/env/loader` | The **server-only** `.env` file loader (uses `node:fs`). | [src/env](./src/env/README.md) |
 | `@spfn/core/config` | `@spfn/core`'s own validated env config (`env`, `envSchema`, `registry`), built on `@spfn/core/env`. | [src/config](./src/config/README.md) |
+| `@spfn/core/app-config` | Reads `spfn.config.js` — the one committed place that says which ports and host the app is served on (`loadAppConfig`, `resolvePorts`, `resolveHost`, `PORT_DEFAULTS`). Deliberately side-effect free, so the CLI can import it before an app's environment exists. | [src/app-config/index.ts](https://github.com/fxylabs/spfn/blob/main/packages/core/src/app-config/index.ts) |
 | `@spfn/core/logger` | Structured singleton `logger` with child loggers and level masking. No dependencies. | [src/logger](./src/logger/README.md) |
 | `@spfn/core/cache` | Valkey/Redis singleton over ioredis (`getCache`, `getCacheRead`). Degrades to disabled rather than throwing. | [src/cache](./src/cache/README.md) |
 | `@spfn/core/job` | Background jobs on pg-boss: a fluent `job()` builder, cron, run-once, event-driven, `defineJobRouter`. | [src/job](./src/job/README.md) |
@@ -227,6 +354,7 @@ entry in `package.json` `exports`. Each module has its own README with the API d
 | `@spfn/core/event/ws/client` | Browser WebSocket client. | [src/event](./src/event/README.md) |
 | `@spfn/core/codegen` | The codegen orchestrator and the built-in generators: `@spfn/core:route-map` for the proxy's route map, `@spfn/core:contract` for the client contract. | [src/codegen](./src/codegen/README.md) |
 | `@spfn/core/contract` | Route contracts for clients that ship separately: collect, snapshot, and the build gate that refuses a breaking change. | [src/contract](./src/contract/README.md) |
+| `@spfn/core/ops` | The operations surface `spfn ops` drives: `opsRoute`, `createOpsRouter`, `defineOpsModule`, and the manifest the CLI discovers commands from. Structure only — the router is always authenticated, and token verification lives in `@spfn/auth`. | [How do I operate the app from the terminal?](#how-do-i-operate-the-app-from-the-terminal) |
 
 `db/manager`, `db/schema` and `db/transaction` are **not** package subpaths of their own.
 They are internal modules re-exported by `@spfn/core/db` — import their symbols from
@@ -516,6 +644,57 @@ spfn ops call listSignups --query limit=50            # invoke one
 spfn ops call listSignups --describe                  # print its usage (--json for raw schemas)
 ```
 
+### Can a package ship ops commands?
+
+It can describe them. Whether they are reachable is your application's decision, made in
+the `createOpsRouter` call — installing a package never adds anything to your ops surface.
+Available from **0.3.0-beta.5**.
+
+```typescript
+// in the package
+export const ledgerOpsModule = defineOpsModule({
+    id: 'ledger',
+    source: '@acme/ledger',
+    contractVersion: '1.0.0',
+    summary: 'Ledger diagnostics',
+    commands: {
+        verify: {
+            summary: 'Verify ledger invariants',
+            effect: 'read',                                  // read | write | destructive
+            scopes: ['ledger:read'],
+            route: opsRoute.get('/ledger/verify').handler(verifyLedger),
+        },
+    },
+});
+
+// in the application — nothing is mounted until this line names it
+export const opsRouter = createOpsRouter({ listSignups }, {
+    auth: opsTokenAuth,
+    authorize: requireOpsScope,
+    modules: [ledgerOpsModule],
+});
+```
+
+A module command is named `<module>.<command>` (`ledger.verify`) and its route must live
+under `/_ops/<module>/`. The scopes it declares become a server-side guard, run after
+authentication — `authorize` is required as soon as any module is mounted, and it is passed
+in rather than imported so core stays independent of `@spfn/auth`.
+
+What is refused at definition time: a path that could decode its way out of the module's
+namespace, two commands in one module that could answer the same URL, and an app route that
+overlaps a mounted module's command. That last one matters because the alternative is a
+surface where which command answers depends on route registration order.
+
+The manifest gains a `modules` array and per-command `module`, `summary`, `effect` and
+`scopes`. All of it is additive — an app that mounts no modules serves exactly the v1
+manifest it served before.
+
+```bash
+spfn ops modules                                      # what is mounted, and from where
+spfn ops list --module ledger                         # just that module's commands
+spfn ops call ledger.compact --yes                    # effect=destructive needs this
+```
+
 Authentication is an ops token from [`@spfn/auth`](../auth/README.md#ops-tokens-spfn-ops):
 scoped, revocable, hash-stored, issued with `spfn ops token issue` against the running app
 — the CLI signs in as an administrator, so issuance needs no database access. On macOS the

package/dist/authz/index.js

@@ -1,4 +1,4 @@
-import { format } from 'util';
+import { logger } from '@spfn/core/logger';
 
 // src/errors/error-registry.ts
 var ErrorRegistry = class _ErrorRegistry {
@@ -90,386 +90,6 @@ var ErrorRegistry = class _ErrorRegistry {
     return Array.from(this.errors.keys());
   }
 };
-
-// src/logger/types.ts
-var LOG_LEVEL_PRIORITY = {
-  debug: 0,
-  info: 1,
-  warn: 2,
-  error: 3,
-  fatal: 4
-};
-
-// src/logger/formatters.ts
-var SENSITIVE_KEYS = [
-  "password",
-  "passwd",
-  "pwd",
-  "secret",
-  "token",
-  "apikey",
-  "api_key",
-  "accesstoken",
-  "access_token",
-  "refreshtoken",
-  "refresh_token",
-  "authorization",
-  "auth",
-  "cookie",
-  "session",
-  "sessionid",
-  "session_id",
-  "privatekey",
-  "private_key",
-  "creditcard",
-  "credit_card",
-  "cardnumber",
-  "card_number",
-  "cvv",
-  "ssn",
-  "pin"
-];
-var MASKED_VALUE = "***MASKED***";
-function isSensitiveKey(key) {
-  const lowerKey = key.toLowerCase();
-  return SENSITIVE_KEYS.some((sensitive) => lowerKey.includes(sensitive));
-}
-function maskSensitiveData(data, seen = /* @__PURE__ */ new WeakSet()) {
-  if (data === null || data === void 0) {
-    return data;
-  }
-  if (typeof data !== "object") {
-    return data;
-  }
-  if (seen.has(data)) {
-    return "[Circular]";
-  }
-  seen.add(data);
-  if (Array.isArray(data)) {
-    return data.map((item) => maskSensitiveData(item, seen));
-  }
-  const masked = {};
-  for (const [key, value] of Object.entries(data)) {
-    if (isSensitiveKey(key)) {
-      masked[key] = MASKED_VALUE;
-    } else if (typeof value === "object" && value !== null) {
-      masked[key] = maskSensitiveData(value, seen);
-    } else {
-      masked[key] = value;
-    }
-  }
-  return masked;
-}
-var COLORS = {
-  reset: "\x1B[0m",
-  bright: "\x1B[1m",
-  dim: "\x1B[2m",
-  // 로그 레벨 컬러
-  debug: "\x1B[36m",
-  // cyan
-  info: "\x1B[32m",
-  // green
-  warn: "\x1B[33m",
-  // yellow
-  error: "\x1B[31m",
-  // red
-  fatal: "\x1B[35m",
-  // magenta
-  // 추가 컬러
-  gray: "\x1B[90m"
-};
-function formatTimestampHuman(date) {
-  const year = date.getFullYear();
-  const month = String(date.getMonth() + 1).padStart(2, "0");
-  const day = String(date.getDate()).padStart(2, "0");
-  const hours = String(date.getHours()).padStart(2, "0");
-  const minutes = String(date.getMinutes()).padStart(2, "0");
-  const seconds = String(date.getSeconds()).padStart(2, "0");
-  const ms = String(date.getMilliseconds()).padStart(3, "0");
-  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${ms}`;
-}
-function formatError(error) {
-  const lines = [];
-  lines.push(`${error.name}: ${error.message}`);
-  if (error.stack) {
-    const stackLines = error.stack.split("\n").slice(1);
-    lines.push(...stackLines);
-  }
-  if (error.cause instanceof Error) {
-    lines.push(`Caused by: ${formatError(error.cause)}`);
-  } else if (error.cause !== void 0) {
-    lines.push(`Caused by: ${String(error.cause)}`);
-  }
-  return lines.join("\n");
-}
-function formatConsole(metadata, colorize = true) {
-  const parts = [];
-  const timestamp = formatTimestampHuman(metadata.timestamp);
-  if (colorize) {
-    parts.push(`${COLORS.gray}[${timestamp}]${COLORS.reset}`);
-  } else {
-    parts.push(`[${timestamp}]`);
-  }
-  const pid = process.pid;
-  if (colorize) {
-    parts.push(`${COLORS.dim}[pid=${pid}]${COLORS.reset}`);
-  } else {
-    parts.push(`[pid=${pid}]`);
-  }
-  if (metadata.module) {
-    if (colorize) {
-      parts.push(`${COLORS.dim}[module=${metadata.module}]${COLORS.reset}`);
-    } else {
-      parts.push(`[module=${metadata.module}]`);
-    }
-  }
-  if (metadata.context && Object.keys(metadata.context).length > 0) {
-    Object.entries(metadata.context).forEach(([key, value]) => {
-      let valueStr;
-      if (typeof value === "string") {
-        valueStr = value;
-      } else if (typeof value === "object" && value !== null) {
-        try {
-          valueStr = JSON.stringify(value);
-        } catch (error) {
-          valueStr = "[circular]";
-        }
-      } else {
-        valueStr = String(value);
-      }
-      if (colorize) {
-        parts.push(`${COLORS.dim}[${key}=${valueStr}]${COLORS.reset}`);
-      } else {
-        parts.push(`[${key}=${valueStr}]`);
-      }
-    });
-  }
-  const levelStr = metadata.level.toUpperCase();
-  if (colorize) {
-    const color = COLORS[metadata.level];
-    parts.push(`${color}(${levelStr})${COLORS.reset}:`);
-  } else {
-    parts.push(`(${levelStr}):`);
-  }
-  if (colorize) {
-    parts.push(`${COLORS.bright}${metadata.message}${COLORS.reset}`);
-  } else {
-    parts.push(metadata.message);
-  }
-  let output = parts.join(" ");
-  if (metadata.error) {
-    output += "\n" + formatError(metadata.error);
-  }
-  return output;
-}
-
-// src/logger/logger.ts
-var FORMAT_PATTERN = /%[sdifjoOc%]/;
-var Logger = class _Logger {
-  config;
-  module;
-  constructor(config) {
-    this.config = config;
-    this.module = config.module;
-  }
-  /**
-   * Convert unknown error to Error object
-   */
-  toError(error) {
-    if (error instanceof Error) return error;
-    if (typeof error === "string") return new Error(error);
-    if (typeof error === "object" && error !== null) {
-      return new Error(JSON.stringify(error));
-    }
-    return new Error(String(error));
-  }
-  /**
-   * Check if value is a context object (not an error)
-   */
-  isContext(value) {
-    if (typeof value !== "object" || value === null) return false;
-    if (value instanceof Error) return false;
-    const hasStack = "stack" in value && typeof value.stack === "string";
-    if (hasStack) {
-      return false;
-    }
-    return true;
-  }
-  /**
-   * Get current log level
-   */
-  get level() {
-    return this.config.level;
-  }
-  /**
-   * Create child logger (per module)
-   */
-  child(module) {
-    return new _Logger({
-      ...this.config,
-      module
-    });
-  }
-  /**
-   * Common log method with error/context detection
-   */
-  logWithLevel(level, message, errorOrContext, context) {
-    if (errorOrContext !== void 0 && FORMAT_PATTERN.test(message)) {
-      this.log(level, format(message, errorOrContext), void 0, context);
-      return;
-    }
-    if (errorOrContext instanceof Error) {
-      this.log(level, message, errorOrContext, context);
-    } else if (errorOrContext !== void 0 && typeof errorOrContext === "object" && !this.isContext(errorOrContext)) {
-      this.log(level, message, this.toError(errorOrContext), context);
-    } else if (typeof errorOrContext === "string" || typeof errorOrContext === "number" || typeof errorOrContext === "boolean") {
-      this.log(level, message, this.toError(errorOrContext), context);
-    } else {
-      this.log(level, message, void 0, errorOrContext);
-    }
-  }
-  debug(message, errorOrContext, context) {
-    this.logWithLevel("debug", message, errorOrContext, context);
-  }
-  info(message, errorOrContext, context) {
-    this.logWithLevel("info", message, errorOrContext, context);
-  }
-  warn(message, errorOrContext, context) {
-    this.logWithLevel("warn", message, errorOrContext, context);
-  }
-  error(message, errorOrContext, context) {
-    this.logWithLevel("error", message, errorOrContext, context);
-  }
-  fatal(message, errorOrContext, context) {
-    this.logWithLevel("fatal", message, errorOrContext, context);
-  }
-  /**
-   * Log processing (internal)
-   */
-  log(level, message, error, context) {
-    if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[this.config.level]) {
-      return;
-    }
-    const metadata = {
-      timestamp: /* @__PURE__ */ new Date(),
-      level,
-      message,
-      module: this.module,
-      error,
-      // Mask sensitive information in context to prevent credential leaks
-      context: context ? maskSensitiveData(context) : void 0
-    };
-    this.processTransports(metadata);
-  }
-  /**
-   * Process Transports
-   */
-  processTransports(metadata) {
-    const promises = this.config.transports.filter((transport) => transport.enabled).map((transport) => this.safeTransportLog(transport, metadata));
-    Promise.all(promises).catch((error) => {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      process.stderr.write(`[Logger] Transport error: ${errorMessage}
-`);
-    });
-  }
-  /**
-   * Transport log (error-safe)
-   */
-  async safeTransportLog(transport, metadata) {
-    try {
-      await transport.log(metadata);
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      process.stderr.write(`[Logger] Transport "${transport.name}" failed: ${errorMessage}
-`);
-    }
-  }
-  /**
-   * Close all Transports
-   */
-  async close() {
-    const closePromises = this.config.transports.filter((transport) => transport.close).map((transport) => transport.close());
-    await Promise.all(closePromises);
-  }
-};
-
-// src/logger/transports/console.ts
-var ConsoleTransport = class {
-  name = "console";
-  level;
-  enabled;
-  colorize;
-  constructor(config) {
-    this.level = config.level;
-    this.enabled = config.enabled;
-    this.colorize = config.colorize ?? true;
-  }
-  async log(metadata) {
-    if (!this.enabled) {
-      return;
-    }
-    if (LOG_LEVEL_PRIORITY[metadata.level] < LOG_LEVEL_PRIORITY[this.level]) {
-      return;
-    }
-    const message = formatConsole(metadata, this.colorize);
-    if (metadata.level === "warn" || metadata.level === "error" || metadata.level === "fatal") {
-      console.error(message);
-    } else {
-      console.log(message);
-    }
-  }
-};
-
-// src/logger/config.ts
-function getConsoleConfig() {
-  const isProduction = process.env.NODE_ENV === "production";
-  return {
-    level: "debug",
-    enabled: true,
-    colorize: !isProduction
-    // Dev: colored output, Production: plain text
-  };
-}
-function validateEnvironment() {
-  const nodeEnv = process.env.NODE_ENV;
-  if (!nodeEnv) {
-    process.stderr.write(
-      "[Logger] Warning: NODE_ENV is not set. Defaulting to test environment.\n"
-    );
-  }
-}
-function validateConfig() {
-  validateEnvironment();
-}
-
-// src/logger/factory.ts
-function initializeTransports() {
-  const transports = [];
-  const consoleConfig = getConsoleConfig();
-  transports.push(new ConsoleTransport(consoleConfig));
-  return transports;
-}
-function getLogLevel() {
-  const envLevel = process.env.SPFN_LOG_LEVEL || process.env.NEXT_PUBLIC_SPFN_LOG_LEVEL || "info";
-  if (envLevel in LOG_LEVEL_PRIORITY) {
-    return envLevel;
-  }
-  process.stderr.write(
-    `[Logger] Invalid log level "${envLevel}", defaulting to "info"
-`
-  );
-  return "info";
-}
-function initializeLogger() {
-  validateConfig();
-  return new Logger({
-    level: getLogLevel(),
-    transports: initializeTransports()
-  });
-}
-var logger = initializeLogger();
-
-// src/errors/serializable-error.ts
 var RESERVED_RESPONSE_KEYS = /* @__PURE__ */ new Set(["__type", "message", "error"]);
 var AUTHORING_ENVIRONMENTS = /* @__PURE__ */ new Set(["local", "development", "test"]);
 function refuseReservedKey(className, key) {