gorsee 0.2.3 → 0.2.5

package/dist-pkg/server/server-execution.js

@@ -0,0 +1,53 @@
+import { executeEndpointRequest } from "./endpoint-execution.js";
+import { createTraceIds, emitAIEvent } from "../ai/index.js";
+export async function executeServerExecution(options) {
+  const trace = options.trace?.requestId && options.trace?.traceId && options.trace?.spanId ? options.trace : createTraceIds(options.trace), pathname = new URL(options.request.url).pathname;
+  await emitAIEvent({
+    kind: `${options.kind}.start`,
+    severity: "info",
+    source: "runtime",
+    message: `${options.kind} request received`,
+    requestId: trace.requestId,
+    traceId: trace.traceId,
+    spanId: trace.spanId,
+    parentSpanId: trace.parentSpanId,
+    route: options.route,
+    data: {
+      method: options.request.method,
+      pathname,
+      middlewareCount: options.middlewares?.length ?? 0
+    }
+  });
+  const response = await executeEndpointRequest({
+    request: options.request,
+    kind: options.kind,
+    params: options.params,
+    middlewares: options.middlewares,
+    trustedOrigin: options.trustedOrigin,
+    trustForwardedHeaders: options.trustForwardedHeaders,
+    securityPolicy: options.securityPolicy,
+    trace,
+    handler: async (context) => options.handler({
+      ...context,
+      kind: options.kind,
+      trace
+    })
+  });
+  await emitAIEvent({
+    kind: `${options.kind}.finish`,
+    severity: response.status >= 400 ? "warn" : "info",
+    source: "runtime",
+    message: `${options.kind} request completed`,
+    requestId: trace.requestId,
+    traceId: trace.traceId,
+    spanId: trace.spanId,
+    parentSpanId: trace.parentSpanId,
+    route: options.route,
+    data: {
+      method: options.request.method,
+      pathname,
+      status: response.status
+    }
+  });
+  return response;
+}

package/dist-pkg/server/sqlite-cache-store.d.ts

@@ -0,0 +1,13 @@
+import type { CacheStore } from "./cache.js";
+interface SQLiteCacheStoreOptions {
+    maxEntryAgeMs?: number;
+    pruneExpiredOnInit?: boolean;
+    pruneExpiredOnGet?: boolean;
+    pruneExpiredOnSet?: boolean;
+    pruneExpiredOnKeys?: boolean;
+}
+export declare function createSQLiteCacheStore(path?: string, options?: SQLiteCacheStoreOptions): CacheStore & {
+    close(): void;
+    deleteExpired(now?: number): number;
+};
+export {};

package/dist-pkg/server/sqlite-cache-store.js

