@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/dist/scaffold/assets.js

@@ -7,71 +7,75 @@ export async function getBackendScaffoldAssets() {
     return [
         {
             sourcePath: path.join(templatesRoot, 'tsconfig.json'),
-            targetPath: path.join('src', 'backend', 'tsconfig.json')
+            targetPath: path.join('src', 'backend', 'tsconfig.json'),
         },
         {
             sourcePath: path.join(templatesRoot, 'index.ts'),
-            targetPath: path.join('src', 'backend', 'index.ts')
-        },
-        {
-            sourcePath: path.join(templatesRoot, 'server', 'fastify.ts'),
-            targetPath: path.join('src', 'backend', 'server', 'fastify.ts')
+            targetPath: path.join('src', 'backend', 'index.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'module.ts'),
-            targetPath: path.join('src', 'backend', 'module.ts')
+            targetPath: path.join('src', 'backend', 'module.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'auth', 'adapter.ts'),
-            targetPath: path.join('src', 'backend', 'auth', 'adapter.ts')
+            targetPath: path.join('src', 'backend', 'auth', 'adapter.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'observability', 'logger.ts'),
-            targetPath: path.join('src', 'backend', 'observability', 'logger.ts')
+            targetPath: path.join('src', 'backend', 'observability', 'logger.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'observability', 'metrics.ts'),
-            targetPath: path.join('src', 'backend', 'observability', 'metrics.ts')
+            targetPath: path.join('src', 'backend', 'observability', 'metrics.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'env.ts'),
-            targetPath: path.join('src', 'backend', 'env.ts')
+            targetPath: path.join('src', 'backend', 'env.ts'),
+        },
+        {
+            sourcePath: path.join(templatesRoot, 'session', 'store.ts'),
+            targetPath: path.join('src', 'backend', 'session', 'store.ts'),
+        },
+        {
+            sourcePath: path.join(templatesRoot, 'session', 'sqlite.ts'),
+            targetPath: path.join('src', 'backend', 'session', 'sqlite.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'functions', 'hello', 'index.ts'),
-            targetPath: path.join('src', 'backend', 'functions', 'hello', 'index.ts')
+            targetPath: path.join('src', 'backend', 'functions', 'hello', 'index.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'jobs', 'nightly', 'index.ts'),
-            targetPath: path.join('src', 'backend', 'jobs', 'nightly', 'index.ts')
+            targetPath: path.join('src', 'backend', 'jobs', 'nightly', 'index.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'jobs', 'runtime.ts'),
-            targetPath: path.join('src', 'backend', 'jobs', 'runtime.ts')
+            targetPath: path.join('src', 'backend', 'jobs', 'runtime.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'jobs', 'scheduler.ts'),
-            targetPath: path.join('src', 'backend', 'jobs', 'scheduler.ts')
+            targetPath: path.join('src', 'backend', 'jobs', 'scheduler.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'db', 'connection.ts'),
-            targetPath: path.join('src', 'backend', 'db', 'connection.ts')
+            targetPath: path.join('src', 'backend', 'db', 'connection.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'db', 'migrate.ts'),
-            targetPath: path.join('src', 'backend', 'db', 'migrate.ts')
+            targetPath: path.join('src', 'backend', 'db', 'migrate.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'db', 'migrations', '0001-example.ts'),
-            targetPath: path.join('src', 'backend', 'db', 'migrations', '0001-example.ts')
+            targetPath: path.join('src', 'backend', 'db', 'migrations', '0001-example.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, 'db', 'types.d.ts'),
-            targetPath: path.join('src', 'backend', 'db', 'types.d.ts')
+            targetPath: path.join('src', 'backend', 'db', 'types.d.ts'),
         },
         {
             sourcePath: path.join(templatesRoot, '.env.example'),
-            targetPath: path.join('.env.example')
-        }
+            targetPath: path.join('.env.example'),
+        },
     ];
 }

package/dist/testing/context.js

@@ -1,4 +1,4 @@
-const GLOBAL_KEY = '__webstirBackendTestContext__';
+const GLOBAL_KEY = Symbol.for('webstir.backendTestContext');
 export function setBackendTestContext(context) {
     const target = globalThis;
     if (context) {

package/dist/testing/index.d.ts

@@ -1,6 +1,6 @@
 import { getBackendTestContext, setBackendTestContext } from './context.js';
 import type { BackendTestCallback, BackendTestHarness, BackendTestHarnessOptions } from './types.js';
-export type { BackendTestCallback, BackendTestContext, BackendTestHarness, BackendTestHarnessOptions } from './types.js';
+export type { BackendTestCallback, BackendTestContext, BackendTestHarness, BackendTestHarnessOptions, } from './types.js';
 export { getBackendTestContext, setBackendTestContext };
 export declare function createBackendTestHarness(options?: BackendTestHarnessOptions): Promise<BackendTestHarness>;
 export declare function backendTest(name: string, callback: BackendTestCallback): void;

package/dist/testing/index.js

@@ -2,67 +2,68 @@ import { spawn } from 'node:child_process';
 import { once } from 'node:events';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import net from 'node:net';
 import path from 'node:path';
 import { getBackendTestContext, setBackendTestContext } from './context.js';
+import { resolveWorkspaceRoot } from '../workspace.js';
 const DEFAULT_PORT = 4100;
 const DEFAULT_READY_TEXT = 'API server running';
 const DEFAULT_READY_TIMEOUT_MS = 15_000;
 export { getBackendTestContext, setBackendTestContext };
 export async function createBackendTestHarness(options = {}) {
-    const workspaceRoot = options.workspaceRoot ?? process.env.WEBSTIR_WORKSPACE_ROOT ?? process.cwd();
-    const buildRoot = options.buildRoot ?? process.env.WEBSTIR_BACKEND_BUILD_ROOT ?? path.join(workspaceRoot, 'build', 'backend');
-    const entry = options.entry ?? process.env.WEBSTIR_BACKEND_TEST_ENTRY ?? path.join(buildRoot, 'index.js');
-    const manifestPath = options.manifestPath ??
-        process.env.WEBSTIR_BACKEND_TEST_MANIFEST ??
-        path.join(workspaceRoot, '.webstir', 'backend-manifest.json');
-    const readyText = options.readyText ?? process.env.WEBSTIR_BACKEND_TEST_READY ?? DEFAULT_READY_TEXT;
-    const readyTimeoutMs = options.readyTimeoutMs ?? readInt(process.env.WEBSTIR_BACKEND_TEST_READY_TIMEOUT, DEFAULT_READY_TIMEOUT_MS);
+    const resolvedEnv = { ...process.env, ...(options.env ?? {}) };
+    const workspaceRoot = resolveWorkspaceRoot({
+        workspaceRoot: options.workspaceRoot,
+        env: resolvedEnv,
+    });
+    const buildRoot = resolveWorkspacePath(workspaceRoot, options.buildRoot ??
+        resolvedEnv.WEBSTIR_BACKEND_BUILD_ROOT ??
+        path.join(workspaceRoot, 'build', 'backend'));
+    const entry = resolveWorkspacePath(workspaceRoot, options.entry ?? resolvedEnv.WEBSTIR_BACKEND_TEST_ENTRY ?? path.join(buildRoot, 'index.js'));
+    const manifestPath = resolveWorkspacePath(workspaceRoot, options.manifestPath ??
+        resolvedEnv.WEBSTIR_BACKEND_TEST_MANIFEST ??
+        path.join(workspaceRoot, '.webstir', 'backend-manifest.json'));
+    const readyText = options.readyText ?? resolvedEnv.WEBSTIR_BACKEND_TEST_READY ?? DEFAULT_READY_TEXT;
+    const readyTimeoutMs = options.readyTimeoutMs ??
+        readInt(resolvedEnv.WEBSTIR_BACKEND_TEST_READY_TIMEOUT, DEFAULT_READY_TIMEOUT_MS);
     if (!existsSync(entry)) {
         throw new Error(`Backend test entry not found at ${entry}. Run the backend build before executing backend tests.`);
     }
-    const requestedPort = options.port ?? readInt(process.env.WEBSTIR_BACKEND_TEST_PORT, DEFAULT_PORT);
-    const port = await findOpenPort(requestedPort);
-    const env = createRuntimeEnv({
-        workspaceRoot,
-        port,
-        overrides: options.env
-    });
     const manifest = await loadManifest(manifestPath);
-    const child = spawn(process.execPath, [entry], {
-        cwd: workspaceRoot,
-        env,
-        stdio: ['ignore', 'pipe', 'pipe']
+    const requestedPort = options.port ?? readInt(resolvedEnv.WEBSTIR_BACKEND_TEST_PORT, DEFAULT_PORT);
+    const { child, env, port } = await startBackendTestProcess({
+        workspaceRoot,
+        entry,
+        requestedPort,
+        baseEnv: resolvedEnv,
+        overrides: options.env,
+        readyText,
+        readyTimeoutMs,
     });
-    try {
-        await waitForReady(child, readyText, readyTimeoutMs);
-    }
-    catch (error) {
-        await stopProcess(child);
-        throw error;
-    }
     const baseUrl = new URL(env.API_BASE_URL ?? `http://127.0.0.1:${port}`);
     const context = {
         baseUrl: baseUrl.toString(),
         url: baseUrl,
         port,
         manifest,
-        routes: Array.isArray(manifest?.routes) ? manifest.routes : [],
+        routes: Array.isArray(manifest?.routes)
+            ? manifest.routes
+            : [],
         env,
         request: async (pathOrUrl = '/', init) => {
             const target = toUrl(baseUrl, pathOrUrl);
             return await fetch(target, init);
-        }
+        },
     };
     return {
         context,
         async stop() {
             await stopProcess(child);
-        }
+        },
     };
 }
 export function backendTest(name, callback) {
-    const globalTest = globalThis.test;
+    const globalTest = globalThis
+        .test;
     if (typeof globalTest !== 'function') {
         throw new Error('backendTest() requires the @webstir-io/webstir-testing runtime.');
     }
@@ -89,28 +90,42 @@ function readInt(value, fallback) {
     const parsed = Number.parseInt(value, 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
-async function findOpenPort(start, attempts = 10) {
-    let candidate = start;
-    for (let index = 0; index < attempts; index += 1) {
-        // eslint-disable-next-line no-await-in-loop
-        if (await isPortAvailable(candidate)) {
-            return candidate;
-        }
-        candidate += 1;
-    }
-    throw new Error(`Unable to find an open port for backend tests (tried starting at ${start}).`);
-}
-function isPortAvailable(port) {
-    return new Promise((resolve) => {
-        const server = net.createServer();
-        server.once('error', () => {
-            server.close(() => resolve(false));
+async function startBackendTestProcess(options) {
+    let candidate = options.requestedPort;
+    let lastError = null;
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        const env = createRuntimeEnv({
+            workspaceRoot: options.workspaceRoot,
+            port: candidate,
+            baseEnv: options.baseEnv,
+            overrides: options.overrides,
         });
-        server.once('listening', () => {
-            server.close(() => resolve(true));
+        const child = spawn(process.execPath, [options.entry], {
+            cwd: options.workspaceRoot,
+            env,
+            stdio: ['ignore', 'pipe', 'pipe'],
         });
-        server.listen(port, '127.0.0.1');
-    });
+        const output = captureChildOutput(child);
+        try {
+            await waitForReady(child, options.readyText, options.readyTimeoutMs);
+            output.stop();
+            return { child, env, port: candidate };
+        }
+        catch (error) {
+            const captured = output.read();
+            output.stop();
+            await stopProcess(child);
+            const message = error instanceof Error ? error.message : String(error);
+            const failure = new Error(`Backend test server did not become ready on port ${candidate}.\nstdout:\n${captured.stdout}\nstderr:\n${captured.stderr}\nerror:\n${message}`);
+            if (attempt < 9 && indicatesPortInUse(captured.stdout, captured.stderr, message)) {
+                lastError = failure;
+                candidate += 1;
+                continue;
+            }
+            throw failure;
+        }
+    }
+    throw lastError ?? new Error('Backend test server did not become ready.');
 }
 function createRuntimeEnv(options) {
     const overrides = {};
@@ -119,16 +134,45 @@ function createRuntimeEnv(options) {
             overrides[key] = value;
         }
     }
-    const baseUrl = overrides.API_BASE_URL ?? process.env.API_BASE_URL ?? `http://127.0.0.1:${options.port}`;
+    const baseUrl = overrides.API_BASE_URL ?? options.baseEnv.API_BASE_URL ?? `http://127.0.0.1:${options.port}`;
     return {
-        ...process.env,
+        ...options.baseEnv,
         ...overrides,
         PORT: String(options.port),
         API_BASE_URL: baseUrl,
-        NODE_ENV: overrides.NODE_ENV ?? process.env.NODE_ENV ?? 'test',
+        NODE_ENV: overrides.NODE_ENV ?? options.baseEnv.NODE_ENV ?? 'test',
         WORKSPACE_ROOT: options.workspaceRoot,
-        WEBSTIR_BACKEND_TEST_RUN: '1'
+        WEBSTIR_BACKEND_TEST_RUN: '1',
+    };
+}
+function captureChildOutput(child) {
+    let stdout = '';
+    let stderr = '';
+    const onStdout = (chunk) => {
+        stdout += chunk.toString();
     };
+    const onStderr = (chunk) => {
+        stderr += chunk.toString();
+    };
+    child.stdout?.on('data', onStdout);
+    child.stderr?.on('data', onStderr);
+    return {
+        stop() {
+            child.stdout?.off('data', onStdout);
+            child.stderr?.off('data', onStderr);
+        },
+        read() {
+            return { stdout, stderr };
+        },
+    };
+}
+function indicatesPortInUse(stdout, stderr, message) {
+    return [stdout, stderr, message].some((value) => value.includes('EADDRINUSE') ||
+        value.includes('address already in use') ||
+        value.includes('Failed to listen at 127.0.0.1'));
+}
+function resolveWorkspacePath(workspaceRoot, value) {
+    return path.isAbsolute(value) ? path.resolve(value) : path.resolve(workspaceRoot, value);
 }
 async function loadManifest(manifestPath) {
     try {
@@ -148,7 +192,7 @@ async function waitForReady(child, readyText, timeoutMs) {
         .split('|')
         .map((token) => token.trim())
         .filter(Boolean);
-    const readinessMatches = (line) => (normalized.length === 0 ? line.length > 0 : normalized.some((token) => line.includes(token)));
+    const readinessMatches = (line) => normalized.length === 0 ? line.length > 0 : normalized.some((token) => line.includes(token));
     await new Promise((resolve, reject) => {
         const cleanup = () => {
             child.stdout?.off('data', onStdout);

package/dist/utils/bun.d.ts

@@ -0,0 +1,2 @@
+export declare function readTextFile(filePath: string): Promise<string>;
+export declare function writeTextFile(filePath: string, contents: string): Promise<void>;

package/dist/utils/bun.js

@@ -0,0 +1,13 @@
+function getBunRuntime() {
+    const runtime = globalThis;
+    if (typeof runtime.Bun?.file === 'function' && typeof runtime.Bun?.write === 'function') {
+        return runtime.Bun;
+    }
+    throw new Error('[webstir-backend] Bun runtime is required for package-level IO.');
+}
+export async function readTextFile(filePath) {
+    return await getBunRuntime().file(filePath).text();
+}
+export async function writeTextFile(filePath, contents) {
+    await getBunRuntime().write(filePath, contents);
+}

package/dist/watch.d.ts

@@ -1,8 +1,20 @@
 export interface WatchHandle {
     stop(): Promise<void>;
 }
+export interface BackendWatchEvent {
+    readonly type: 'build-start' | 'build-complete';
+    readonly succeeded?: boolean;
+    readonly errorCount?: number;
+    readonly warningCount?: number;
+    readonly durationMs?: number;
+    readonly bunBenchmarkSucceeded?: boolean;
+    readonly bunBenchmarkErrorCount?: number;
+    readonly bunBenchmarkWarningCount?: number;
+    readonly bunBenchmarkDurationMs?: number;
+}
 export interface StartWatchOptions {
-    readonly workspaceRoot: string;
+    readonly workspaceRoot?: string;
     readonly env?: Record<string, string | undefined>;
+    readonly onEvent?: (event: BackendWatchEvent) => void | Promise<void>;
 }
 export declare function startBackendWatch(options: StartWatchOptions): Promise<WatchHandle>;