@webstir-io/webstir-backend 0.1.15

package/dist/manifest/pipeline.js

@@ -0,0 +1,224 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { moduleManifestSchema, CONTRACT_VERSION } from '@webstir-io/module-contract';
+export async function loadBackendModuleManifest(options) {
+    const { workspaceRoot, buildRoot, entryPoints, diagnostics } = options;
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    let workspacePackage;
+    try {
+        const raw = await readFile(pkgPath, 'utf8');
+        workspacePackage = JSON.parse(raw);
+    }
+    catch (error) {
+        const err = error;
+        // Missing package.json is expected in some temporary workspaces; avoid noisy warnings.
+        if (err.code !== 'ENOENT') {
+            diagnostics.push({
+                severity: 'warn',
+                message: `[webstir-backend] unable to read ${pkgPath}: ${err.message}. Using defaults.`
+            });
+        }
+    }
+    const moduleConfig = workspacePackage?.webstir?.moduleManifest ?? {};
+    let manifestCandidate = {
+        contractVersion: typeof moduleConfig.contractVersion === 'string' ? moduleConfig.contractVersion : CONTRACT_VERSION,
+        name: typeof moduleConfig.name === 'string' ? moduleConfig.name : deriveModuleName(workspacePackage, workspaceRoot),
+        version: typeof moduleConfig.version === 'string' ? moduleConfig.version : deriveModuleVersion(workspacePackage),
+        kind: 'backend',
+        capabilities: Array.isArray(moduleConfig.capabilities) ? moduleConfig.capabilities : [],
+        routes: moduleConfig.routes ?? [],
+        views: moduleConfig.views ?? [],
+        jobs: moduleConfig.jobs ?? [],
+        events: moduleConfig.events ?? [],
+        services: moduleConfig.services ?? [],
+        init: moduleConfig.init,
+        dispose: moduleConfig.dispose
+    };
+    const definition = await loadModuleDefinition(buildRoot, diagnostics);
+    if (definition) {
+        const definitionManifest = definition.manifest ?? {};
+        const routesFromDefinition = definition.routes?.map((route) => route.definition);
+        const viewsFromDefinition = definition.views?.map((view) => view.definition);
+        const mergedCapabilities = Array.from(new Set([...(manifestCandidate.capabilities ?? []), ...(definitionManifest.capabilities ?? [])]));
+        manifestCandidate = {
+            ...manifestCandidate,
+            ...definitionManifest,
+            capabilities: mergedCapabilities,
+            routes: routesFromDefinition ?? definitionManifest.routes ?? manifestCandidate.routes ?? [],
+            views: viewsFromDefinition ?? definitionManifest.views ?? manifestCandidate.views ?? [],
+            jobs: definitionManifest.jobs ?? manifestCandidate.jobs ?? [],
+            events: definitionManifest.events ?? manifestCandidate.events ?? [],
+            services: definitionManifest.services ?? manifestCandidate.services ?? [],
+            init: definitionManifest.init ?? manifestCandidate.init,
+            dispose: definitionManifest.dispose ?? manifestCandidate.dispose
+        };
+    }
+    const validation = moduleManifestSchema.safeParse(manifestCandidate);
+    if (!validation.success) {
+        const problems = validation.error.issues
+            .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+            .join('; ');
+        diagnostics.push({
+            severity: 'error',
+            message: `[webstir-backend] module manifest validation failed (${problems}). Falling back to defaults.`
+        });
+        return {
+            contractVersion: CONTRACT_VERSION,
+            name: deriveModuleName(workspacePackage, workspaceRoot),
+            version: deriveModuleVersion(workspacePackage),
+            kind: 'backend',
+            capabilities: [],
+            routes: [],
+            views: [],
+            jobs: [],
+            events: [],
+            services: []
+        };
+    }
+    const manifest = validation.data;
+    try {
+        const normalizePath = (p) => {
+            let s = typeof p === 'string' ? p : '';
+            if (!s.startsWith('/'))
+                s = '/' + s;
+            s = s.replace(/\/+/, '/');
+            if (s.length > 1 && s.endsWith('/'))
+                s = s.slice(0, -1);
+            return s;
+        };
+        const seen = new Map();
+        for (const r of manifest.routes ?? []) {
+            const method = typeof r.method === 'string' ? r.method.toUpperCase() : '';
+            const pathKey = normalizePath(r.path);
+            const key = `${method} ${pathKey}`;
+            seen.set(key, (seen.get(key) ?? 0) + 1);
+        }
+        const dups = Array.from(seen.entries()).filter(([, count]) => count > 1);
+        if (dups.length > 0) {
+            const list = dups.map(([k, c]) => `${k} (${c}x)`).join(', ');
+            diagnostics.push({ severity: 'warn', message: `[webstir-backend] duplicate route definitions: ${list}` });
+        }
+    }
+    catch {
+        // best-effort only
+    }
+    if (manifest.routes?.length && entryPoints.length === 0) {
+        diagnostics.push({
+            severity: 'warn',
+            message: '[webstir-backend] module manifest defines routes but no entry points were built. Ensure backend compilation produced handlers.'
+        });
+    }
+    try {
+        const jobs = Array.isArray(manifest.jobs) ? manifest.jobs : [];
+        const events = Array.isArray(manifest.events) ? manifest.events : [];
+        const services = Array.isArray(manifest.services) ? manifest.services : [];
+        if (jobs.length + events.length + services.length > 0) {
+            diagnostics.push({
+                severity: 'info',
+                message: `[webstir-backend] manifest jobs=${jobs.length} events=${events.length} services=${services.length}`
+            });
+        }
+        const noSchedule = jobs.filter((j) => j && typeof j.name === 'string' && (j.schedule === undefined || j.schedule === null));
+        if (noSchedule.length > 0) {
+            const MAX_LIST = 10;
+            const names = noSchedule.map((j) => j.name).slice(0, MAX_LIST).join(', ');
+            const omitted = noSchedule.length > MAX_LIST ? ` (+${noSchedule.length - MAX_LIST} more)` : '';
+            diagnostics.push({
+                severity: 'warn',
+                message: `[webstir-backend] jobs without schedules: ${names}${omitted}`
+            });
+        }
+    }
+    catch {
+        // best-effort only
+    }
+    try {
+        const routes = Array.isArray(manifest.routes) ? manifest.routes.length : 0;
+        const views = Array.isArray(manifest.views) ? manifest.views.length : 0;
+        const caps = Array.isArray(manifest.capabilities) && manifest.capabilities.length > 0 ? ` [${manifest.capabilities.join(', ')}]` : '';
+        diagnostics.push({ severity: 'info', message: `[webstir-backend] manifest routes=${routes} views=${views}${caps}` });
+    }
+    catch {
+        // ignore
+    }
+    return manifest;
+}
+async function loadModuleDefinition(buildRoot, diagnostics) {
+    const candidates = [
+        path.join(buildRoot, 'module.js'),
+        path.join(buildRoot, 'module.mjs'),
+        path.join(buildRoot, 'module/index.js'),
+        path.join(buildRoot, 'module/index.mjs')
+    ];
+    for (const fullPath of candidates) {
+        if (!existsSync(fullPath)) {
+            continue;
+        }
+        try {
+            const moduleUrl = `${pathToFileURL(fullPath).href}?t=${Date.now()}`;
+            const imported = (await import(moduleUrl));
+            const definitionCandidate = extractModuleDefinition(imported);
+            if (isModuleDefinition(definitionCandidate)) {
+                return definitionCandidate;
+            }
+            diagnostics.push({
+                severity: 'warn',
+                message: `[webstir-backend] module definition at ${fullPath} does not export a createModule() definition.`
+            });
+        }
+        catch (error) {
+            diagnostics.push({
+                severity: 'warn',
+                message: `[webstir-backend] failed to load module definition from ${fullPath}: ${error.message}`
+            });
+        }
+    }
+    return undefined;
+}
+function extractModuleDefinition(exports) {
+    const keys = ['module', 'moduleDefinition', 'default', 'backendModule'];
+    for (const key of keys) {
+        if (key in exports) {
+            const value = exports[key];
+            if (value !== null && value !== undefined) {
+                return value;
+            }
+        }
+    }
+    return undefined;
+}
+function isModuleDefinition(value) {
+    return typeof value === 'object' && value !== null && 'manifest' in value;
+}
+function deriveModuleName(pkg, workspaceRoot) {
+    if (typeof pkg?.webstir?.moduleManifest?.name === 'string' && pkg.webstir.moduleManifest.name.length > 0) {
+        return pkg.webstir.moduleManifest.name;
+    }
+    if (typeof pkg?.name === 'string' && pkg.name.length > 0) {
+        return pkg.name;
+    }
+    return `backend-module-${path.basename(workspaceRoot)}`;
+}
+function deriveModuleVersion(pkg) {
+    if (typeof pkg?.webstir?.moduleManifest?.version === 'string' && pkg.webstir.moduleManifest.version.length > 0) {
+        return pkg.webstir.moduleManifest.version;
+    }
+    if (typeof pkg?.version === 'string' && pkg.version.length > 0) {
+        return pkg.version;
+    }
+    return '0.0.0';
+}
+export async function summarizeBuiltManifest(buildRoot) {
+    const definition = await loadModuleDefinition(buildRoot, []);
+    if (!definition || !definition.manifest) {
+        return undefined;
+    }
+    const manifest = definition.manifest;
+    return {
+        routes: Array.isArray(manifest.routes) ? manifest.routes.length : 0,
+        views: Array.isArray(manifest.views) ? manifest.views.length : 0,
+        capabilities: manifest.capabilities
+    };
+}

