@webstir-io/webstir-backend 0.1.15 → 0.1.16

package/src/cache/diff.ts

@@ -1,128 +1,134 @@
 import path from 'node:path';
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { mkdir } from 'node:fs/promises';
 
 import type { ModuleManifest, ModuleDiagnostic } from '@webstir-io/module-contract';
 
 import type { BackendBuildMode } from '../workspace.js';
+import { readTextFile, writeTextFile } from '../utils/bun.js';
+
+type DigestRouteLike = { readonly method?: string; readonly path?: string };
+type DigestViewLike = { readonly path?: string };
 
 export async function persistAndDiffOutputs(
-    workspaceRoot: string,
-    _buildRoot: string,
-    outputs: Record<string, number> | undefined,
-    env: Record<string, string | undefined>,
-    diagnostics: ModuleDiagnostic[],
-    mode: BackendBuildMode
+  workspaceRoot: string,
+  _buildRoot: string,
+  outputs: Record<string, number> | undefined,
+  env: Record<string, string | undefined>,
+  diagnostics: ModuleDiagnostic[],
+  mode: BackendBuildMode,
 ): Promise<void> {
-    if (!outputs) return;
+  if (!outputs) return;
+  try {
+    const diagMax = resolveDiagMax(env);
+    const webstirDir = path.join(workspaceRoot, '.webstir');
+    const cachePath = path.join(webstirDir, 'backend-outputs.json');
+    await mkdir(webstirDir, { recursive: true });
+
+    let previous: Record<string, number> = {};
     try {
-        const diagMax = resolveDiagMax(env);
-        const webstirDir = path.join(workspaceRoot, '.webstir');
-        const cachePath = path.join(webstirDir, 'backend-outputs.json');
-        await mkdir(webstirDir, { recursive: true });
-
-        let previous: Record<string, number> = {};
-        try {
-            const raw = await readFile(cachePath, 'utf8');
-            previous = JSON.parse(raw) as Record<string, number>;
-        } catch {
-            // first run or unreadable cache
-        }
-
-        const changed: string[] = [];
-        for (const [rel, bytes] of Object.entries(outputs)) {
-            if (previous[rel] !== bytes) {
-                changed.push(rel);
-            }
-        }
-        const removed = Object.keys(previous).filter((rel) => outputs[rel] === undefined);
-
-        if (changed.length + removed.length > 0) {
-            const list = changed.slice(0, diagMax).join(', ');
-            const omitted = changed.length > diagMax ? ` (+${changed.length - diagMax} more)` : '';
-            const removedInfo = removed.length > 0 ? `, removed=${removed.length}` : '';
-            diagnostics.push({
-                severity: 'info',
-                message: `[webstir-backend] ${mode}:changed ${changed.length} file(s): ${list}${omitted}${removedInfo}`
-            });
-        }
-
-        await writeFile(cachePath, JSON.stringify(outputs, null, 2), 'utf8');
+      const raw = await readTextFile(cachePath);
+      previous = JSON.parse(raw) as Record<string, number>;
     } catch {
-        // ignore cache errors
+      // first run or unreadable cache
+    }
+
+    const changed: string[] = [];
+    for (const [rel, bytes] of Object.entries(outputs)) {
+      if (previous[rel] !== bytes) {
+        changed.push(rel);
+      }
     }
+    const removed = Object.keys(previous).filter((rel) => outputs[rel] === undefined);
+
+    if (changed.length + removed.length > 0) {
+      const list = changed.slice(0, diagMax).join(', ');
+      const omitted = changed.length > diagMax ? ` (+${changed.length - diagMax} more)` : '';
+      const removedInfo = removed.length > 0 ? `, removed=${removed.length}` : '';
+      diagnostics.push({
+        severity: 'info',
+        message: `[webstir-backend] ${mode}:changed ${changed.length} file(s): ${list}${omitted}${removedInfo}`,
+      });
+    }
+
+    await writeTextFile(cachePath, JSON.stringify(outputs, null, 2));
+  } catch {
+    // ignore cache errors
+  }
 }
 
 export async function persistAndDiffManifest(
-    workspaceRoot: string,
-    manifest: ModuleManifest,
-    env: Record<string, string | undefined>,
-    diagnostics: ModuleDiagnostic[]
+  workspaceRoot: string,
+  manifest: ModuleManifest,
+  env: Record<string, string | undefined>,
+  diagnostics: ModuleDiagnostic[],
 ): Promise<void> {
+  try {
+    const diagMax = resolveDiagMax(env);
+    const webstirDir = path.join(workspaceRoot, '.webstir');
+    const cachePath = path.join(webstirDir, 'backend-manifest-digest.json');
+    await mkdir(webstirDir, { recursive: true });
+
+    const routeKeys = Array.isArray(manifest.routes)
+      ? (manifest.routes as readonly DigestRouteLike[]).map(
+          (route) => `${(route.method ?? '').toUpperCase()} ${route.path ?? ''}`,
+        )
+      : [];
+    const viewPaths = Array.isArray(manifest.views)
+      ? (manifest.views as readonly DigestViewLike[]).map((view) => `${view.path ?? ''}`)
+      : [];
+    const caps = Array.isArray(manifest.capabilities) ? manifest.capabilities : [];
+
+    type Digest = { routes: string[]; views: string[]; capabilities: string[] };
+    let previous: Digest | undefined;
     try {
-        const diagMax = resolveDiagMax(env);
-        const webstirDir = path.join(workspaceRoot, '.webstir');
-        const cachePath = path.join(webstirDir, 'backend-manifest-digest.json');
-        await mkdir(webstirDir, { recursive: true });
-
-        const routeKeys = Array.isArray(manifest.routes)
-            ? (manifest.routes as any[]).map((r) => `${(r.method ?? '').toUpperCase()} ${r.path ?? ''}`)
-            : [];
-        const viewPaths = Array.isArray(manifest.views)
-            ? (manifest.views as any[]).map((v) => `${v.path ?? ''}`)
-            : [];
-        const caps = Array.isArray(manifest.capabilities) ? manifest.capabilities : [];
-
-        type Digest = { routes: string[]; views: string[]; capabilities: string[] };
-        let previous: Digest | undefined;
-        try {
-            const raw = await readFile(cachePath, 'utf8');
-            previous = JSON.parse(raw) as Digest;
-        } catch {
-            // first run; no diff
-        }
+      const raw = await readTextFile(cachePath);
+      previous = JSON.parse(raw) as Digest;
+    } catch {
+      // first run; no diff
+    }
 
-        if (previous) {
-            const prevRoutes = new Set(previous.routes);
-            const prevViews = new Set(previous.views);
-            const nextRoutes = new Set(routeKeys);
-            const nextViews = new Set(viewPaths);
-
-            const addedRoutes: string[] = [];
-            const removedRoutes: string[] = [];
-            const addedViews: string[] = [];
-            const removedViews: string[] = [];
-
-            for (const r of nextRoutes) if (!prevRoutes.has(r)) addedRoutes.push(r);
-            for (const r of prevRoutes) if (!nextRoutes.has(r)) removedRoutes.push(r);
-            for (const v of nextViews) if (!prevViews.has(v)) addedViews.push(v);
-            for (const v of prevViews) if (!nextViews.has(v)) removedViews.push(v);
-
-            if (addedRoutes.length + removedRoutes.length + addedViews.length + removedViews.length > 0) {
-                const list = (items: string[]) => items.slice(0, diagMax).join(', ');
-                const routeDelta = `routes +${addedRoutes.length}/-${removedRoutes.length}`;
-                const viewDelta = `views +${addedViews.length}/-${removedViews.length}`;
-                let msg = `[webstir-backend] manifest changed: ${routeDelta}; ${viewDelta}`;
-                const details: string[] = [];
-                if (addedRoutes.length > 0) details.push(`added routes: ${list(addedRoutes)}`);
-                if (removedRoutes.length > 0) details.push(`removed routes: ${list(removedRoutes)}`);
-                if (addedViews.length > 0) details.push(`added views: ${list(addedViews)}`);
-                if (removedViews.length > 0) details.push(`removed views: ${list(removedViews)}`);
-                if (details.length > 0) {
-                    msg += ` — ${details.join(' | ')}`;
-                }
-                diagnostics.push({ severity: 'info', message: msg });
-            }
+    if (previous) {
+      const prevRoutes = new Set(previous.routes);
+      const prevViews = new Set(previous.views);
+      const nextRoutes = new Set(routeKeys);
+      const nextViews = new Set(viewPaths);
+
+      const addedRoutes: string[] = [];
+      const removedRoutes: string[] = [];
+      const addedViews: string[] = [];
+      const removedViews: string[] = [];
+
+      for (const r of nextRoutes) if (!prevRoutes.has(r)) addedRoutes.push(r);
+      for (const r of prevRoutes) if (!nextRoutes.has(r)) removedRoutes.push(r);
+      for (const v of nextViews) if (!prevViews.has(v)) addedViews.push(v);
+      for (const v of prevViews) if (!nextViews.has(v)) removedViews.push(v);
+
+      if (addedRoutes.length + removedRoutes.length + addedViews.length + removedViews.length > 0) {
+        const list = (items: string[]) => items.slice(0, diagMax).join(', ');
+        const routeDelta = `routes +${addedRoutes.length}/-${removedRoutes.length}`;
+        const viewDelta = `views +${addedViews.length}/-${removedViews.length}`;
+        let msg = `[webstir-backend] manifest changed: ${routeDelta}; ${viewDelta}`;
+        const details: string[] = [];
+        if (addedRoutes.length > 0) details.push(`added routes: ${list(addedRoutes)}`);
+        if (removedRoutes.length > 0) details.push(`removed routes: ${list(removedRoutes)}`);
+        if (addedViews.length > 0) details.push(`added views: ${list(addedViews)}`);
+        if (removedViews.length > 0) details.push(`removed views: ${list(removedViews)}`);
+        if (details.length > 0) {
+          msg += ` — ${details.join(' | ')}`;
         }
-
-        const digest: Digest = { routes: routeKeys, views: viewPaths, capabilities: caps };
-        await writeFile(cachePath, JSON.stringify(digest, null, 2), 'utf8');
-    } catch {
-        // ignore cache errors
+        diagnostics.push({ severity: 'info', message: msg });
+      }
     }
+
+    const digest: Digest = { routes: routeKeys, views: viewPaths, capabilities: caps };
+    await writeTextFile(cachePath, JSON.stringify(digest, null, 2));
+  } catch {
+    // ignore cache errors
+  }
 }
 
 function resolveDiagMax(env: Record<string, string | undefined>, fallback = 50): number {
-    const raw = env?.WEBSTIR_BACKEND_DIAG_MAX;
-    const n = typeof raw === 'string' ? parseInt(raw, 10) : NaN;
-    return Number.isFinite(n) && n > 0 ? n : fallback;
+  const raw = env?.WEBSTIR_BACKEND_DIAG_MAX;
+  const n = typeof raw === 'string' ? parseInt(raw, 10) : NaN;
+  return Number.isFinite(n) && n > 0 ? n : fallback;
 }

package/src/cache/reporters.ts

@@ -4,38 +4,38 @@ import type { BackendBuildMode } from '../workspace.js';
 import { persistAndDiffManifest, persistAndDiffOutputs } from './diff.js';
 
 export interface CacheReporter {
-    readonly diffOutputs: (
-        outputs: Record<string, number> | undefined,
-        mode: BackendBuildMode
-    ) => Promise<void>;
-    readonly diffManifest: (manifest: ModuleManifest) => Promise<void>;
+  readonly diffOutputs: (
+    outputs: Record<string, number> | undefined,
+    mode: BackendBuildMode,
+  ) => Promise<void>;
+  readonly diffManifest: (manifest: ModuleManifest) => Promise<void>;
 }
 
 export function createCacheReporter(options: {
-    readonly workspaceRoot: string;
-    readonly buildRoot: string;
-    readonly env: Record<string, string | undefined>;
-    readonly diagnostics: ModuleDiagnostic[];
+  readonly workspaceRoot: string;
+  readonly buildRoot: string;
+  readonly env: Record<string, string | undefined>;
+  readonly diagnostics: ModuleDiagnostic[];
 }): CacheReporter {
-    const { workspaceRoot, buildRoot, env, diagnostics } = options;
-    const diagnosticsTarget = shouldLogCacheDiffs(env) ? diagnostics : [];
+  const { workspaceRoot, buildRoot, env, diagnostics } = options;
+  const diagnosticsTarget = shouldLogCacheDiffs(env) ? diagnostics : [];
 
-    return {
-        async diffOutputs(outputs, mode) {
-            await persistAndDiffOutputs(workspaceRoot, buildRoot, outputs, env, diagnosticsTarget, mode);
-        },
-        async diffManifest(manifest) {
-            await persistAndDiffManifest(workspaceRoot, manifest, env, diagnosticsTarget);
-        }
-    };
+  return {
+    async diffOutputs(outputs, mode) {
+      await persistAndDiffOutputs(workspaceRoot, buildRoot, outputs, env, diagnosticsTarget, mode);
+    },
+    async diffManifest(manifest) {
+      await persistAndDiffManifest(workspaceRoot, manifest, env, diagnosticsTarget);
+    },
+  };
 }
 
 function shouldLogCacheDiffs(env: Record<string, string | undefined>): boolean {
-    const raw = env?.WEBSTIR_BACKEND_CACHE_LOG;
-    if (!raw) return true;
-    const normalized = raw.trim().toLowerCase();
-    if (['off', '0', 'false', 'quiet', 'silent', 'skip'].includes(normalized)) {
-        return false;
-    }
-    return true;
+  const raw = env?.WEBSTIR_BACKEND_CACHE_LOG;
+  if (!raw) return true;
+  const normalized = raw.trim().toLowerCase();
+  if (['off', '0', 'false', 'quiet', 'silent', 'skip'].includes(normalized)) {
+    return false;
+  }
+  return true;
 }

package/src/deploy-cli.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env bun
+
+import path from 'node:path';
+
+import { startPublishedWorkspaceServer } from './runtime/deploy.js';
+
+async function main(argv: readonly string[]): Promise<void> {
+  const args = parseArgs(argv);
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const workspaceRoot = path.resolve(args.workspace ?? process.cwd());
+  const server = await startPublishedWorkspaceServer({
+    workspaceRoot,
+    host: args.host,
+    port: args.port,
+  });
+
+  const shutdown = async (signal: NodeJS.Signals): Promise<void> => {
+    process.stderr.write(`[webstir-backend-deploy] received ${signal}, stopping.\n`);
+    await server.stop();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => void shutdown('SIGINT'));
+  process.on('SIGTERM', () => void shutdown('SIGTERM'));
+
+  process.stdout.write(
+    `[webstir-backend-deploy] serving ${server.mode} workspace at ${server.origin}\n`,
+  );
+
+  await new Promise<void>(() => {
+    // Keep the process alive until it receives a signal.
+  });
+}
+
+function parseArgs(argv: readonly string[]): {
+  readonly workspace?: string;
+  readonly host?: string;
+  readonly port?: number;
+  readonly help: boolean;
+} {
+  let workspace: string | undefined;
+  let host: string | undefined;
+  let port: number | undefined;
+  let help = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) {
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      help = true;
+      continue;
+    }
+
+    if (arg === '--workspace') {
+      const next = argv[index + 1];
+      if (!next) {
+        throw new Error('Missing value for --workspace.');
+      }
+      workspace = next;
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--host') {
+      const next = argv[index + 1];
+      if (!next) {
+        throw new Error('Missing value for --host.');
+      }
+      host = next;
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--port') {
+      const next = argv[index + 1];
+      if (!next) {
+        throw new Error('Missing value for --port.');
+      }
+      const parsed = Number(next);
+      if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`Invalid value for --port: ${next}`);
+      }
+      port = parsed;
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return { workspace, host, port, help };
+}
+
+function printHelp(): void {
+  process.stdout.write(`Usage: webstir-backend-deploy [--workspace <path>] [--host <host>] [--port <port>]
+
+Starts a published api or full Webstir workspace with a single Bun entrypoint.
+`);
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+});

package/src/diagnostics/summary.ts

@@ -1,32 +1,38 @@
 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
-    }
+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';
+  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);
+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

@@ -1,2 +1,13 @@
+export { runAddJob, runAddRoute, runUpdateRouteContract } from './add.js';
+export type { AddJobOptions, AddRouteOptions, UpdateRouteContractOptions } from './add.js';
 export { backendProvider } from './provider.js';
 export { startBackendWatch } from './watch.js';
+export { getBackendScaffoldAssets } from './scaffold/assets.js';
+export { createDefaultBunBackendBootstrap, startBunBackend } from './runtime/bun.js';
+export type {
+  BunRuntimeEnvLike,
+  DefaultBunBackendBootstrapOptions,
+  MetricsTracker,
+  RuntimeLogger,
+} from './runtime/bun.js';
+export { startPublishedWorkspaceServer } from './runtime/deploy.js';