@webstir-io/webstir-backend 0.1.15

package/src/diagnostics/summary.ts

@@ -0,0 +1,32 @@
+import type { ModuleDiagnostic } from '@webstir-io/module-contract';
+
+export function pushEntryBucketSummary(diagnostics: ModuleDiagnostic[], entryPoints: readonly string[]): void {
+    try {
+        const server = entryPoints.filter(
+            (p) => p === 'index.js' || /(^|\/)index\.js$/.test(p) && !/^(functions|jobs)\//.test(p)
+        ).length;
+        const functionsCount = entryPoints.filter((p) => p.startsWith('functions/')).length;
+        const jobsCount = entryPoints.filter((p) => p.startsWith('jobs/')).length;
+        diagnostics.push({
+            severity: 'info',
+            message: `[webstir-backend] entries by bucket: server=${server} functions=${functionsCount} jobs=${jobsCount}`
+        });
+    } catch {
+        // best-effort only
+    }
+}
+
+type Severity = 'info' | 'warn' | 'error';
+
+export function normalizeLogLevel(value: unknown): Severity {
+    if (typeof value !== 'string') return 'info';
+    const v = value.toLowerCase();
+    if (v === 'error' || v === 'warn' || v === 'info') return v;
+    return 'info';
+}
+
+export function filterDiagnostics(list: readonly ModuleDiagnostic[], min: Severity): readonly ModuleDiagnostic[] {
+    const rank = (s: Severity) => (s === 'error' ? 3 : s === 'warn' ? 2 : 1);
+    const threshold = rank(min);
+    return list.filter((d) => rank(d.severity as Severity) >= threshold);
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { backendProvider } from './provider.js';
+export { startBackendWatch } from './watch.js';

package/src/manifest/pipeline.ts

@@ -0,0 +1,270 @@
+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';
+import type { ModuleDefinition, ModuleDiagnostic, ModuleManifest } from '@webstir-io/module-contract';
+
+interface WorkspacePackageJson {
+    readonly name?: string;
+    readonly version?: string;
+    readonly webstir?: {
+        readonly moduleManifest?: WorkspaceModuleConfig;
+    };
+}
+
+type WorkspaceModuleConfig = Partial<ModuleManifest> & {
+    readonly contractVersion?: string;
+    readonly capabilities?: ModuleManifest['capabilities'];
+};
+
+export interface LoadManifestOptions {
+    readonly workspaceRoot: string;
+    readonly buildRoot: string;
+    readonly entryPoints: readonly string[];
+    readonly diagnostics: ModuleDiagnostic[];
+}
+
+export async function loadBackendModuleManifest(options: LoadManifestOptions): Promise<ModuleManifest> {
+    const { workspaceRoot, buildRoot, entryPoints, diagnostics } = options;
+    const pkgPath = path.join(workspaceRoot, 'package.json');
+    let workspacePackage: WorkspacePackageJson | undefined;
+
+    try {
+        const raw = await readFile(pkgPath, 'utf8');
+        workspacePackage = JSON.parse(raw) as WorkspacePackageJson;
+    } catch (error) {
+        const err = error as NodeJS.ErrnoException;
+        // 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: ModuleManifest = {
+        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 ?? ({} as ModuleManifest);
+        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: unknown) => {
+            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<string, number>();
+        for (const r of manifest.routes ?? []) {
+            const method = typeof (r as any).method === 'string' ? (r as any).method.toUpperCase() : '';
+            const pathKey = normalizePath((r as any).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: any) => j && typeof j.name === 'string' && (j.schedule === undefined || j.schedule === null));
+        if (noSchedule.length > 0) {
+            const MAX_LIST = 10;
+            const names = noSchedule.map((j: any) => 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: string,
+    diagnostics: ModuleDiagnostic[]
+): Promise<ModuleDefinition | undefined> {
+    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)) as Record<string, unknown>;
+            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 as Error).message}`
+            });
+        }
+    }
+
+    return undefined;
+}
+
+function extractModuleDefinition(exports: Record<string, unknown>): unknown {
+    const keys = ['module', 'moduleDefinition', 'default', 'backendModule'];
+    for (const key of keys) {
+        if (key in exports) {
+            const value = exports[key as keyof typeof exports];
+            if (value !== null && value !== undefined) {
+                return value;
+            }
+        }
+    }
+    return undefined;
+}
+
+function isModuleDefinition(value: unknown): value is ModuleDefinition {
+    return typeof value === 'object' && value !== null && 'manifest' in (value as Record<string, unknown>);
+}
+
+function deriveModuleName(pkg: WorkspacePackageJson | undefined, workspaceRoot: string): string {
+    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: WorkspacePackageJson | undefined): string {
+    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: string
+): Promise<{ routes: number; views: number; capabilities?: readonly string[] } | undefined> {
+    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/src/provider.ts

@@ -0,0 +1,124 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+
+import type {
+    ModuleBuildOptions,
+    ModuleBuildResult,
+    ModuleDiagnostic,
+    ModuleManifest,
+    ModuleProvider
+} from '@webstir-io/module-contract';
+
+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 { pushEntryBucketSummary, 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' };
+
+interface PackageJson {
+    readonly name: string;
+    readonly version: string;
+    readonly engines?: {
+        readonly node?: string;
+    };
+}
+
+const pkg = packageJson as PackageJson;
+
+export const backendProvider: ModuleProvider = {
+    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: ModuleDiagnostic[] = [];
+
+        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/src/scaffold/assets.ts

@@ -0,0 +1,81 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { ModuleAsset } from '@webstir-io/module-contract';
+
+export async function getBackendScaffoldAssets(): Promise<readonly ModuleAsset[]> {
+    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/src/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/src/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/src/testing/context.ts

@@ -0,0 +1,17 @@
+import type { BackendTestContext } from './types.js';
+
+const GLOBAL_KEY = '__webstirBackendTestContext__';
+
+export function setBackendTestContext(context: BackendTestContext | null): void {
+    const target = globalThis as Record<string, unknown>;
+    if (context) {
+        target[GLOBAL_KEY] = context;
+    } else {
+        delete target[GLOBAL_KEY];
+    }
+}
+
+export function getBackendTestContext(): BackendTestContext | null {
+    const target = globalThis as Record<string, unknown>;
+    return (target[GLOBAL_KEY] ?? null) as BackendTestContext | null;
+}

package/src/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;