package/dist/provider.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleProvider } from '@webstir-io/module-contract';
+export declare const backendProvider: ModuleProvider;

package/dist/provider.js

@@ -0,0 +1,101 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { collectArtifacts, createBuildManifest } from './build/artifacts.js';
+import { buildSupportFile, runBackendBuildPipeline } from './build/pipeline.js';
+import { loadBackendModuleManifest } from './manifest/pipeline.js';
+import { createCacheReporter } from './cache/reporters.js';
+import { normalizeLogLevel, filterDiagnostics } from './diagnostics/summary.js';
+import { getBackendScaffoldAssets } from './scaffold/assets.js';
+import { normalizeMode, resolveWorkspacePaths } from './workspace.js';
+import packageJson from '../package.json' with { type: 'json' };
+const pkg = packageJson;
+export const backendProvider = {
+    metadata: {
+        id: pkg.name ?? '@webstir-io/webstir-backend',
+        kind: 'backend',
+        version: pkg.version ?? '0.0.0',
+        compatibility: {
+            minCliVersion: '0.1.0',
+            nodeRange: pkg.engines?.node ?? '>=20.18.1'
+        }
+    },
+    resolveWorkspace(options) {
+        return resolveWorkspacePaths(options.workspaceRoot);
+    },
+    async build(options) {
+        const paths = resolveWorkspacePaths(options.workspaceRoot);
+        const tsconfigPath = path.join(paths.sourceRoot, 'tsconfig.json');
+        const diagnostics = [];
+        const incremental = options.incremental === true;
+        const env = options.env ?? {};
+        const mode = normalizeMode(env.WEBSTIR_MODULE_MODE);
+        console.info(`[webstir-backend] ${mode}:start`);
+        const { entryPoints, outputs, includePublishSourcemaps } = await runBackendBuildPipeline({
+            sourceRoot: paths.sourceRoot,
+            buildRoot: paths.buildRoot,
+            tsconfigPath,
+            mode,
+            env,
+            incremental,
+            diagnostics
+        });
+        const artifacts = await collectArtifacts(paths.buildRoot, includePublishSourcemaps);
+        const envSource = path.join(paths.sourceRoot, 'env.ts');
+        if (existsSync(envSource)) {
+            try {
+                await buildSupportFile({
+                    sourceFile: envSource,
+                    sourceRoot: paths.sourceRoot,
+                    buildRoot: paths.buildRoot,
+                    tsconfigPath,
+                    mode,
+                    env,
+                    diagnostics
+                });
+            }
+            catch {
+                // env compilation errors are already captured in diagnostics
+            }
+        }
+        const moduleManifest = await loadBackendModuleManifest({
+            workspaceRoot: options.workspaceRoot,
+            buildRoot: paths.buildRoot,
+            entryPoints,
+            diagnostics
+        });
+        const manifest = createBuildManifest(paths.buildRoot, artifacts, diagnostics, moduleManifest);
+        console.info(`[webstir-backend] ${mode}:complete (entries=${manifest.entryPoints.length})`);
+        diagnostics.push({ severity: 'info', message: `[webstir-backend] ${mode}:built entries=${manifest.entryPoints.length}` });
+        const cacheReporter = createCacheReporter({
+            workspaceRoot: options.workspaceRoot,
+            buildRoot: paths.buildRoot,
+            env,
+            diagnostics
+        });
+        try {
+            await cacheReporter.diffOutputs(outputs, mode);
+        }
+        catch {
+            // ignore cache errors
+        }
+        try {
+            await cacheReporter.diffManifest(moduleManifest);
+        }
+        catch {
+            // ignore cache errors
+        }
+        // Optionally filter diagnostics by severity for orchestrator consumption
+        const minLevel = normalizeLogLevel(env.WEBSTIR_BACKEND_LOG_LEVEL);
+        const filteredDiagnostics = filterDiagnostics(manifest.diagnostics, minLevel);
+        return {
+            artifacts,
+            manifest: {
+                ...manifest,
+                diagnostics: filteredDiagnostics
+            }
+        };
+    },
+    async getScaffoldAssets() {
+        return await getBackendScaffoldAssets();
+    }
+};

