@webstir-io/webstir-backend 0.1.15

package/templates/backend/jobs/scheduler.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+import { setInterval } from 'node:timers';
+
+import { loadJobs } from './runtime.js';
+
+const args = process.argv.slice(2);
+
+async function main() {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  const jobs = await loadJobs();
+  if (jobs.length === 0) {
+    console.info('[jobs] no jobs registered in webstir.moduleManifest.jobs');
+    return;
+  }
+
+  if (args.includes('--list')) {
+    listJobs(jobs);
+    return;
+  }
+
+  const jobName = parseOption('--job');
+  const watch = args.includes('--watch');
+  const runAll = args.includes('--all') || (!jobName && !watch);
+
+  if (watch) {
+    await startWatch(jobs, jobName);
+    return;
+  }
+
+  if (jobName) {
+    await runNamedJob(jobs, jobName);
+    return;
+  }
+
+  if (runAll) {
+    for (const job of jobs) {
+      await runJob(job);
+    }
+    return;
+  }
+}
+
+async function startWatch(jobs: Awaited<ReturnType<typeof loadJobs>>, jobName?: string) {
+  const filtered = jobName ? jobs.filter((job) => job.name === jobName) : jobs;
+  if (filtered.length === 0) {
+    console.error(jobName ? `[jobs] job '${jobName}' not found` : '[jobs] no jobs available to watch');
+    process.exitCode = 1;
+    return;
+  }
+
+  const timers = filtered.map((job) => scheduleJob(job));
+  if (timers.every((timer) => timer === undefined)) {
+    console.warn('[jobs] no jobs have schedules compatible with the built-in watcher. Use an external scheduler.');
+    return;
+  }
+
+  console.info('[jobs] watching jobs:', filtered.map((job) => job.name).join(', '));
+  process.stdin.resume();
+}
+
+function scheduleJob(job: Awaited<ReturnType<typeof loadJobs>>[number]) {
+  const intervalMs = toInterval(job.schedule);
+  if (intervalMs === null) {
+    console.info(
+      `[jobs] schedule '${job.schedule ?? 'unspecified'}' is not supported by the built-in watcher. Run manually or use an external scheduler.`
+    );
+    return undefined;
+  }
+
+  if (intervalMs === 0) {
+    void runJob(job);
+    return undefined;
+  }
+
+  void runJob(job);
+  return setInterval(() => {
+    void runJob(job);
+  }, intervalMs);
+}
+
+async function runNamedJob(jobs: Awaited<ReturnType<typeof loadJobs>>, jobName: string) {
+  const job = jobs.find((item) => item.name === jobName);
+  if (!job) {
+    console.error(`[jobs] job '${jobName}' not found`);
+    process.exitCode = 1;
+    return;
+  }
+  await runJob(job);
+}
+
+async function runJob(job: Awaited<ReturnType<typeof loadJobs>>[number]) {
+  const startedAt = new Date();
+  console.info(`[jobs] running ${job.name} (schedule: ${job.schedule ?? 'manual'})`);
+  try {
+    await job.run();
+    console.info(`[jobs] ${job.name} completed in ${(Date.now() - startedAt.getTime()).toFixed(0)}ms`);
+  } catch (error) {
+    console.error(`[jobs] ${job.name} failed: ${(error as Error).message}`);
+    process.exitCode = 1;
+  }
+}
+
+function listJobs(jobs: Awaited<ReturnType<typeof loadJobs>>) {
+  for (const job of jobs) {
+    console.info(`- ${job.name}${job.schedule ? ` (${job.schedule})` : ''}${job.description ? ` — ${job.description}` : ''}`);
+  }
+}
+
+function parseOption(flag: string): string | undefined {
+  const index = args.findIndex((arg) => arg === flag);
+  if (index !== -1 && args[index + 1] && !args[index + 1].startsWith('-')) {
+    return args[index + 1];
+  }
+  const prefix = `${flag}=`;
+  const inline = args.find((arg) => arg.startsWith(prefix));
+  if (inline) {
+    return inline.slice(prefix.length);
+  }
+  return undefined;
+}
+
+function toInterval(schedule: string | undefined): number | null {
+  if (!schedule) {
+    return null;
+  }
+  const trimmed = schedule.trim().toLowerCase();
+  if (!trimmed) return null;
+
+  if (trimmed.startsWith('@')) {
+    switch (trimmed.slice(1)) {
+      case 'hourly':
+        return 60 * 60 * 1000;
+      case 'daily':
+      case 'midnight':
+        return 24 * 60 * 60 * 1000;
+      case 'weekly':
+        return 7 * 24 * 60 * 60 * 1000;
+      case 'reboot':
+        return 0;
+      default:
+        return null;
+    }
+  }
+
+  const rateMatch = /^rate\((\d+)\s+(second|seconds|minute|minutes|hour|hours)\)$/.exec(trimmed);
+  if (rateMatch) {
+    const value = Number(rateMatch[1]);
+    const unit = rateMatch[2];
+    const multiplier =
+      unit.startsWith('second') ? 1000 : unit.startsWith('minute') ? 60 * 1000 : unit.startsWith('hour') ? 60 * 60 * 1000 : 0;
+    return value > 0 && multiplier > 0 ? value * multiplier : null;
+  }
+
+  return null;
+}
+
+function printHelp() {
+  console.info(`Usage:
+  node build/backend/jobs/scheduler.js [--list]
+  node build/backend/jobs/scheduler.js --job <name>
+  node build/backend/jobs/scheduler.js --watch [--job <name>]
+
+Options:
+  --list            Show registered jobs and exit
+  --job <name>      Run a specific job immediately (or watch a single job)
+  --all             Run all jobs once (default when no options are provided)
+  --watch           Run supported jobs on an interval (supports @hourly/@daily/@weekly/@reboot and rate(...) syntax)
+  --help            Display this message
+`);
+}
+
+const isMain = (() => {
+  try {
+    const argv1 = process.argv?.[1];
+    if (!argv1) return false;
+    const here = new URL(import.meta.url);
+    const run = new URL(`file://${argv1}`);
+    return here.pathname === run.pathname;
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  main().catch((error) => {
+    console.error('[jobs] scheduler failed:', error);
+    process.exitCode = 1;
+  });
+}

package/templates/backend/module.ts

@@ -0,0 +1,87 @@
+// Example manifest + route definition. Update the values to match your backend.
+// When this file is present, the server scaffold loads build/backend/module.js,
+// announces the manifest, and mounts every route definition automatically.
+
+interface RouteHandlerResult {
+  status?: number;
+  headers?: Record<string, string>;
+  body?: unknown;
+  errors?: { code: string; message: string; details?: unknown }[];
+}
+
+type RouteHandler = (ctx: RouteContext) => Promise<RouteHandlerResult> | RouteHandlerResult;
+
+interface RouteContext {
+  params: Record<string, string>;
+  query: Record<string, string>;
+  body: unknown;
+  auth?: {
+    userId?: string;
+    email?: string;
+    scopes: readonly string[];
+    roles: readonly string[];
+  };
+  requestId: string;
+  env: {
+    get: (name: string) => string | undefined;
+    require: (name: string) => string;
+    entries: () => Record<string, string | undefined>;
+  };
+  logger: {
+    info: (message: string, metadata?: Record<string, unknown>) => void;
+    warn: (message: string, metadata?: Record<string, unknown>) => void;
+    error: (message: string, metadata?: Record<string, unknown>) => void;
+  };
+  now: () => Date;
+}
+
+const routes = [
+  {
+    definition: {
+      name: 'helloRoute',
+      method: 'GET',
+      path: '/hello/:name',
+      summary: 'Simple hello route',
+      description: 'Demonstrates manifest wiring + request context metadata.'
+    },
+    handler: async (ctx: RouteContext) => {
+      if (!ctx.auth) {
+        return {
+          status: 401,
+          errors: [{ code: 'auth', message: 'Sign-in required to access /hello' }]
+        };
+      }
+      const name = ctx.params.name ?? 'world';
+      ctx.logger.info('hello route invoked', { name, requestId: ctx.requestId, userId: ctx.auth.userId });
+      return {
+        status: 200,
+        body: {
+          message: `Hello ${name}`,
+          greetedAt: ctx.now().toISOString(),
+          user: ctx.auth.userId ?? 'anonymous'
+        }
+      };
+    }
+  }
+];
+
+const jobs = [
+  {
+    name: 'nightly',
+    schedule: '0 0 * * *',
+    description: 'Example nightly maintenance job metadata surfaced in the manifest.'
+  }
+];
+
+export const module = {
+  manifest: {
+    contractVersion: '1.0.0',
+    name: '@demo/backend',
+    version: '0.1.0',
+    kind: 'backend',
+    capabilities: ['http', 'auth', 'db'],
+    routes: routes.map((route) => route.definition),
+    jobs
+  },
+  routes
+};

package/templates/backend/observability/logger.ts

@@ -0,0 +1,24 @@
+import type http from 'node:http';
+import pino, { stdTimeFunctions, type Logger } from 'pino';
+
+import type { AppEnv } from '../env.js';
+
+export function createBaseLogger(env: AppEnv): Logger {
+  return pino({
+    level: env.logging.level,
+    base: {
+      service: env.logging.serviceName,
+      environment: env.NODE_ENV
+    },
+    timestamp: stdTimeFunctions.isoTime
+  });
+}
+
+export function createRequestLogger(baseLogger: Logger, options: { requestId: string; req: http.IncomingMessage; route?: string }): Logger {
+  return baseLogger.child({
+    requestId: options.requestId,
+    method: options.req.method ?? 'GET',
+    path: options.req.url ?? '/',
+    route: options.route
+  });
+}

package/templates/backend/observability/metrics.ts

@@ -0,0 +1,78 @@
+import type { MetricsConfig } from '../env.js';
+
+export interface RequestMetricsEvent {
+  method: string;
+  route: string;
+  status: number;
+  durationMs: number;
+}
+
+export interface MetricsSnapshot {
+  enabled: true;
+  totalRequests: number;
+  errorCount: number;
+  averageDurationMs: number;
+  p95DurationMs: number;
+  byStatus: Record<string, number>;
+  windowSize: number;
+}
+
+export interface MetricsTracker {
+  record(event: RequestMetricsEvent): void;
+  snapshot(): MetricsSnapshot | undefined;
+}
+
+export function createMetricsTracker(config: MetricsConfig): MetricsTracker {
+  if (!config.enabled) {
+    return {
+      record() {
+        // no-op
+      },
+      snapshot() {
+        return undefined;
+      }
+    };
+  }
+
+  let totalRequests = 0;
+  let errorCount = 0;
+  const byStatus = new Map<number, number>();
+  const durations: number[] = [];
+
+  return {
+    record(event) {
+      totalRequests++;
+      if (event.status >= 500) {
+        errorCount++;
+      }
+      byStatus.set(event.status, (byStatus.get(event.status) ?? 0) + 1);
+      durations.push(event.durationMs);
+      if (durations.length > config.windowSize) {
+        durations.shift();
+      }
+    },
+    snapshot() {
+      const counts = Object.fromEntries(
+        [...byStatus.entries()].map(([status, count]) => [String(status), count])
+      );
+      const averageDurationMs = durations.length > 0 ? durations.reduce((sum, value) => sum + value, 0) / durations.length : 0;
+      const p95DurationMs = durations.length > 0 ? percentile(durations, 0.95) : 0;
+      return {
+        enabled: true,
+        totalRequests,
+        errorCount,
+        averageDurationMs,
+        p95DurationMs,
+        byStatus: counts,
+        windowSize: config.windowSize
+      };
+    }
+  };
+}
+
+function percentile(values: readonly number[], ratio: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.min(sorted.length - 1, Math.floor(ratio * (sorted.length - 1)));
+  return sorted[index];
+}

package/templates/backend/server/fastify.ts

@@ -0,0 +1,288 @@
+// Optional Fastify server scaffold for richer routing
+// Rename or import into your backend index to use.
+import Fastify from 'fastify';
+import { randomUUID } from 'node:crypto';
+
+import { loadEnv } from '../env.js';
+
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+
+interface Logger {
+  readonly level: LogLevel;
+  log(level: LogLevel, message: string, metadata?: Record<string, unknown>): void;
+  debug(message: string, metadata?: Record<string, unknown>): void;
+  info(message: string, metadata?: Record<string, unknown>): void;
+  warn(message: string, metadata?: Record<string, unknown>): void;
+  error(message: string, metadata?: Record<string, unknown>): void;
+  with(bindings: Record<string, unknown>): Logger;
+}
+
+interface EnvAccessor {
+  get(name: string): string | undefined;
+  require(name: string): string;
+  entries(): Record<string, string | undefined>;
+}
+
+interface ModuleRouteDefinition {
+  name?: string;
+  method?: string;
+  path?: string;
+}
+
+interface ModuleRoute {
+  definition?: ModuleRouteDefinition;
+  handler?: (ctx: Record<string, unknown>) => Promise<any> | any;
+}
+
+interface ModuleManifestLike {
+  name?: string;
+  version?: string;
+  capabilities?: string[];
+  routes?: ModuleRouteDefinition[];
+}
+
+interface ModuleDefinitionLike {
+  manifest?: ModuleManifestLike;
+  routes?: ModuleRoute[];
+}
+
+interface ManifestSummary {
+  name?: string;
+  version?: string;
+  routes: number;
+  capabilities?: string[];
+}
+
+type ReadinessStatus = 'booting' | 'ready' | 'error';
+type ReadinessTracker = ReturnType<typeof createReadinessTracker>;
+
+export async function start(): Promise<void> {
+  const env = loadEnv();
+  const port = env.PORT;
+  const mode = env.NODE_ENV;
+  const readiness = createReadinessTracker();
+  readiness.booting();
+
+  const app = Fastify({ logger: false });
+
+  app.get('/api/health', async () => ({ ok: true, uptime: process.uptime() }));
+  app.get('/healthz', async () => ({ ok: true }));
+
+  let manifestSummary: ManifestSummary | undefined;
+
+  app.get('/readyz', async (_req, reply) => {
+    const snapshot = readiness.snapshot();
+    const statusCode = snapshot.status === 'ready' ? 200 : 503;
+    reply.code(statusCode);
+    return { status: snapshot.status, message: snapshot.message, manifest: manifestSummary };
+  });
+
+  try {
+    const definition = await tryLoadModuleDefinition();
+    if (definition) {
+      manifestSummary = summarizeManifest(definition.manifest, definition.routes);
+      logManifestSummary(definition.manifest, definition.routes);
+      mountRoutes(app, definition);
+    } else {
+      console.info('[fastify] no module definition found. Routes will be empty.');
+    }
+  } catch (error) {
+    readiness.error((error as Error).message ?? 'module load failed');
+    console.error('[fastify] failed to load module definition:', error);
+  }
+
+  await app.listen({ port, host: '0.0.0.0' });
+
+  if (readiness.snapshot().status !== 'error') {
+    readiness.ready();
+  }
+
+  // Dev runner watches for this readiness line
+  console.info('API server running');
+  console.info(`[webstir-backend] mode=${mode} port=${port}`);
+}
+
+function mountRoutes(app: import('fastify').FastifyInstance, definition: ModuleDefinitionLike) {
+  const routes = Array.isArray(definition?.routes) ? definition.routes : [];
+  for (const r of routes) {
+    try {
+      const method = String(r.definition?.method ?? 'GET').toUpperCase();
+      const url = String(r.definition?.path ?? '/');
+      const handler = r.handler;
+      if (typeof handler !== 'function') continue;
+
+      app.route({
+        method: method as any,
+        url,
+        handler: async (req, reply) => {
+          const requestId = extractRequestId(req);
+          reply.header('x-request-id', requestId);
+          const envAccessor = createEnvAccessor();
+          const ctx: Record<string, unknown> = {
+            request: req,
+            reply,
+            auth: undefined,
+            session: null,
+            db: {},
+            env: envAccessor,
+            logger: createRequestLogger(requestId),
+            requestId,
+            now: () => new Date(),
+            params: (req as any).params ?? {},
+            query: (req as any).query ?? {},
+            body: (req as any).body ?? {}
+          };
+          const result = await handler(ctx);
+          const status = result?.status ?? (result?.errors ? 400 : 200);
+          const headers = result?.headers ?? { 'content-type': 'application/json' };
+          for (const [k, v] of Object.entries(headers)) {
+            reply.header(k, String(v));
+          }
+          if (result?.errors) {
+            reply.code(status).send({ errors: result.errors });
+          } else {
+            reply.code(status).send(result?.body ?? null);
+          }
+        }
+      });
+      console.info(`[fastify] mounted ${method} ${url}`);
+    } catch (error) {
+      console.warn('[fastify] failed to mount route', error);
+    }
+  }
+}
+
+async function tryLoadModuleDefinition(): Promise<ModuleDefinitionLike | undefined> {
+  const candidates = ['../module.js', '../module/index.js'];
+  for (const rel of candidates) {
+    try {
+      const url = new URL(rel, import.meta.url);
+      const mod = await import(url.toString());
+      const def = (mod && (mod.module || mod.moduleDefinition || mod.default)) as ModuleDefinitionLike;
+      if (def && typeof def === 'object') return def;
+    } catch {
+      // ignore and try next
+    }
+  }
+  return undefined;
+}
+
+function summarizeManifest(manifest?: ModuleManifestLike, routes?: ModuleRoute[]): ManifestSummary | undefined {
+  if (!manifest) return undefined;
+  const routeCount = Array.isArray(manifest.routes) ? manifest.routes.length : Array.isArray(routes) ? routes.length : 0;
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    routes: routeCount,
+    capabilities: manifest.capabilities && manifest.capabilities.length > 0 ? manifest.capabilities : undefined
+  };
+}
+
+function logManifestSummary(manifest: ModuleManifestLike | undefined, routes?: ModuleRoute[]): void {
+  if (!manifest) {
+    console.info('[fastify] manifest metadata not found.');
+    return;
+  }
+  const caps = manifest.capabilities?.length ? ` [${manifest.capabilities.join(', ')}]` : '';
+  const count = Array.isArray(manifest.routes) ? manifest.routes.length : Array.isArray(routes) ? routes.length : 0;
+  console.info(`[fastify] manifest name=${manifest.name ?? 'unknown'} routes=${count}${caps}`);
+}
+
+function createEnvAccessor(): EnvAccessor {
+  return {
+    get: (name) => process.env[name],
+    require: (name) => {
+      const value = process.env[name];
+      if (value === undefined) {
+        throw new Error(`Missing required env var ${name}`);
+      }
+      return value;
+    },
+    entries: () => ({ ...process.env })
+  };
+}
+
+function createRequestLogger(requestId: string, bindings: Record<string, unknown> = {}): Logger {
+  const logWithLevel = (level: LogLevel, message: string, metadata?: Record<string, unknown>) => {
+    const bindingKeys = Object.keys(bindings);
+    const suffix = bindingKeys.length ? ` ${bindingKeys.map((k) => `${k}=${JSON.stringify(bindings[k])}`).join(' ')}` : '';
+    const writer = level === 'error' ? console.error : level === 'warn' ? console.warn : console.log;
+    if (metadata) {
+      writer(`[${level}] [request ${requestId}] ${message}${suffix}`, metadata);
+    } else {
+      writer(`[${level}] [request ${requestId}] ${message}${suffix}`);
+    }
+  };
+
+  return {
+    level: 'info',
+    log: logWithLevel,
+    debug: (message, metadata) => logWithLevel('debug', message, metadata),
+    info: (message, metadata) => logWithLevel('info', message, metadata),
+    warn: (message, metadata) => logWithLevel('warn', message, metadata),
+    error: (message, metadata) => logWithLevel('error', message, metadata),
+    with(extra) {
+      return createRequestLogger(requestId, { ...bindings, ...extra });
+    }
+  };
+}
+
+function extractRequestId(req: { id?: string; headers?: Record<string, unknown> }): string {
+  if (req && typeof req.id === 'string' && req.id.length > 0) {
+    return req.id;
+  }
+  const header = req?.headers?.['x-request-id'];
+  if (typeof header === 'string' && header.length > 0) {
+    return header;
+  }
+  if (Array.isArray(header) && header.length > 0) {
+    return header[0] as string;
+  }
+  try {
+    return randomUUID();
+  } catch {
+    return `${Date.now()}`;
+  }
+}
+
+function createReadinessTracker() {
+  let status: ReadinessStatus = 'booting';
+  let message: string | undefined;
+  return {
+    booting() {
+      status = 'booting';
+      message = undefined;
+    },
+    ready() {
+      status = 'ready';
+      message = undefined;
+    },
+    error(reason: string) {
+      status = 'error';
+      message = reason;
+    },
+    snapshot() {
+      return { status, message };
+    }
+  };
+}
+
+// Execute when launched directly
+const isMain = (() => {
+  try {
+    const argv1 = process.argv?.[1];
+    if (!argv1) return false;
+    const here = new URL(import.meta.url);
+    const run = new URL(`file://${argv1}`);
+    return here.pathname === run.pathname;
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  start().catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+  });
+}

package/templates/backend/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "../../build/backend",
+    "rootDir": ".",
+    "declaration": false,
+    "sourceMap": true,
+    "types": ["node"],
+    "resolveJsonModule": true
+  },
+  "include": ["**/*"],
+  "exclude": ["../../build", "../../dist", "node_modules"]
+}