arcway 0.1.26 → 0.1.28

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.28",
   "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,8 @@ 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 { createPluginManager } from '../plugins/manager.js';
 import path from 'node:path';
 
 async function boot(options) {
@@ -25,8 +28,12 @@ async function boot(options) {
   const envFiles = loadEnvFiles(rootDir, mode);
   const config = await makeConfig(rootDir, { overrides: options.configOverrides, mode });
 
+  const plugins = await createPluginManager(config.plugins, { runLifecycle: false });
+  config.database.pluginMigrations = plugins.migrations();
+
   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 +44,12 @@ 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 };
+
+  plugins.log = log;
+  appContext.plugins = plugins;
+
+  await plugins.runEnabledLifecycle();
 
   await runHook('init', appContext, rootDir);
 
@@ -50,14 +62,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,7 +82,9 @@ async function boot(options) {
     mail,
     events,
     log,
+    meta,
     workerPool,
+    plugins,
   });
   await jobRunner.init();
 
@@ -87,7 +101,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 +116,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,59 @@
+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';
+import { createPluginManager } from './plugins/manager.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) {
+  const plugins = await createPluginManager(config.plugins, { runLifecycle: false });
+  if (config?.api?.enabled !== false && config?.api?.dir) {
+    await discoverRoutes(config.api.dir);
+    await discoverMiddleware(config.api.dir);
+    await plugins.discoverRoutes();
+  }
+
+  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);
+    await plugins.discoverJobs();
+  }
+}
 
 async function build(options) {
   const rootDir = options?.rootDir ?? process.cwd();
@@ -10,16 +63,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/loader.js

@@ -12,12 +12,14 @@ import resolveRedis from './modules/redis.js';
 import resolveCache from './modules/cache.js';
 import resolveEvents from './modules/events.js';
 import resolveMail from './modules/mail.js';
+import resolveSecrets from './modules/secrets.js';
 import resolveSession from './modules/session.js';
 import resolvePages from './modules/pages.js';
 import resolveBuild from './modules/build.js';
 import resolveMcp from './modules/mcp.js';
 import resolveWebsocket from './modules/websocket.js';
 import resolveSeeds from './modules/seeds.js';
+import resolvePlugins from './modules/plugins.js';
 
 function deepMerge(target, source) {
   const result = { ...target };
@@ -49,12 +51,14 @@ const modules = [
   resolveFiles,
   resolveMail,
   resolveRedis,
+  resolveSecrets,
   resolveSession,
   resolvePages,
   resolveBuild,
   resolveMcp,
   resolveWebsocket,
   resolveSeeds,
+  resolvePlugins,
 ];
 
 async function makeConfig(rootDir, { overrides, mode } = {}) {

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/mcp.js

@@ -3,7 +3,11 @@ const DEFAULTS = {
 };
 
 function resolve(config) {
-  return { ...config, mcp: { ...DEFAULTS, ...config.mcp } };
+  const mcp = { ...DEFAULTS, ...config.mcp };
+  if (!mcp.secret && config.secrets?.values?.['mcp-api']) {
+    mcp.secret = config.secrets.values['mcp-api'];
+  }
+  return { ...config, mcp };
 }
 
 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/plugins.js

@@ -0,0 +1,18 @@
+import path from 'node:path';
+
+const DEFAULTS = {
+  enabled: false,
+  dirs: ['plugins'],
+};
+
+function resolve(config, { rootDir } = {}) {
+  const plugins = { ...DEFAULTS, ...config.plugins };
+  const dirs = Array.isArray(plugins.dirs) ? plugins.dirs : [plugins.dirs];
+  plugins.dirs = dirs
+    .filter((dir) => typeof dir === 'string' && dir.length > 0)
+    .map((dir) => (rootDir && !path.isAbsolute(dir) ? path.resolve(rootDir, dir) : dir));
+  plugins.enabled = plugins.enabled === true;
+  return { ...config, plugins };
+}
+
+export default resolve;

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;