package/dist/scaffold/assets.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleAsset } from '@webstir-io/module-contract';
+export declare function getBackendScaffoldAssets(): Promise<readonly ModuleAsset[]>;

package/dist/scaffold/assets.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+export async function getBackendScaffoldAssets() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const packageRoot = path.resolve(here, '..', '..');
+    const templatesRoot = path.join(packageRoot, 'templates', 'backend');
+    return [
+        {
+            sourcePath: path.join(templatesRoot, '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')
+        },
+        {
+            sourcePath: path.join(templatesRoot, 'module.ts'),
+            targetPath: path.join('src', 'backend', 'module.ts')
+        },
+        {
+            sourcePath: path.join(templatesRoot, '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')
+        },
+        {
+            sourcePath: path.join(templatesRoot, 'observability', 'metrics.ts'),
+            targetPath: path.join('src', 'backend', 'observability', 'metrics.ts')
+        },
+        {
+            sourcePath: path.join(templatesRoot, 'env.ts'),
+            targetPath: path.join('src', 'backend', 'env.ts')
+        },
+        {
+            sourcePath: path.join(templatesRoot, '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')
+        },
+        {
+            sourcePath: path.join(templatesRoot, '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')
+        },
+        {
+            sourcePath: path.join(templatesRoot, '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')
+        },
+        {
+            sourcePath: path.join(templatesRoot, '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')
+        },
+        {
+            sourcePath: path.join(templatesRoot, '.env.example'),
+            targetPath: path.join('.env.example')
+        }
+    ];
+}

