@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.131

package/src/server/dev-span-processor.ts

@@ -1,78 +0,0 @@
-/**
- * DevSpanProcessor — Custom OTEL SpanProcessor that drives dev log output.
- *
- * Collects completed spans per-request (correlated by trace ID). When the
- * root span (http.server.request) ends, all child spans are already collected
- * (child spans end before parent in OTEL). The processor formats the span
- * tree and writes it to stderr.
- *
- * This replaces the old DevLogEmitter/DevLogEvents system. OTEL spans are
- * now the single source of truth for dev logging — no more parallel event
- * systems that can drift.
- *
- * Design doc: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
- */
-
-import type { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import type { Span, Context } from '@opentelemetry/api';
-import {
-  formatSpanTree,
-  formatSpanSummary,
-  formatJson,
-  type DevLogMode,
-  type DevLoggerConfig,
-} from './dev-logger.js';
-
-export class DevSpanProcessor implements SpanProcessor {
-  private spansByTrace = new Map<string, ReadableSpan[]>();
-  private mode: DevLogMode;
-  private config: DevLoggerConfig;
-
-  constructor(config: DevLoggerConfig) {
-    this.config = config;
-    this.mode = config.mode ?? 'tree';
-  }
-
-  onStart(_span: Span, _context: Context): void {
-    // No action needed on span start — we collect on end.
-  }
-
-  onEnd(span: ReadableSpan): void {
-    const traceId = span.spanContext().traceId;
-
-    let spans = this.spansByTrace.get(traceId);
-    if (!spans) {
-      spans = [];
-      this.spansByTrace.set(traceId, spans);
-    }
-    spans.push(span);
-
-    // Root span signals request completion — all child spans are already
-    // collected because OTEL ends child spans before parent spans.
-    if (span.name === 'http.server.request') {
-      const output = this.format(spans);
-      if (output) {
-        process.stderr.write(output);
-      }
-      this.spansByTrace.delete(traceId);
-    }
-  }
-
-  private format(spans: ReadableSpan[]): string {
-    if (this.mode === 'quiet') return '';
-    if (this.mode === 'json') return formatJson(spans);
-    if (this.mode === 'summary') return formatSpanSummary(spans, this.config);
-    // Both 'tree' and 'verbose' use the tree formatter.
-    // verbose will show additional detail (every component render) once
-    // component-level spans are wired.
-    return formatSpanTree(spans, this.config);
-  }
-
-  async shutdown(): Promise<void> {
-    this.spansByTrace.clear();
-  }
-
-  async forceFlush(): Promise<void> {
-    // Nothing to flush — output happens synchronously in onEnd.
-  }
-}

package/src/server/manifest-status-resolver.ts

@@ -1,215 +0,0 @@
-/**
- * Manifest-compatible status-code file resolver.
- *
- * The existing status-code-resolver.ts works with SegmentNode (Map-based).
- * This module works with ManifestSegmentNode (object-based) for use at
- * runtime in the RSC/SSR entries, where the route manifest provides
- * plain objects instead of Maps.
- *
- * Supports two format families:
- * - 'component' (default): .tsx/.jsx/.mdx status files → React rendering pipeline
- * - 'json': .json status files → raw JSON response, no React
- *
- * Follows the same fallback chains as status-code-resolver.ts:
- *
- * **Component chain (4xx):**
- *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
- *   Pass 4 — framework default (returns null)
- *
- * **JSON chain (4xx):**
- *   Pass 1 — json status files (leaf → root): {status}.json → 4xx.json
- *   Pass 2 — framework default JSON (returns null, caller provides bare JSON)
- *
- * See design/10-error-handling.md §"Status-Code Files"
- */
-
-import type { ManifestSegmentNode } from './route-matcher.js';
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-/** A file reference in the manifest (lazy import + path). */
-interface ManifestFile {
-  load: () => Promise<unknown>;
-  filePath: string;
-}
-
-/** How the status-code file was matched. */
-export type ManifestStatusFileKind =
-  | 'exact' // e.g. 403.tsx matched status 403
-  | 'category' // e.g. 4xx.tsx matched status 403
-  | 'legacy' // e.g. not-found.tsx matched status 404
-  | 'error'; // error.tsx as last resort
-
-/** Response format family for status-code resolution. */
-export type ManifestStatusFileFormat = 'component' | 'json';
-
-/** Result of resolving a status-code file from manifest segments. */
-export interface ManifestStatusFileResolution {
-  /** The matched manifest file (has load() and filePath). */
-  file: ManifestFile;
-  /** The HTTP status code (always the original status, not the file's code). */
-  status: number;
-  /** How the file was matched. */
-  kind: ManifestStatusFileKind;
-  /** Index into the segments array where the file was found. */
-  segmentIndex: number;
-}
-
-// ─── Legacy Compat Mapping ───────────────────────────────────────────────────
-
-const LEGACY_FILE_TO_STATUS: Record<string, number> = {
-  'not-found': 404,
-  'forbidden': 403,
-  'unauthorized': 401,
-};
-
-// ─── Resolver ────────────────────────────────────────────────────────────────
-
-/**
- * Resolve the status-code file to render for a given HTTP status code,
- * using manifest segment nodes (plain objects, not Maps).
- *
- * @param status - The HTTP status code (4xx or 5xx).
- * @param segments - The matched segment chain from root (index 0) to leaf (last).
- * @param format - The response format family ('component' or 'json'). Defaults to 'component'.
- */
-export function resolveManifestStatusFile(
-  status: number,
-  segments: ReadonlyArray<ManifestSegmentNode>,
-  format: ManifestStatusFileFormat = 'component'
-): ManifestStatusFileResolution | null {
-  if (status < 400 || status > 599) {
-    return null;
-  }
-
-  if (format === 'json') {
-    return resolveJson(status, segments);
-  }
-
-  if (status <= 499) {
-    return resolve4xx(status, segments);
-  }
-
-  return resolve5xx(status, segments);
-}
-
-/**
- * 4xx component fallback chain (three separate passes):
- *   Pass 1 — status files (leaf → root): {status}.tsx → 4xx.tsx
- *   Pass 2 — legacy compat (leaf → root): not-found.tsx / forbidden.tsx / unauthorized.tsx
- *   Pass 3 — error.tsx (leaf → root)
- */
-function resolve4xx(
-  status: number,
-  segments: ReadonlyArray<ManifestSegmentNode>
-): ManifestStatusFileResolution | null {
-  const statusStr = String(status);
-
-  // Pass 1: status files across all segments (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.statusFiles) continue;
-
-    // Exact match first
-    const exact = segment.statusFiles[statusStr];
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    // Category catch-all
-    const category = segment.statusFiles['4xx'];
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
-  }
-
-  // Pass 2: legacy compat files (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.legacyStatusFiles) continue;
-
-    for (const [name, legacyStatus] of Object.entries(LEGACY_FILE_TO_STATUS)) {
-      if (legacyStatus === status) {
-        const file = segment.legacyStatusFiles[name];
-        if (file) {
-          return { file, status, kind: 'legacy', segmentIndex: i };
-        }
-      }
-    }
-  }
-
-  // Pass 3: error.tsx (leaf → root)
-  for (let i = segments.length - 1; i >= 0; i--) {
-    if (segments[i].error) {
-      return { file: segments[i].error!, status, kind: 'error', segmentIndex: i };
-    }
-  }
-
-  return null;
-}
-
-/**
- * 5xx component fallback chain (single pass, per-segment):
- *   At each segment (leaf → root): {status}.tsx → 5xx.tsx → error.tsx
- */
-function resolve5xx(
-  status: number,
-  segments: ReadonlyArray<ManifestSegmentNode>
-): ManifestStatusFileResolution | null {
-  const statusStr = String(status);
-
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-
-    if (segment.statusFiles) {
-      const exact = segment.statusFiles[statusStr];
-      if (exact) {
-        return { file: exact, status, kind: 'exact', segmentIndex: i };
-      }
-
-      const categoryKey = '5xx';
-      const category = segment.statusFiles[categoryKey];
-      if (category) {
-        return { file: category, status, kind: 'category', segmentIndex: i };
-      }
-    }
-
-    if (segment.error) {
-      return { file: segment.error, status, kind: 'error', segmentIndex: i };
-    }
-  }
-
-  return null;
-}
-
-/**
- * JSON fallback chain (for both 4xx and 5xx):
- *   At each segment (leaf → root): {status}.json → {category}.json
- *   No legacy compat, no error.tsx — JSON chain terminates at category catch-all.
- */
-function resolveJson(
-  status: number,
-  segments: ReadonlyArray<ManifestSegmentNode>
-): ManifestStatusFileResolution | null {
-  const statusStr = String(status);
-  const categoryKey = status >= 500 ? '5xx' : '4xx';
-
-  for (let i = segments.length - 1; i >= 0; i--) {
-    const segment = segments[i];
-    if (!segment.jsonStatusFiles) continue;
-
-    const exact = segment.jsonStatusFiles[statusStr];
-    if (exact) {
-      return { file: exact, status, kind: 'exact', segmentIndex: i };
-    }
-
-    const category = segment.jsonStatusFiles[categoryKey];
-    if (category) {
-      return { file: category, status, kind: 'category', segmentIndex: i };
-    }
-  }
-
-  return null;
-}

