arcway 0.1.26 → 0.1.27

package/client/fetcher.js

@@ -2,13 +2,15 @@ class ApiError extends Error {
   status;
   code;
   details;
+  data;
 
-  constructor(status, code, message, details) {
+  constructor(status, code, message, details, data) {
     super(message);
     this.name = 'ApiError';
     this.status = status;
     this.code = code;
     this.details = details;
+    this.data = data;
   }
 }
 
@@ -39,6 +41,7 @@ async function soloFetch(url, init) {
         json.error.code || 'UNKNOWN',
         json.error.message || res.statusText,
         json.error.details,
+        json.data,
       );
     }
     throw new ApiError(res.status, 'UNKNOWN', json?.message || res.statusText);

package/client/hooks/swr-compat.js

@@ -1,4 +1,5 @@
 import * as SWR from 'swr';
+import * as SWRInfinite from 'swr/infinite';
 import * as SWRMutation from 'swr/mutation';
 
 function resolveHook(mod) {
@@ -15,11 +16,12 @@ function resolveNamed(mod, key) {
 }
 
 const useSWR = resolveHook(SWR);
+const useSWRInfinite = resolveHook(SWRInfinite);
 const useSWRConfig = resolveNamed(SWR, 'useSWRConfig');
 const useSWRMutation = resolveHook(SWRMutation);
 
-if (!useSWR || !useSWRConfig || !useSWRMutation) {
+if (!useSWR || !useSWRInfinite || !useSWRConfig || !useSWRMutation) {
   throw new Error('Arcway failed to resolve SWR hooks');
 }
 
-export { useSWR, useSWRConfig, useSWRMutation };
+export { useSWR, useSWRInfinite, useSWRConfig, useSWRMutation };

package/client/hooks/use-api-paginated.js

@@ -0,0 +1,74 @@
+import { useCallback, useMemo, useRef } from 'react';
+import { useApiContext } from '../provider.js';
+import { soloFetch } from '../fetcher.js';
+import { stringifyQuery } from '../query.js';
+import { useSWRConfig, useSWRInfinite } from './swr-compat.js';
+
+function buildUrl(base, query) {
+  if (!query) return base;
+  const qs = stringifyQuery(query);
+  return qs ? `${base}?${qs}` : base;
+}
+
+export default function useApiPaginated(path, getQuery, options) {
+  const { pathPrefix, headers } = useApiContext();
+  const { mutate: globalMutate } = useSWRConfig();
+  const getQueryRef = useRef(getQuery);
+  getQueryRef.current = getQuery;
+
+  const disabled = path === null || options?.disable === true;
+  const fullPath = disabled ? null : `${pathPrefix}${path}`;
+  const swrConfig = useMemo(() => {
+    const { disable: _disable, ws: _ws, ...rest } = options ?? {};
+    return rest;
+  }, [options]);
+
+  const getKey = useCallback(
+    (pageIndex, previousPageData) => {
+      if (!fullPath) return null;
+
+      const query =
+        typeof getQueryRef.current === 'function'
+          ? getQueryRef.current(pageIndex, previousPageData)
+          : getQueryRef.current;
+
+      if (query === null) return null;
+      return buildUrl(fullPath, query);
+    },
+    [fullPath],
+  );
+
+  const result = useSWRInfinite(
+    getKey,
+    (key) => soloFetch(key, { headers }),
+    swrConfig,
+  );
+
+  const makeMethod = useCallback(
+    (method) => async (body) => {
+      if (!fullPath) throw new Error('Cannot call mutation on a disabled useApiPaginated hook');
+
+      const res = await soloFetch(fullPath, {
+        method,
+        headers: {
+          ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+          ...headers,
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      });
+
+      await globalMutate((key) => typeof key === 'string' && key.startsWith(fullPath));
+      return res;
+    },
+    [fullPath, headers, globalMutate],
+  );
+
+  return {
+    ...result,
+    loading: result.isLoading,
+    post: makeMethod('POST'),
+    put: makeMethod('PUT'),
+    patch: makeMethod('PATCH'),
+    del: makeMethod('DELETE'),
+  };
+}

package/client/index.js

@@ -7,6 +7,7 @@ export {
   useWsManager,
 } from './provider.js';
 export { default as useApi } from './hooks/use-api.js';
+export { default as useApiPaginated } from './hooks/use-api-paginated.js';
 export { default as useQuery } from './hooks/use-query.js';
 export { default as useMutation } from './hooks/use-mutation.js';
 export { default as useDebounce } from './hooks/use-debounce.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",
@@ -47,11 +47,11 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.987.0",
     "@babel/core": "^7.29.0",
-    "@vitejs/plugin-react": "^5.1.0",
     "@base-ui/react": "^1.2.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@tailwindcss/vite": "^4.1.18",
     "@tailwindcss/postcss": "^4.1.18",
+    "@tailwindcss/vite": "^4.1.18",
+    "@vitejs/plugin-react": "^5.1.0",
     "arktype": "^2.1.29",
     "bcryptjs": "^3.0.3",
     "better-sqlite3": "^12.6.2",
@@ -80,6 +80,7 @@
     "knex": "^3.1.0",
     "lucide-react": "^0.564.0",
     "mailparser": "^3.9.3",
+    "ms": "^2.1.3",
     "nanoid": "^5.1.6",
     "negotiator": "^1.0.0",
     "nodemailer": "^8.0.1",

package/server/boot/index.js

@@ -3,6 +3,7 @@ import { createInfrastructure, destroyInfrastructure } from './infrastructure.js
 import { EventHandler } from '../events/handler.js';
 import { JobRunner } from '../jobs/runner.js';
 import { WorkerPool } from '../jobs/worker-pool.js';
+import { createWorkerData } from '../jobs/worker-config.js';
 import { loadEnvFiles } from '../env.js';
 import { McpRouter } from '../mcp/index.js';
 import WebServer from '../web-server.js';
@@ -16,6 +17,7 @@ import { createWsBackplane } from '../ws/backplane.js';
 import { runHook } from './hooks.js';
 import { createViteDevRouter } from '../pages/vite-dev.js';
 import { resolvePagesOutDir } from '../pages/out-dir.js';
+import { collectRuntimeMeta } from '../meta.js';
 import path from 'node:path';
 
 async function boot(options) {
@@ -27,6 +29,7 @@ async function boot(options) {
 
   const infrastructure = await createInfrastructure(config, { runMigrations: true });
   const { db, redis, queue, cache, files, mail, events, log } = infrastructure;
+  const meta = await collectRuntimeMeta(rootDir);
 
   if (envFiles.length > 0) log.info('Env files loaded', { envFiles });
 
@@ -37,7 +40,7 @@ async function boot(options) {
   // framework services and to the init/ready/shutdown hooks. Mutations from
   // the init hook (e.g. wrapping `appContext.db`) persist for process lifetime
   // because downstream consumers read properties off this reference at use time.
-  const appContext = { db, redis, events, queue, cache, files, mail, log, fileWatcher };
+  const appContext = { db, redis, events, queue, cache, files, mail, log, fileWatcher, meta };
 
   await runHook('init', appContext, rootDir);
 
@@ -50,14 +53,14 @@ async function boot(options) {
   });
   await eventHandler.init();
 
-  // Workers rebuild their own infrastructure from a JSON-safe config snapshot,
-  // so anything non-serializable on the main-thread config (streams, functions)
-  // must not ride through workerData. makeConfig already yields plain objects.
+  // Workers rebuild their own infrastructure. workerData must stay structured-
+  // clone safe, so function-valued app config hooks are stripped from the
+  // snapshot and reloaded from arcway.config.js inside worker-entry.
   const workerPool =
     config.jobs?.workerPoolSize > 0
       ? new WorkerPool({
           size: config.jobs.workerPoolSize,
-          workerData: { config },
+          workerData: createWorkerData({ config, rootDir, mode, meta }),
           defaultTimeoutMs: config.jobs?.staleTimeoutMs ?? null,
         })
       : null;
@@ -70,6 +73,7 @@ async function boot(options) {
     mail,
     events,
     log,
+    meta,
     workerPool,
   });
   await jobRunner.init();
@@ -87,7 +91,8 @@ async function boot(options) {
 
   const pagesRouter = new PagesRouter(config, { rootDir, log, mode, fileWatcher, appContext });
   await pagesRouter.init();
-  const pagesOutDir = resolvePagesOutDir(config, rootDir, mode);
+  const resolveCurrentPagesOutDir = () => resolvePagesOutDir(config, rootDir, mode);
+  const pagesOutDir = resolveCurrentPagesOutDir();
   const viteRouter =
     mode === 'development' && config.pages?.vite?.enabled === true
       ? await createViteDevRouter({ rootDir, log, config })
@@ -101,6 +106,7 @@ async function boot(options) {
 
   const staticRouter = new StaticRouter({
     outDir: pagesOutDir,
+    ...(mode === 'production' ? { resolveOutDir: resolveCurrentPagesOutDir } : {}),
     publicDir: path.join(rootDir, 'public'),
   });
 

package/server/build.js

@@ -1,6 +1,48 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { makeConfig } from './config/loader.js';
 import { buildPages } from './pages/build.js';
-import { resolvePagesOutDir } from './pages/out-dir.js';
+import {
+  createPagesVersionedBuildTarget,
+  pruneOldPagesBuilds,
+  resolvePagesBaseOutDir,
+} from './pages/out-dir.js';
+import { discoverRoutes } from './router/routes.js';
+import { discoverMiddleware } from './router/middleware.js';
+import { EventHandler } from './events/handler.js';
+import { discoverJobs } from './jobs/runner.js';
+import { collectRuntimeMeta } from './meta.js';
+
+async function writeBuildMeta(rootDir, meta) {
+  const buildDir = path.join(rootDir, '.build');
+  const targetPath = path.join(buildDir, 'meta.json');
+  const tempPath = path.join(buildDir, `meta.json.next-${process.pid}`);
+  await fs.mkdir(buildDir, { recursive: true });
+  await fs.writeFile(tempPath, JSON.stringify(meta, null, 2));
+  await fs.rename(tempPath, targetPath);
+}
+
+async function validateServerModules(config) {
+  if (config?.api?.enabled !== false && config?.api?.dir) {
+    await discoverRoutes(config.api.dir);
+    await discoverMiddleware(config.api.dir);
+  }
+
+  if (config?.events?.dir) {
+    const handler = new EventHandler(
+      { dir: config.events.dir },
+      {
+        events: { subscribe() {} },
+        log: { info() {}, warn() {}, error() {}, extend() { return this; } },
+      },
+    );
+    await handler.init();
+  }
+
+  if (config?.jobs?.enabled !== false && config?.jobs?.dir) {
+    await discoverJobs(config.jobs.dir);
+  }
+}
 
 async function build(options) {
   const rootDir = options?.rootDir ?? process.cwd();
@@ -10,16 +52,32 @@ async function build(options) {
   let pages;
   const pagesEnabled = config?.pages?.enabled !== false;
   if (pagesEnabled) {
+    const baseOutDir = resolvePagesBaseOutDir(config, rootDir, 'production');
+    const target = await createPagesVersionedBuildTarget(baseOutDir);
     pages = await buildPages({
       rootDir,
-      outDir: resolvePagesOutDir(config, rootDir, 'production'),
+      outDir: target.outDir,
       serverTarget: buildTarget,
       minify: true,
       fonts: config?.pages?.fonts,
     });
+    await pruneOldPagesBuilds(baseOutDir, config?.pages?.retainBuilds ?? 5);
+    pages = {
+      ...pages,
+      baseOutDir,
+      buildHash: target.buildHash,
+      outDir: target.outDir,
+    };
   }
 
-  return { pages };
+  await validateServerModules(config);
+  const meta = await collectRuntimeMeta(rootDir);
+  await writeBuildMeta(rootDir, {
+    ...meta,
+    ...(pages?.buildHash ? { pagesBuildHash: pages.buildHash } : {}),
+  });
+
+  return { pages, serverValidated: true, meta };
 }
 
-export { build };
+export { build, validateServerModules };

package/server/cache/index.js

@@ -1,5 +1,6 @@
 import MemoryCacheDriver from './drivers/memory.js';
 import RedisCacheDriver from './drivers/redis.js';
+import { normalizeCacheTtl } from './ttl.js';
 
 class Cache {
   _driver;
@@ -9,6 +10,10 @@ class Cache {
   constructor(config, { redis, log } = {}) {
     this._log = log;
     this._namespace = config?.namespace ?? '';
+    this._defaultTtlMs =
+      config?.defaultTtlMs === undefined
+        ? undefined
+        : normalizeCacheTtl(config.defaultTtlMs, 'cache.defaultTtlMs');
 
     if (config?.driver === 'redis') {
       this._driver = new RedisCacheDriver(redis.client, redis.keyPrefix);
@@ -35,7 +40,9 @@ class Cache {
   }
 
   async set(key, value, ttlMs) {
-    await this._driver.set(this._namespace, key, JSON.stringify(value), ttlMs);
+    const resolvedTtlMs =
+      ttlMs === undefined ? this._defaultTtlMs : normalizeCacheTtl(ttlMs, 'cache ttl');
+    await this._driver.set(this._namespace, key, JSON.stringify(value), resolvedTtlMs);
   }
 
   async delete(key) {
@@ -52,7 +59,9 @@ class Cache {
       }
     }
     const value = await fn();
-    await this._driver.set(this._namespace, key, JSON.stringify(value), ttlMs);
+    const resolvedTtlMs =
+      ttlMs === undefined ? this._defaultTtlMs : normalizeCacheTtl(ttlMs, 'cache ttl');
+    await this._driver.set(this._namespace, key, JSON.stringify(value), resolvedTtlMs);
     return value;
   }
 
@@ -62,6 +71,7 @@ class Cache {
     child._driver = this._driver;
     child._log = this._log;
     child._namespace = namespace;
+    child._defaultTtlMs = this._defaultTtlMs;
     return child;
   }
 }

package/server/cache/ttl.js

@@ -0,0 +1,24 @@
+import { parseDuration } from '../config/duration.js'
+
+function parseCacheTtl(value) {
+  if (value === undefined || value === null) return null
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null
+  if (typeof value !== 'string') return null
+
+  const normalized = value.trim()
+  if (!normalized) return null
+
+  return parseDuration(normalized)
+}
+
+function normalizeCacheTtl(value, label = 'cache ttl') {
+  const parsed = parseCacheTtl(value)
+  if (parsed === null) {
+    throw new Error(
+      `Invalid ${label}: ${JSON.stringify(value)}. Use milliseconds as a number or a string like "500ms", "30s", "15m", "2h", or "7d".`,
+    )
+  }
+  return parsed
+}
+
+export { parseCacheTtl, normalizeCacheTtl }

package/server/config/duration.js

@@ -0,0 +1,49 @@
+import ms from 'ms'
+
+function parseDuration(value) {
+  if (value === undefined || value === null) return null
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null
+  if (typeof value !== 'string') return null
+
+  const normalized = value.trim()
+  if (!normalized) return null
+
+  const parsed = ms(normalized)
+  return typeof parsed === 'number' ? parsed : null
+}
+
+function normalizeDurationMs(value, label) {
+  const parsed = parseDuration(value)
+  if (parsed === null) {
+    throw new Error(
+      `Invalid ${label}: ${JSON.stringify(value)}. Use milliseconds as a number or a string like "500ms", "30s", "15m", "2h", or "7d".`,
+    )
+  }
+  return parsed
+}
+
+function normalizeDurationSeconds(value, label) {
+  if (value === 0) return 0
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null
+  const parsed = parseDuration(value)
+  if (parsed === null) {
+    throw new Error(
+      `Invalid ${label}: ${JSON.stringify(value)}. Use seconds as a number or a string like "30s", "15m", "2h", or "7d".`,
+    )
+  }
+  return Math.floor(parsed / 1000)
+}
+
+function normalizeDurationDays(value, label) {
+  if (value === null) return null
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null
+  const parsed = parseDuration(value)
+  if (parsed === null) {
+    throw new Error(
+      `Invalid ${label}: ${JSON.stringify(value)}. Use days as a number or a string like "7d", "2w", or "168h".`,
+    )
+  }
+  return Math.floor(parsed / 86_400_000)
+}
+
+export { parseDuration, normalizeDurationMs, normalizeDurationSeconds, normalizeDurationDays }

package/server/config/modules/cache.js

@@ -1,10 +1,16 @@
+import { normalizeCacheTtl } from '../../cache/ttl.js';
+
 const DEFAULTS = {
   driver: 'memory',
 };
 
 function resolve(config) {
   if (!config.cache) return config;
-  return { ...config, cache: { ...DEFAULTS, ...config.cache } };
+  const resolved = { ...DEFAULTS, ...config.cache };
+  if (resolved.defaultTtlMs !== undefined) {
+    resolved.defaultTtlMs = normalizeCacheTtl(resolved.defaultTtlMs, 'cache.defaultTtlMs');
+  }
+  return { ...config, cache: resolved };
 }
 
 export default resolve;

package/server/config/modules/jobs.js

@@ -1,5 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
+import { normalizeDurationMs } from '../duration.js';
 
 // Leave one core free for the main thread (dispatch/polling/HTTP). 0 disables
 // worker threads entirely and runs handlers inline on the main thread.
@@ -20,9 +21,21 @@ const DEFAULTS = {
 
 function resolve(config, { rootDir } = {}) {
   const jobs = { ...DEFAULTS, ...config.jobs };
-  if (jobs.dir && !path.isAbsolute(jobs.dir)) {
+  if (rootDir && jobs.dir && !path.isAbsolute(jobs.dir)) {
     jobs.dir = path.resolve(rootDir, jobs.dir);
   }
+  if (jobs.backoffMs !== undefined) {
+    jobs.backoffMs = normalizeDurationMs(jobs.backoffMs, 'jobs.backoffMs');
+  }
+  if (jobs.pollIntervalMs !== undefined) {
+    jobs.pollIntervalMs = normalizeDurationMs(jobs.pollIntervalMs, 'jobs.pollIntervalMs');
+  }
+  if (jobs.cooldownMs !== undefined) {
+    jobs.cooldownMs = normalizeDurationMs(jobs.cooldownMs, 'jobs.cooldownMs');
+  }
+  if (jobs.staleTimeoutMs !== undefined) {
+    jobs.staleTimeoutMs = normalizeDurationMs(jobs.staleTimeoutMs, 'jobs.staleTimeoutMs');
+  }
   if (jobs.workerPoolSize === undefined) jobs.workerPoolSize = defaultWorkerPoolSize();
   return { ...config, jobs };
 }

package/server/config/modules/mail.js

@@ -1,3 +1,5 @@
+import { normalizeDurationDays, normalizeDurationSeconds } from '../duration.js';
+
 const DEFAULTS = {
   driver: 'console',
   enabled: true,
@@ -5,7 +7,20 @@ const DEFAULTS = {
 
 function resolve(config) {
   if (!config.mail) return config;
-  return { ...config, mail: { ...DEFAULTS, ...config.mail } };
+  const mail = { ...DEFAULTS, ...config.mail };
+  if (mail.inbound?.imap?.pollIntervalSeconds !== undefined) {
+    mail.inbound.imap.pollIntervalSeconds = normalizeDurationSeconds(
+      mail.inbound.imap.pollIntervalSeconds,
+      'mail.inbound.imap.pollIntervalSeconds',
+    );
+  }
+  if (mail.inbound?.retentionDays !== undefined) {
+    mail.inbound.retentionDays = normalizeDurationDays(
+      mail.inbound.retentionDays,
+      'mail.inbound.retentionDays',
+    );
+  }
+  return { ...config, mail };
 }
 
 export default resolve;

package/server/config/modules/pages.js

@@ -5,6 +5,7 @@ const DEFAULTS = {
   dir: 'pages',
   outDir: '.build/pages',
   devOutDir: '.build/dev/pages',
+  retainBuilds: 5,
   vite: {
     enabled: true,
   },

package/server/config/modules/queue.js

@@ -1,10 +1,16 @@
+import { normalizeDurationMs } from '../duration.js';
+
 const DEFAULTS = {
   tableName: 'arcway_queue',
   lockCooldownMs: 5 * 60 * 1000,
 };
 
 function resolve(config) {
-  return { ...config, queue: { ...DEFAULTS, ...config.queue } };
+  const queue = { ...DEFAULTS, ...config.queue };
+  if (queue.lockCooldownMs !== undefined) {
+    queue.lockCooldownMs = normalizeDurationMs(queue.lockCooldownMs, 'queue.lockCooldownMs');
+  }
+  return { ...config, queue };
 }
 
 export default resolve;

package/server/config/modules/server.js

@@ -1,3 +1,5 @@
+import { normalizeDurationMs, normalizeDurationSeconds } from '../duration.js';
+
 const DEFAULTS = {
   host: '0.0.0.0',
   port: 3000,
@@ -19,11 +21,21 @@ function resolveCors(config, mode) {
   if (config === false) return void 0;
   if (config === void 0 && mode === 'production') return void 0;
   const userConfig = typeof config === 'object' ? config : {};
-  return { ...DEFAULT_CORS, ...userConfig };
+  const resolved = { ...DEFAULT_CORS, ...userConfig };
+  if (resolved.maxAge !== undefined) {
+    resolved.maxAge = normalizeDurationSeconds(resolved.maxAge, 'server.cors.maxAge');
+  }
+  return resolved;
 }
 
 function resolve(config, { mode } = {}) {
   const server = { ...DEFAULTS, ...config.server };
+  if (server.shutdownTimeoutMs !== undefined) {
+    server.shutdownTimeoutMs = normalizeDurationMs(
+      server.shutdownTimeoutMs,
+      'server.shutdownTimeoutMs',
+    );
+  }
   server.cors = resolveCors(server.cors, mode);
   return { ...config, server };
 }

package/server/config/modules/websocket.js

@@ -1,3 +1,5 @@
+import { normalizeDurationMs } from '../duration.js';
+
 const DEFAULTS = {
   path: '/ws',
   pingIntervalMs: 30000,
@@ -8,6 +10,12 @@ const VALID_DRIVERS = new Set(['memory', 'redis']);
 
 function resolve(config) {
   const websocket = { ...DEFAULTS, ...config.websocket };
+  if (websocket.pingIntervalMs !== undefined) {
+    websocket.pingIntervalMs = normalizeDurationMs(
+      websocket.pingIntervalMs,
+      'websocket.pingIntervalMs',
+    );
+  }
   if (!VALID_DRIVERS.has(websocket.driver)) {
     throw new Error(
       `Invalid config: websocket.driver="${websocket.driver}" must be one of: ${[...VALID_DRIVERS].join(', ')}`,

package/server/context.js

@@ -1,3 +1,6 @@
+import * as vault from './lib/vault/index.js';
+import { wsBroadcastToPath, wsSendToSocket } from './ws/registry.js';
+
 function trackDb(db) {
   if (!db || typeof db !== 'function' && typeof db !== 'object') return { db, stats: { queries: 0, durationMs: 0 } };
   const stats = { queries: 0, durationMs: 0 };
@@ -58,8 +61,60 @@ function wrapBuilder(builder, stats) {
   return builder;
 }
 
+function buildErrResponse(input, status = 400) {
+  if (typeof input === 'string') {
+    return { status, error: { message: input } };
+  }
+  if (input instanceof Error) {
+    return { status, error: { message: input.message } };
+  }
+  if (input && typeof input === 'object') {
+    const { status: explicitStatus, ...error } = input;
+    return { status: explicitStatus ?? status, error };
+  }
+  return { status, error: { message: 'An error occurred' } };
+}
+
+function normalizeEvent(event) {
+  if (event === undefined) return undefined;
+  return {
+    name: event?.name ?? null,
+    payload: Object.prototype.hasOwnProperty.call(event || {}, 'payload')
+      ? (event.payload ?? null)
+      : null,
+  };
+}
+
+function normalizeMeta(meta) {
+  return {
+    builtAt: meta?.builtAt ?? null,
+    version: meta?.version ?? null,
+    buildNumber: meta?.buildNumber ?? null,
+    branch: meta?.branch ?? null,
+    tag: meta?.tag ?? null,
+    dirty: meta?.dirty ?? null,
+    environment: meta?.environment ?? process.env.NODE_ENV ?? 'development',
+    nodeVersion: meta?.nodeVersion ?? process.version,
+    shortSha: meta?.shortSha ?? null,
+    sha: meta?.sha ?? null,
+    packageVersion: meta?.packageVersion ?? null,
+  };
+}
+
 function buildContext(appContext, extras) {
   const tracked = trackDb(appContext.db);
+  const normalizedExtras = { ...extras };
+  if (Object.prototype.hasOwnProperty.call(normalizedExtras, 'event')) {
+    normalizedExtras.event = normalizeEvent(normalizedExtras.event);
+  }
+  const req = normalizedExtras.req;
+  const ws =
+    req?.socketId && req?.path
+      ? {
+          send: (response) => wsSendToSocket(req.socketId, req.path, response),
+          broadcast: (response) => wsBroadcastToPath(req.path, response),
+        }
+      : null;
   const ctx = {
     db: tracked.db,
     log: appContext.log,
@@ -68,10 +123,14 @@ function buildContext(appContext, extras) {
     queue: appContext.queue,
     files: appContext.files,
     mail: appContext.mail,
+    meta: normalizeMeta(appContext.meta),
+    vault,
+    ws,
+    err: (input, status) => buildErrResponse(input, status),
     _dbStats: tracked.stats,
-    ...extras,
+    ...normalizedExtras,
   };
   return ctx;
 }
 
-export { buildContext };
+export { buildContext, buildErrResponse };