package/dist/testing/context.d.ts

@@ -0,0 +1,3 @@
+import type { BackendTestContext } from './types.js';
+export declare function setBackendTestContext(context: BackendTestContext | null): void;
+export declare function getBackendTestContext(): BackendTestContext | null;

package/dist/testing/context.js

@@ -0,0 +1,14 @@
+const GLOBAL_KEY = '__webstirBackendTestContext__';
+export function setBackendTestContext(context) {
+    const target = globalThis;
+    if (context) {
+        target[GLOBAL_KEY] = context;
+    }
+    else {
+        delete target[GLOBAL_KEY];
+    }
+}
+export function getBackendTestContext() {
+    const target = globalThis;
+    return (target[GLOBAL_KEY] ?? null);
+}

package/dist/testing/index.d.ts

@@ -0,0 +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 { getBackendTestContext, setBackendTestContext };
+export declare function createBackendTestHarness(options?: BackendTestHarnessOptions): Promise<BackendTestHarness>;
+export declare function backendTest(name: string, callback: BackendTestCallback): void;

package/dist/testing/index.js

@@ -0,0 +1,208 @@
+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';
+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);
+    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']
+    });
+    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 : [],
+        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;
+    if (typeof globalTest !== 'function') {
+        throw new Error('backendTest() requires the @webstir-io/webstir-testing runtime.');
+    }
+    globalTest(name, async () => {
+        const context = getBackendTestContext();
+        if (!context) {
+            throw new Error('Backend test context not available. Ensure backend tests run via the Webstir CLI (`webstir test`).');
+        }
+        await callback(context);
+    });
+}
+function toUrl(base, pathOrUrl) {
+    if (pathOrUrl instanceof URL) {
+        return pathOrUrl.toString();
+    }
+    if (/^https?:/i.test(pathOrUrl)) {
+        return pathOrUrl;
+    }
+    return new URL(pathOrUrl, base).toString();
+}
+function readInt(value, fallback) {
+    if (!value)
+        return 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));
+        });
+        server.once('listening', () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+function createRuntimeEnv(options) {
+    const overrides = {};
+    for (const [key, value] of Object.entries(options.overrides ?? {})) {
+        if (value !== undefined) {
+            overrides[key] = value;
+        }
+    }
+    const baseUrl = overrides.API_BASE_URL ?? process.env.API_BASE_URL ?? `http://127.0.0.1:${options.port}`;
+    return {
+        ...process.env,
+        ...overrides,
+        PORT: String(options.port),
+        API_BASE_URL: baseUrl,
+        NODE_ENV: overrides.NODE_ENV ?? process.env.NODE_ENV ?? 'test',
+        WORKSPACE_ROOT: options.workspaceRoot,
+        WEBSTIR_BACKEND_TEST_RUN: '1'
+    };
+}
+async function loadManifest(manifestPath) {
+    try {
+        const raw = await readFile(manifestPath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function emitModuleEvent(level, message) {
+    const payload = JSON.stringify({ type: level, message });
+    process.stdout.write(`WEBSTIR_MODULE_EVENT ${payload}\n`);
+}
+async function waitForReady(child, readyText, timeoutMs) {
+    const normalized = readyText
+        .split('|')
+        .map((token) => token.trim())
+        .filter(Boolean);
+    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);
+            child.stderr?.off('data', onStderr);
+            child.off('exit', onExit);
+            clearTimeout(timer);
+        };
+        const onStdout = (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split(/\r?\n/)) {
+                if (!line)
+                    continue;
+                emitModuleEvent('info', line);
+                if (readinessMatches(line)) {
+                    cleanup();
+                    resolve();
+                }
+            }
+        };
+        const onStderr = (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split(/\r?\n/)) {
+                if (!line)
+                    continue;
+                emitModuleEvent('error', line);
+                if (readinessMatches(line)) {
+                    cleanup();
+                    resolve();
+                }
+            }
+        };
+        const onExit = (code) => {
+            cleanup();
+            reject(new Error(`Backend test server exited before it became ready (code ${code ?? 'null'}).`));
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            emitModuleEvent('error', 'Backend test server readiness timed out.');
+            reject(new Error(`Backend test server did not become ready within ${timeoutMs}ms. Check server logs for details.`));
+        }, timeoutMs);
+        child.stdout?.on('data', onStdout);
+        child.stderr?.on('data', onStderr);
+        child.once('exit', onExit);
+    });
+}
+async function stopProcess(child) {
+    if (!child || child.killed || child.exitCode !== null) {
+        return;
+    }
+    child.kill('SIGTERM');
+    try {
+        await once(child, 'exit');
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/testing/types.d.ts

@@ -0,0 +1,28 @@
+import type { ModuleManifest } from '@webstir-io/module-contract';
+type ModuleRoute = NonNullable<ModuleManifest['routes']>[number];
+export interface BackendTestContext {
+    readonly baseUrl: string;
+    readonly url: URL;
+    readonly port: number;
+    readonly manifest: ModuleManifest | null;
+    readonly routes: readonly ModuleRoute[];
+    readonly env: Readonly<Record<string, string>>;
+    request(pathOrUrl?: string | URL, init?: RequestInit): Promise<Response>;
+}
+export interface BackendTestHarness {
+    readonly context: BackendTestContext;
+    stop(): Promise<void>;
+}
+export interface BackendTestHarnessOptions {
+    workspaceRoot?: string;
+    buildRoot?: string;
+    entry?: string;
+    manifestPath?: string;
+    env?: Record<string, string | undefined>;
+    port?: number;
+    readyText?: string;
+    readyTimeoutMs?: number;
+    reuseExistingServer?: boolean;
+}
+export type BackendTestCallback = (context: BackendTestContext) => Promise<void> | void;
+export {};

package/dist/testing/types.js

@@ -0,0 +1 @@
+export {};