@@ -0,0 +1,88 @@
+import { Database } from "bun:sqlite";
+import { safeJSONParse } from "../ai/json.js";
+function ensureCacheTable(sqlite) {
+  sqlite.run(`
+    CREATE TABLE IF NOT EXISTS gorsee_route_cache (
+      cache_key TEXT PRIMARY KEY,
+      body TEXT NOT NULL,
+      headers TEXT NOT NULL,
+      status INTEGER NOT NULL,
+      created_at INTEGER NOT NULL,
+      revalidating INTEGER NOT NULL DEFAULT 0
+    )
+  `);
+}
+function pruneExpiredRows(sqlite, maxEntryAgeMs, now = Date.now()) {
+  const cutoff = now - maxEntryAgeMs;
+  return sqlite.prepare("DELETE FROM gorsee_route_cache WHERE created_at <= ?1").run(cutoff).changes ?? 0;
+}
+export function createSQLiteCacheStore(path = ":memory:", options = {}) {
+  const sqlite = new Database(path);
+  sqlite.run("PRAGMA journal_mode=WAL;");
+  ensureCacheTable(sqlite);
+  const {
+    maxEntryAgeMs = 86400000,
+    pruneExpiredOnInit = !0,
+    pruneExpiredOnGet = !0,
+    pruneExpiredOnSet = !0,
+    pruneExpiredOnKeys = !0
+  } = options;
+  if (pruneExpiredOnInit)
+    pruneExpiredRows(sqlite, maxEntryAgeMs);
+  return {
+    async get(key) {
+      if (pruneExpiredOnGet)
+        pruneExpiredRows(sqlite, maxEntryAgeMs);
+      const row = sqlite.prepare(`
+        SELECT body, headers, status, created_at, revalidating
+        FROM gorsee_route_cache
+        WHERE cache_key = ?1
+      `).get(key);
+      if (!row)
+        return;
+      const headers = safeJSONParse(row.headers);
+      if (!headers) {
+        sqlite.prepare("DELETE FROM gorsee_route_cache WHERE cache_key = ?1").run(key);
+        return;
+      }
+      return {
+        body: row.body,
+        headers,
+        status: row.status,
+        createdAt: row.created_at,
+        revalidating: row.revalidating === 1
+      };
+    },
+    async set(key, entry) {
+      if (pruneExpiredOnSet)
+        pruneExpiredRows(sqlite, maxEntryAgeMs);
+      sqlite.prepare(`
+        INSERT INTO gorsee_route_cache (cache_key, body, headers, status, created_at, revalidating)
+        VALUES (?1, ?2, ?3, ?4, ?5, ?6)
+        ON CONFLICT(cache_key) DO UPDATE SET
+          body = excluded.body,
+          headers = excluded.headers,
+          status = excluded.status,
+          created_at = excluded.created_at,
+          revalidating = excluded.revalidating
+      `).run(key, entry.body, JSON.stringify(entry.headers), entry.status, entry.createdAt, entry.revalidating ? 1 : 0);
+    },
+    async delete(key) {
+      sqlite.prepare("DELETE FROM gorsee_route_cache WHERE cache_key = ?1").run(key);
+    },
+    async clear() {
+      sqlite.prepare("DELETE FROM gorsee_route_cache").run();
+    },
+    async keys() {
+      if (pruneExpiredOnKeys)
+        pruneExpiredRows(sqlite, maxEntryAgeMs);
+      return sqlite.prepare("SELECT cache_key FROM gorsee_route_cache").all().map((row) => row.cache_key);
+    },
+    deleteExpired(now = Date.now()) {
+      return pruneExpiredRows(sqlite, maxEntryAgeMs, now);
+    },
+    close() {
+      sqlite.close();
+    }
+  };
+}

package/dist-pkg/server/sse.d.ts

@@ -0,0 +1,9 @@
+export interface SSEOptions {
+    headers?: Record<string, string>;
+}
+export interface SSEStream {
+    response: Response;
+    send: (event: string, data: unknown) => void;
+    close: () => void;
+}
+export declare function createSSEStream(options?: SSEOptions): SSEStream;

package/dist-pkg/server/sse.js

@@ -0,0 +1,34 @@
+export function createSSEStream(options) {
+  let controller = null;
+  const encoder = new TextEncoder, stream = new ReadableStream({
+    start(ctrl) {
+      controller = ctrl;
+    },
+    cancel() {
+      controller = null;
+    }
+  }), response = new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+      ...options?.headers
+    }
+  });
+  function send(event, data) {
+    if (!controller)
+      return;
+    const payload = `event: ${event}
+data: ${JSON.stringify(data)}
+
+`;
+    controller.enqueue(encoder.encode(payload));
+  }
+  function close() {
+    if (controller) {
+      controller.close();
+      controller = null;
+    }
+  }
+  return { response, send, close };
+}

package/dist-pkg/server/static-file.d.ts