package/src/server/prerender.ts

@@ -1,139 +0,0 @@
-/**
- * Pre-rendering types and utilities.
- *
- * A `prerender.ts` file in a route segment signals the framework to
- * pre-render the route's shell at build time. This module defines the
- * types that a user exports from `prerender.ts` and utilities for
- * loading and validating those exports.
- *
- * Design doc: design/15-future-prerendering.md
- */
-
-import { parseCacheLife } from '#/plugins/cache-transform.js';
-
-// ---------------------------------------------------------------------------
-// Types — user-facing exports from prerender.ts
-// ---------------------------------------------------------------------------
-
-/**
- * The shape of a prerender.ts module's exports.
- *
- * ```ts
- * // app/docs/[slug]/prerender.ts
- * export async function generateParams() {
- *   return docs.map(d => ({ slug: d.slug }))
- * }
- * export const ttl = '1h'
- * export const tags = ['docs']
- * ```
- */
-export interface PrerenderConfig {
-  /**
-   * Generate the set of params to pre-render at build time.
-   * Required for dynamic segments (`[param]`).
-   * Optional for static segments (the single URL is pre-rendered automatically).
-   */
-  generateParams?: () => Promise<Record<string, string>[]> | Record<string, string>[];
-
-  /**
-   * How long the pre-rendered shell is considered fresh.
-   * Accepts duration strings ('30s', '5m', '1h', '2d', '1w') or seconds as a number.
-   * Default: Infinity (cache until explicit invalidation).
-   */
-  ttl?: string | number;
-
-  /**
-   * Invalidation tags. Calling `revalidateTag('docs')` purges all
-   * pre-rendered shells with that tag.
-   */
-  tags?: string[];
-
-  /**
-   * Fallback strategy for dynamic routes without `generateParams`.
-   * Only valid in `output: 'static'` mode.
-   * - `'shell'`: emit a single pre-rendered shell that serves as client-side fallback
-   */
-  fallback?: 'shell';
-}
-
-// ---------------------------------------------------------------------------
-// Parsed prerender config — framework-internal, with TTL resolved to seconds
-// ---------------------------------------------------------------------------
-
-export interface ResolvedPrerenderConfig {
-  /** TTL in seconds. Infinity if not set. */
-  ttlSeconds: number;
-  /** Invalidation tags */
-  tags: string[];
-  /** The generateParams function, if provided */
-  generateParams?: () => Promise<Record<string, string>[]> | Record<string, string>[];
-  /** Fallback strategy */
-  fallback?: 'shell';
-}
-
-/**
- * Resolve raw prerender.ts exports into a normalized config.
- *
- * Validates:
- * - `ttl` is a valid duration string or number
- * - `tags` is an array of strings
- * - `fallback` is 'shell' or undefined
- */
-export function resolvePrerenderConfig(raw: PrerenderConfig): ResolvedPrerenderConfig {
-  const ttlSeconds = raw.ttl != null ? parseCacheLife(raw.ttl) : Infinity;
-
-  const tags = raw.tags ?? [];
-  if (!Array.isArray(tags) || tags.some((t) => typeof t !== 'string')) {
-    throw new Error(
-      `prerender.ts: tags must be an array of strings. Got: ${JSON.stringify(raw.tags)}`
-    );
-  }
-
-  if (raw.fallback != null && raw.fallback !== 'shell') {
-    throw new Error(
-      `prerender.ts: fallback must be 'shell' or omitted. Got: ${JSON.stringify(raw.fallback)}`
-    );
-  }
-
-  return {
-    ttlSeconds,
-    tags,
-    generateParams: raw.generateParams,
-    fallback: raw.fallback,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Build diagnostics
-// ---------------------------------------------------------------------------
-
-export interface PrerenderDiagnostic {
-  type: 'DYNAMIC_SEGMENT_NO_PARAMS';
-  segmentPath: string;
-  message: string;
-}
-
-/**
- * Check if a dynamic segment has `generateParams` when prerender.ts is present.
- * If not, emit a diagnostic — the route falls back to SSR.
- */
-export function checkDynamicSegmentParams(
-  segmentPath: string,
-  isDynamic: boolean,
-  hasGenerateParams: boolean,
-  fallback?: 'shell'
-): PrerenderDiagnostic | null {
-  if (!isDynamic) return null;
-  if (hasGenerateParams) return null;
-  if (fallback === 'shell') return null;
-
-  return {
-    type: 'DYNAMIC_SEGMENT_NO_PARAMS',
-    segmentPath,
-    message:
-      `Dynamic segment "${segmentPath}" has prerender.ts but no generateParams(). ` +
-      `The route will fall back to SSR at request time. ` +
-      `Add generateParams() to pre-render specific param values, ` +
-      `or set fallback: 'shell' (static mode only) for a client-side fallback shell.`,
-  };
-}