@@ -0,0 +1,9 @@
+export interface StaticFileOptions {
+    contentType?: string;
+    cacheControl?: string;
+    request?: Request;
+    etag?: boolean;
+    extraHeaders?: Record<string, string>;
+}
+export declare function serveStaticFile(rootDir: string, relativePath: string, options?: StaticFileOptions): Promise<Response | null>;
+export declare function servePrefixedStaticFile(pathname: string, prefix: string, rootDir: string, options?: StaticFileOptions): Promise<Response | null>;

package/dist-pkg/server/static-file.js

@@ -0,0 +1,43 @@
+import { getMimeType } from "./mime.js";
+import { fileETag, isNotModified } from "./etag.js";
+import { readFile, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+export async function serveStaticFile(rootDir, relativePath, options = {}) {
+  const {
+    contentType,
+    cacheControl,
+    request,
+    etag = !1,
+    extraHeaders = {}
+  } = options;
+  try {
+    const rootPath = await realpath(resolve(rootDir)), candidatePath = resolve(rootPath, relativePath), filePath = await realpath(candidatePath).catch(() => candidatePath), relativePathFromRoot = relative(rootPath, filePath);
+    if (relativePathFromRoot.startsWith("..") || isAbsolute(relativePathFromRoot))
+      return null;
+    const fileBuffer = await readFile(filePath).catch(() => null);
+    if (!fileBuffer)
+      return null;
+    const headers = {
+      "Content-Type": contentType ?? getMimeType(filePath),
+      ...extraHeaders
+    };
+    if (cacheControl)
+      headers["Cache-Control"] = cacheControl;
+    if (etag) {
+      const tag = await fileETag(filePath);
+      if (tag && request && isNotModified(request, tag))
+        return new Response(null, { status: 304, headers: extraHeaders });
+      if (tag)
+        headers.ETag = tag;
+    }
+    return new Response(fileBuffer, { headers });
+  } catch {
+    return null;
+  }
+}
+export async function servePrefixedStaticFile(pathname, prefix, rootDir, options = {}) {
+  if (!pathname.startsWith(prefix))
+    return null;
+  const relativePath = pathname.slice(prefix.length);
+  return serveStaticFile(rootDir, relativePath, options);
+}

package/dist-pkg/server/ws.d.ts

@@ -0,0 +1,18 @@
+export interface WSContext {
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    id: string;
+}
+export type WSHandler = {
+    open?: (ws: WSContext) => void;
+    message?: (ws: WSContext, data: string | ArrayBuffer) => void;
+    close?: (ws: WSContext) => void;
+};
+export declare function joinRoom(room: string, ws: WSContext): void;
+export declare function leaveRoom(room: string, ws: WSContext): void;
+export declare function broadcastToRoom(room: string, data: string, exclude?: WSContext): void;
+export declare function getRoomSize(room: string): number;
+export declare function createWSContext(ws: {
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+}): WSContext;

package/dist-pkg/server/ws.js

@@ -0,0 +1,40 @@
+const rooms = new Map;
+export function joinRoom(room, ws) {
+  let members = rooms.get(room);
+  if (!members) {
+    members = new Set;
+    rooms.set(room, members);
+  }
+  members.add(ws);
+}
+export function leaveRoom(room, ws) {
+  const members = rooms.get(room);
+  if (!members)
+    return;
+  members.delete(ws);
+  if (members.size === 0)
+    rooms.delete(room);
+}
+export function broadcastToRoom(room, data, exclude) {
+  const members = rooms.get(room);
+  if (!members)
+    return;
+  for (const ws of members) {
+    if (ws === exclude)
+      continue;
+    try {
+      ws.send(data);
+    } catch {}
+  }
+}
+export function getRoomSize(room) {
+  return rooms.get(room)?.size ?? 0;
+}
+let wsIdCounter = 0;
+export function createWSContext(ws) {
+  return {
+    send: (data) => ws.send(data),
+    close: (code, reason) => ws.close(code, reason),
+    id: `ws_${++wsIdCounter}`
+  };
+}

package/dist-pkg/server-entry.d.ts

@@ -0,0 +1,19 @@
+export * from "./server/index.js";
+/** @deprecated Prefer "gorsee/auth" when auth is the primary concern. */
+export { createAuth, createMemorySessionStore, createNamespacedSessionStore, createRedisSessionStore, createSQLiteSessionStore, createAuthActionTokenManager, createMemoryAuthActionTokenStore, sessionHasRole, sessionHasPermission, type AuthConfig, type AuthEvent, type AuthEventHandler, type AuthActionTokenClaims, type AuthActionTokenPurpose, type AuthActionTokenReplayStore, type PermissionResolver, type Session, type SessionStore, } from "./auth/index.js";
+/** @deprecated Prefer "gorsee/db" when data access is the primary concern. */
+export { createDB, createPostgresDB, toPostgresSQL, type DB, type PostgresDB, type PostgresClientLike, type PostgresConnectionLike, type PostgresPoolLike, type PostgresQueryResult, runMigrations, createMigration, type MigrationResult, } from "./db/index.js";
+/** @deprecated Prefer "gorsee/security" when security policy is the primary concern. */
+export { securityHeaders, type SecurityConfig, csrfProtection, createCSRFMiddleware, generateCSRFToken, validateCSRFToken, createRateLimiter, createRedisRateLimiter, parseRateLimitWindow, type RateLimiter, type AsyncRateLimiter, type AsyncRateLimitResult, cors, type CORSOptions, } from "./security/index.js";
+/** @deprecated Prefer "gorsee/env" when environment loading is the primary concern. */
+export { env, getPublicEnv, loadEnv } from "./env/index.js";
+/** @deprecated Prefer "gorsee/log" when structured logging is the primary concern. */
+export { log, setLogLevel } from "./log/index.js";
+/** @deprecated Prefer "gorsee/ai" when AI tooling is the primary concern. */
+export { buildAIHealthReport, buildAIContextBundle, buildIDEProjection, configureAIObservability, createAIMCPServer, createAIContextPacket, createAIBridgeHandler, createAIBridgeServer, createIDEProjectionWatcher, createLineReader, emitAIDiagnostic, emitAIEvent, createTraceIds, readAIDiagnosticsSnapshot, readAIEvents, renderAIContextBundleMarkdown, renderAIContextMarkdown, resolveAISessionPackPaths, resolveIDEProjectionPaths, resolveAIStorePaths, resolveAIObservabilityConfig, runWithAITrace, writeAISessionPack, writeIDEProjection, type AIMCPServerOptions, type AIContextPacket, type AIContextBundle, type AIContextSnippet, type AIHealthReport, type AIEvent, type AIEventSeverity, type IDEProjection, type IDEProjectionPaths, type IDEProjectionWatcher, type IDEProjectionWatcherOptions, type AISessionPackConfig, type AISessionPackPaths, type AIStorePaths, type AITraceContext, type AIDiagnostic, type AIObservabilityConfig, type AIBridgeConfig, type AIBridgeServer, type AIBridgeHandler, type AIBridgeServerOptions, type AIBridgeSnapshot, } from "./ai/index.js";
+export { createNodeRedisLikeClient, createIORedisLikeClient, deleteExpiredRedisKeys, type RedisLikeClient, type NodeRedisClientLike, type IORedisClientLike, } from "./server/redis-client.js";
+export { createMemoryJobQueue, defineJob, type JobContext, type JobDefinition, type JobEnqueueOptions, type JobQueue, type JobRunResult, type EnqueuedJob, } from "./server/jobs.js";
+/** @deprecated Prefer "gorsee/i18n" when locale contracts are the primary concern. */
+export { setupI18n, loadLocale, getLocale, getLocales, getDefaultLocale, getFallbackLocales, setLocale, t, plural, negotiateLocale, resolveLocaleFromPath, stripLocalePrefix, withLocalePath, buildHreflangLinks, formatNumber, formatDate, formatRelativeTime, type I18nConfig, type LocaleNegotiationInput, type LocaleNegotiationResult, } from "./i18n/index.js";
+/** @deprecated Prefer "gorsee/content" when content contracts are the primary concern. */
+export { loadContentCollection, parseFrontmatter, extractExcerpt, queryContent, getContentEntryBySlug, type ContentCollectionOptions, type ContentEntry, type ContentQueryOptions, } from "./content/index.js";

package/dist-pkg/server-entry.js

@@ -0,0 +1,93 @@
+export * from "./server/index.js";
+export {
+  createAuth,
+  createMemorySessionStore,
+  createNamespacedSessionStore,
+  createRedisSessionStore,
+  createSQLiteSessionStore,
+  createAuthActionTokenManager,
+  createMemoryAuthActionTokenStore,
+  sessionHasRole,
+  sessionHasPermission
+} from "./auth/index.js";
+export {
+  createDB,
+  createPostgresDB,
+  toPostgresSQL,
+  runMigrations,
+  createMigration
+} from "./db/index.js";
+export {
+  securityHeaders,
+  csrfProtection,
+  createCSRFMiddleware,
+  generateCSRFToken,
+  validateCSRFToken,
+  createRateLimiter,
+  createRedisRateLimiter,
+  parseRateLimitWindow,
+  cors
+} from "./security/index.js";
+export { env, getPublicEnv, loadEnv } from "./env/index.js";
+export { log, setLogLevel } from "./log/index.js";
+export {
+  buildAIHealthReport,
+  buildAIContextBundle,
+  buildIDEProjection,
+  configureAIObservability,
+  createAIMCPServer,
+  createAIContextPacket,
+  createAIBridgeHandler,
+  createAIBridgeServer,
+  createIDEProjectionWatcher,
+  createLineReader,
+  emitAIDiagnostic,
+  emitAIEvent,
+  createTraceIds,
+  readAIDiagnosticsSnapshot,
+  readAIEvents,
+  renderAIContextBundleMarkdown,
+  renderAIContextMarkdown,
+  resolveAISessionPackPaths,
+  resolveIDEProjectionPaths,
+  resolveAIStorePaths,
+  resolveAIObservabilityConfig,
+  runWithAITrace,
+  writeAISessionPack,
+  writeIDEProjection
+} from "./ai/index.js";
+export {
+  createNodeRedisLikeClient,
+  createIORedisLikeClient,
+  deleteExpiredRedisKeys
+} from "./server/redis-client.js";
+export {
+  createMemoryJobQueue,
+  defineJob
+} from "./server/jobs.js";
+export {
+  setupI18n,
+  loadLocale,
+  getLocale,
+  getLocales,
+  getDefaultLocale,
+  getFallbackLocales,
+  setLocale,
+  t,
+  plural,
+  negotiateLocale,
+  resolveLocaleFromPath,
+  stripLocalePrefix,
+  withLocalePath,
+  buildHreflangLinks,
+  formatNumber,
+  formatDate,
+  formatRelativeTime
+} from "./i18n/index.js";
+export {
+  loadContentCollection,
+  parseFrontmatter,
+  extractExcerpt,
+  queryContent,
+  getContentEntryBySlug
+} from "./content/index.js";

package/dist-pkg/testing/index.d.ts

@@ -0,0 +1,98 @@
+import { type ActionFn, type ActionResult } from "../server/action.js";
+import { type DeployArtifactConformanceInput, type DeployArtifactConformanceResult } from "../deploy/conformance.js";
+import { type Context, type MiddlewareFn } from "../server/middleware.js";
+import { type GorseePlugin, type PluginCapability, type PluginDescriptor, type PluginPhase } from "../plugins/index.js";
+/** Create a mock request for testing */
+export declare function createTestRequest(path: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | Record<string, unknown>;
+}): Request;
+/** Create a test context for middleware/loader testing */
+export declare function createTestContext(path: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    body?: string | Record<string, unknown>;
+}): Context;
+/** Run a middleware function with a test context and handler */
+export declare function runTestMiddleware(middleware: MiddlewareFn, ctx: Context, handler?: () => Promise<Response>): Promise<Response>;
+/** Render a component to HTML string for snapshot/assertion testing */
+export declare function renderComponent(component: Function, props?: Record<string, unknown>): string;
+/** Test a loader function directly */
+export declare function testLoader<T>(loader: (ctx: Context) => Promise<T>, path: string, options?: {
+    params?: Record<string, string>;
+    headers?: Record<string, string>;
+}): Promise<T>;
+/** Test an action function through the same wrapper used by the runtime. */
+export declare function testAction<T>(action: ActionFn<T>, path: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    body?: string | Record<string, unknown>;
+}): Promise<ActionResult<T>>;
+/** Test a route handler directly with a framework context. */
+export declare function testRouteHandler(handler: (ctx: Context) => Response | Promise<Response>, path: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    body?: string | Record<string, unknown>;
+}): Promise<Response>;
+/** Validate generated deploy artifacts against explicit contract tokens. */
+export declare function testDeployArtifactConformance(input: DeployArtifactConformanceInput): DeployArtifactConformanceResult;
+/** Assert generated deploy artifacts satisfy explicit contract tokens. */
+export declare function assertTestDeployArtifactConformance(input: DeployArtifactConformanceInput): void;
+export interface FixtureFile {
+    path: string;
+    content: string;
+}
+export interface FixtureAppHarness {
+    rootDir: string;
+    write(): Promise<void>;
+    read(path: string): Promise<string>;
+    listFiles(): Promise<string[]>;
+    cleanup(): Promise<void>;
+}
+export interface WorkspaceFixturePackage {
+    path: string;
+    files: FixtureFile[];
+}
+export interface WorkspaceFixtureHarness extends FixtureAppHarness {
+}
+export declare function createFixtureAppHarness(files: FixtureFile[], rootDir?: string): Promise<FixtureAppHarness>;
+export declare function createWorkspaceFixtureHarness(packages: WorkspaceFixturePackage[], rootFiles?: FixtureFile[], rootDir?: string): Promise<WorkspaceFixtureHarness>;
+export interface PluginConformanceExpectation {
+    middlewareCount?: number;
+    routePaths?: string[];
+    buildPluginNames?: string[];
+    capabilities?: PluginCapability[];
+    pluginOrder?: string[];
+}
+export interface PluginConformanceResult {
+    middlewareCount: number;
+    routePaths: string[];
+    buildPluginNames: string[];
+    capabilities: PluginCapability[];
+    pluginOrder: string[];
+    descriptors: PluginDescriptor[];
+}
+export interface PluginConformanceHarness {
+    register(plugin: GorseePlugin): void;
+    setupAll(): Promise<void>;
+    runPhase(phase: PluginPhase): Promise<void>;
+    teardownAll(): Promise<void>;
+    getResult(): PluginConformanceResult;
+    testRoute(path: string, requestPath?: string): Promise<Response>;
+}
+export declare function createPluginConformanceHarness(config?: Record<string, unknown>): PluginConformanceHarness;
+export declare function validatePluginConformance(plugin: GorseePlugin, expectation?: PluginConformanceExpectation, config?: Record<string, unknown>): Promise<PluginConformanceResult>;
+export interface RuntimeFixture {
+    htmlWrites: string[];
+    historyWrites: string[];
+    removedCssCount: () => number;
+    setFetch(handler: typeof fetch): void;
+    navigate(url: string, pushState?: boolean): Promise<void>;
+    cleanup(): void;
+}
+/** Install a lightweight browser-like fixture for router/runtime tests. */
+export declare function createRuntimeFixture(): RuntimeFixture;