arcway 0.1.9 → 0.1.11

package/client/fetcher.js

@@ -44,7 +44,7 @@ async function soloFetch(url, init) {
     throw new ApiError(res.status, 'UNKNOWN', json?.message || res.statusText);
   }
 
-  return json.data;
+  return json;
 }
 
 export { ApiError, soloFetch };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",
@@ -29,6 +29,7 @@
     "./ui/style-mira.css": "./client/ui/style-mira.css"
   },
   "scripts": {
+    "prepare": "esbuild client/router.jsx --outfile=client/router.js --format=esm --jsx=automatic",
     "test": "vitest run --project=unit",
     "test:storybook": "TMPDIR=~/tmp PLAYWRIGHT_BROWSERS_PATH=~/.cache/playwright vitest run --project=storybook",
     "test:all": "TMPDIR=~/tmp PLAYWRIGHT_BROWSERS_PATH=~/.cache/playwright vitest run",
@@ -37,7 +38,8 @@
     "lint": "eslint server/ client/ tests/",
     "lint:fix": "eslint server/ client/ tests/ --fix",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "deploy:docs": "cd ~/Projects/home-server/baremetal/ansible && ansible-playbook deploy-arcway-docs.yml"
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.987.0",

package/server/bin/cli.js

@@ -11,6 +11,7 @@ import registerLint from './commands/lint.js';
 import registerGraphQLSchema from './commands/graphql-schema.js';
 import registerSchema from './commands/schema.js';
 import registerMigrate from './commands/migrate.js';
+import registerBootstrap from './commands/bootstrap.js';
 
 function getPackageVersion() {
   try {
@@ -36,6 +37,7 @@ function createProgram() {
   registerGraphQLSchema(program);
   registerSchema(program);
   registerMigrate(program);
+  registerBootstrap(program);
   return program;
 }
 

package/server/bin/commands/bootstrap.js

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const FILES = {
+  'arcway.config.js': `export default {
+  database: {
+    client: 'better-sqlite3',
+    connection: { filename: './data.db' },
+  },
+};
+`,
+
+  'api/index.js': `export const GET = {
+  handler: async (ctx) => {
+    return { data: { message: 'Hello from Arcway!' } };
+  },
+};
+`,
+
+  'api/users/index.js': `export const GET = {
+  handler: async (ctx) => {
+    const { db } = ctx;
+    const users = await db('users').select('*');
+    return { data: users };
+  },
+};
+
+export const POST = {
+  schema: {
+    body: { name: 'string', email: 'string.email' },
+  },
+  handler: async (ctx) => {
+    const { req, db, events } = ctx;
+    const [id] = await db('users').insert(req.body);
+    await events.emit('users/created', { id, ...req.body });
+    return { status: 201, data: { id } };
+  },
+};
+`,
+
+  'api/users/[id].js': `export const GET = {
+  handler: async (ctx) => {
+    const { req, db } = ctx;
+    const user = await db('users').where('id', req.query.id).first();
+    if (!user) return { status: 404, error: 'User not found' };
+    return { data: user };
+  },
+};
+`,
+
+  'listeners/users/created.js': `export default async (ctx) => {
+  const { event, log } = ctx;
+  log.info('New user created', { userId: event.payload.id });
+};
+`,
+
+  'jobs/cleanup-sessions.js': `export default {
+  schedule: '0 3 * * *', // Every day at 3 AM
+  handler: async (ctx) => {
+    const { db, log } = ctx;
+    const deleted = await db('sessions')
+      .where('expires_at', '<', new Date().toISOString())
+      .delete();
+    log.info('Cleaned up expired sessions', { deleted });
+  },
+};
+`,
+
+  'migrations/202601010000-create-users.js': `export async function up(knex) {
+  await knex.schema.createTable('users', (table) => {
+    table.increments('id').primary();
+    table.string('name').notNullable();
+    table.string('email').notNullable().unique();
+    table.timestamps(true, true);
+  });
+}
+
+export async function down(knex) {
+  await knex.schema.dropTableIfExists('users');
+}
+`,
+
+  'pages/index.jsx': `export default function Home() {
+  return (
+    <div style={{ padding: '2rem', fontFamily: 'system-ui' }}>
+      <h1>Welcome to Arcway</h1>
+      <p>Edit <code>pages/index.jsx</code> to get started.</p>
+    </div>
+  );
+}
+`,
+
+  '.env': `# NODE_ENV=development
+# SESSION_PASSWORD=change-me-to-a-random-32-char-string
+`,
+
+  '.gitignore': `node_modules/
+.build/
+data.db
+.env.local
+.env.*.local
+`,
+};
+
+function bootstrap(rootDir) {
+  let created = 0;
+  let skipped = 0;
+
+  for (const [relativePath, content] of Object.entries(FILES)) {
+    const fullPath = join(rootDir, relativePath);
+    if (existsSync(fullPath)) {
+      console.log(`  skip  ${relativePath} (already exists)`);
+      skipped++;
+      continue;
+    }
+    const dir = join(fullPath, '..');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(fullPath, content);
+    console.log(`  create  ${relativePath}`);
+    created++;
+  }
+
+  return { created, skipped };
+}
+
+function register(program) {
+  program
+    .command('bootstrap')
+    .description('Scaffold a new Arcway project in the current directory')
+    .action(() => {
+      const rootDir = process.cwd();
+      console.log(`\nBootstrapping Arcway project in ${rootDir}\n`);
+
+      const { created, skipped } = bootstrap(rootDir);
+
+      console.log(`\n  ${created} file(s) created, ${skipped} skipped\n`);
+
+      if (created > 0) {
+        console.log('Next steps:');
+        console.log('  npm install arcway better-sqlite3');
+        console.log('  npx arcway dev\n');
+      }
+    });
+}
+
+export default register;
+export { bootstrap };

package/server/bin/commands/migrate.js

@@ -6,7 +6,10 @@ import { createDB } from '#server/db/index.js';
 async function runMigrateMake(name) {
   const rootDir = process.cwd();
   try {
-    const migrationsDir = path.resolve(rootDir, 'migrations');
+    const mode = process.env.NODE_ENV === 'production' ? 'production' : 'development';
+    loadEnvFiles(rootDir, mode);
+    const config = await makeConfig(rootDir);
+    const migrationsDir = config.database.dir;
     await fs.mkdir(migrationsDir, { recursive: true });
     const now = new Date();
     const timestamp = [

package/server/bin/commands/seed.js

@@ -1,4 +1,3 @@
-import path from 'node:path';
 import { makeConfig } from '#server/config/loader.js';
 import { loadEnvFiles } from '#server/env.js';
 import { createDB } from '#server/db/index.js';
@@ -11,7 +10,7 @@ async function runSeed() {
     const config = await makeConfig(rootDir);
     const db = await createDB(config.database);
     await db.runMigrations();
-    const seedsDir = path.join(rootDir, 'seeds');
+    const seedsDir = config.seeds.dir;
     const results = await runSeeds(db, seedsDir);
     if (results.length === 0) {
       console.log('No seed files found.');

package/server/config/loader.js

@@ -17,6 +17,7 @@ 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';
 
 function deepMerge(target, source) {
   const result = { ...target };
@@ -53,6 +54,7 @@ const modules = [
   resolveBuild,
   resolveMcp,
   resolveWebsocket,
+  resolveSeeds,
 ];
 
 async function makeConfig(rootDir, { overrides, mode } = {}) {

package/server/config/modules/database.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 
 const DEFAULTS = {
   sqliteFilename: '.build/db/arcway.db',
-  migrationsDir: 'migrations',
+  dir: 'migrations',
 };
 
 const CLIENT_MAP = {
@@ -15,8 +15,8 @@ function resolve(config, { rootDir } = {}) {
   const db = { ...DEFAULTS, ...config.database };
   // Resolve friendly client names to actual knex driver names
   db.client = CLIENT_MAP[db.client] ?? db.client;
-  if (db.migrationsDir && !path.isAbsolute(db.migrationsDir)) {
-    db.migrationsDir = path.resolve(rootDir, db.migrationsDir);
+  if (db.dir && !path.isAbsolute(db.dir)) {
+    db.dir = path.resolve(rootDir, db.dir);
   }
   const isSqlite = db.client === 'better-sqlite3' || db.client === 'sqlite3';
   if (isSqlite && !db.connection) {

package/server/config/modules/events.js

@@ -1,13 +1,13 @@
 import path from 'node:path';
 
 const DEFAULTS = {
-  listenersDir: 'listeners',
+  dir: 'listeners',
 };
 
 function resolve(config, { rootDir } = {}) {
   const events = { ...DEFAULTS, ...config.events };
-  if (events.listenersDir && !path.isAbsolute(events.listenersDir)) {
-    events.listenersDir = path.resolve(rootDir, events.listenersDir);
+  if (events.dir && !path.isAbsolute(events.dir)) {
+    events.dir = path.resolve(rootDir, events.dir);
   }
   return { ...config, events };
 }

package/server/config/modules/jobs.js

@@ -6,13 +6,13 @@ const DEFAULTS = {
   pollIntervalMs: 60000,
   tableName: 'arcway_jobs',
   leaseTable: 'arcway_job_leases',
-  jobsDir: 'jobs',
+  dir: 'jobs',
 };
 
 function resolve(config, { rootDir } = {}) {
   const jobs = { ...DEFAULTS, ...config.jobs };
-  if (jobs.jobsDir && !path.isAbsolute(jobs.jobsDir)) {
-    jobs.jobsDir = path.resolve(rootDir, jobs.jobsDir);
+  if (jobs.dir && !path.isAbsolute(jobs.dir)) {
+    jobs.dir = path.resolve(rootDir, jobs.dir);
   }
   return { ...config, jobs };
 }

package/server/config/modules/seeds.js

@@ -0,0 +1,15 @@
+import path from 'node:path';
+
+const DEFAULTS = {
+  dir: 'seeds',
+};
+
+function resolve(config, { rootDir } = {}) {
+  const seeds = { ...DEFAULTS, ...config.seeds };
+  if (seeds.dir && !path.isAbsolute(seeds.dir)) {
+    seeds.dir = path.resolve(rootDir, seeds.dir);
+  }
+  return { ...config, seeds };
+}
+
+export default resolve;

package/server/config/modules/server.js

@@ -3,6 +3,7 @@ const DEFAULTS = {
   port: 3000,
   maxBodySize: 1024 * 1024,
   shutdownTimeoutMs: 10000,
+  trustProxy: false,
 };
 
 const DEFAULT_CORS = {

package/server/db/index.js

@@ -45,6 +45,12 @@ async function createDB(config, { log } = {}) {
     throw new Error(`Database connection failed: ${err}`);
   }
 
+  if (isSqlite) {
+    await db.raw('PRAGMA journal_mode = WAL');
+    await db.raw('PRAGMA busy_timeout = 5000');
+    await db.raw('PRAGMA synchronous = NORMAL');
+  }
+
   const origDestroy = db.destroy.bind(db);
   Object.defineProperty(db, 'destroy', {
     value: async () => {
@@ -56,7 +62,7 @@ async function createDB(config, { log } = {}) {
   });
 
   db.runMigrations = async () => {
-    const migrationsDir = config.migrationsDir;
+    const migrationsDir = config.dir;
     if (!migrationsDir) return;
     const [batch, migrations] = await db.migrate.latest({
       migrationSource: new MigrationSource(migrationsDir),
@@ -69,8 +75,8 @@ async function createDB(config, { log } = {}) {
   };
 
   db.runRollback = async () => {
-    const migrationsDir = config.migrationsDir;
-    if (!migrationsDir) throw new Error('No migrationsDir configured');
+    const migrationsDir = config.dir;
+    if (!migrationsDir) throw new Error('No migrations dir configured');
     const [batch, entries] = await db.migrate.rollback({
       migrationSource: new MigrationSource(migrationsDir),
     });

package/server/events/drivers/memory.js

@@ -6,34 +6,22 @@ class MemoryTransport {
     const regex = patternToRegex(pattern);
     this.subscriptions.push({ pattern, regex, handler });
   }
-  /**
-   * Emit an event. All matching subscribers are called concurrently.
-   * Errors in individual listeners are caught and collected — one failing
-   * listener does not prevent others from running.
-   */
+  /** Emit an event. Handlers run asynchronously — fire-and-forget. */
   async emit(eventName, payload) {
     const matching = this.subscriptions.filter((sub) => sub.regex.test(eventName));
-    if (matching.length === 0) {
-      return;
-    }
-    const errors = [];
-    const results = await Promise.allSettled(
+    if (matching.length === 0) return;
+    Promise.allSettled(
       matching.map((sub) => sub.handler(eventName, payload)),
-    );
-    for (let i = 0; i < results.length; i++) {
-      const result = results[i];
-      if (result.status === 'rejected') {
-        const sub = matching[i];
-        errors.push({ pattern: sub.pattern, error: result.reason });
-        console.error(
-          `Event listener error [${sub.pattern}] for event "${eventName}":`,
-          result.reason,
-        );
+    ).then((results) => {
+      for (let i = 0; i < results.length; i++) {
+        if (results[i].status === 'rejected') {
+          console.error(
+            `Event listener error [${matching[i].pattern}] for event "${eventName}":`,
+            results[i].reason,
+          );
+        }
       }
-    }
-    if (errors.length > 0 && errors.length === matching.length) {
-      throw new Error(`All ${errors.length} listener(s) for event "${eventName}" failed`);
-    }
+    });
   }
   async disconnect() {}
 

package/server/events/handler.js

@@ -20,13 +20,13 @@ function validateHandler(item, filePath, index) {
 
 class EventHandler {
   _events;
-  _listenersDir;
+  _dir;
   _log;
   _appContext;
   _listeners = [];
 
   constructor(config, { events, log, appContext } = {}) {
-    this._listenersDir = config?.listenersDir;
+    this._dir = config?.dir;
     this._events = events;
     this._log = log;
     this._appContext = appContext ?? {
@@ -41,8 +41,8 @@ class EventHandler {
   }
 
   async init() {
-    if (!this._listenersDir) return;
-    const entries = await discoverModules(this._listenersDir, {
+    if (!this._dir) return;
+    const entries = await discoverModules(this._dir, {
       recursive: true,
       label: 'listener file',
     });

package/server/graphql/handler.js

@@ -17,14 +17,14 @@ function createGraphQLHandler(options) {
     cors: false,
     context: async ({ request }) => {
       const loaders = makeLoaders();
-      const requestId = request.headers.get('x-request-id') ?? randomUUID();
+      const id = request.headers.get('x-request-id') ?? randomUUID();
       const headers = {};
       request.headers.forEach((value, key) => {
         headers[key] = value;
       });
       const cookies = parseCookiesFromHeader(request.headers.get('cookie') ?? '');
       const session = await resolveSession(cookies, sessionConfig);
-      return { loaders, session, requestId, headers, cookies };
+      return { loaders, session, id, headers, cookies };
     },
     logging: log
       ? {

package/server/jobs/runner.js

@@ -59,7 +59,7 @@ class JobRunner {
   }
 
   async init() {
-    const jobsDir = this._config?.jobsDir;
+    const jobsDir = this._config?.dir;
     if (!jobsDir) return;
 
     // Discover and register user jobs

package/server/router/api-router.js

@@ -46,7 +46,7 @@ const validateRequest = validateRequestSchema;
 async function serializeResponse(res, response, responseHeaders, statusCode) {
   const customContentType = responseHeaders['Content-Type'] || responseHeaders['content-type'];
   if (!customContentType || customContentType.includes('application/json')) {
-    const responseBody = response.error ? { error: response.error } : { data: response.data };
+    const responseBody = response.error ? { error: response.error } : (response.data ?? null);
     sendJson(res, statusCode, responseBody, responseHeaders);
     return;
   }
@@ -140,7 +140,7 @@ class ApiRouter {
     return buildContext(
       {
         ...this._appContext,
-        log: this._log.extend({ requestId: reqInfo.requestId }),
+        log: this._log.extend({ requestId: reqInfo.id }),
       },
       { req: reqInfo },
     );
@@ -197,7 +197,8 @@ class ApiRouter {
   async handle(req, res) {
     const method = req.method ?? 'GET';
     const pathname = (req.url ?? '/').split('?')[0];
-    const requestId = req.requestId;
+    const id = req.id;
+    const ip = req.ip;
     const startTime = Date.now();
 
     const matched = matchRoute(this._routes, method, pathname);
@@ -205,20 +206,25 @@ class ApiRouter {
 
     const { route, params } = matched;
 
+    // ── Body parsing control ──
+    const body = route.config.parseBody === false ? req.rawBody : req.body;
+
     // ── Validation ──
     const mergedQuery = { ...(req.query ?? {}), ...params };
-    const validated = validateRequest(route.config.schema, mergedQuery, req.body);
+    const validated = validateRequest(route.config.schema, mergedQuery, body);
     if (validated.error) {
       sendJson(res, 400, { error: validated.error });
       return true;
     }
 
     const reqInfo = {
-      requestId,
+      id,
+      ip,
       method,
       path: pathname,
       query: validated.query,
       body: validated.body,
+      rawBody: req.rawBody,
       headers: req.flatHeaders ?? flattenHeaders(req.headers),
       cookies: req.cookies ?? {},
       session: req.session,

package/server/testing/index.js

@@ -128,9 +128,9 @@ async function createTestContext(domainName, options) {
   if (options?.rootDir) {
     const migrationsDir = path.join(options.rootDir, 'migrations');
     await db.migrate.latest({ migrationSource: new MigrationSource(migrationsDir) });
-  } else if (options?.migrationsDir) {
+  } else if (options?.dir || options?.migrationsDir) {
     await db.migrate.latest({
-      migrationSource: new MigrationSource(options.migrationsDir),
+      migrationSource: new MigrationSource(options.dir ?? options.migrationsDir),
     });
   }
   const scopedDb = db;

package/server/web-server.js

@@ -83,12 +83,23 @@ class WebServer {
       }
     }
 
+    const trustProxy = config.server?.trustProxy ?? false;
+
     const requestHandler = (req, res) => {
       // ── Request ID ──
       const incomingId = req.headers['x-request-id'];
-      const requestId = (Array.isArray(incomingId) ? incomingId[0] : incomingId) ?? randomUUID();
-      res.setHeader('X-Request-Id', requestId);
-      req.requestId = requestId;
+      req.id = (Array.isArray(incomingId) ? incomingId[0] : incomingId) ?? randomUUID();
+      res.setHeader('X-Request-Id', req.id);
+
+      // ── Client IP ──
+      if (trustProxy) {
+        const forwarded = req.headers['x-forwarded-for'];
+        req.ip = forwarded
+          ? String(forwarded).split(',')[0].trim()
+          : req.headers['x-real-ip'] ?? req.socket?.remoteAddress ?? '127.0.0.1';
+      } else {
+        req.ip = req.socket?.remoteAddress ?? '127.0.0.1';
+      }
 
       // ── CORS ──
       if (corsConfig) {
@@ -124,7 +135,7 @@ class WebServer {
             res.end(JSON.stringify({ error: { code: ErrorCodes.INVALID_JSON, message: 'Request body is not valid JSON' } }));
             return;
           }
-          log.error('Unhandled error in request handler', { error: msg, requestId });
+          log.error('Unhandled error in request handler', { error: msg, requestId: req.id });
           res.writeHead(500, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify({ error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' } }));
         });
@@ -177,6 +188,7 @@ class WebServer {
     // Body (POST/PUT/PATCH only)
     if (method === 'POST' || method === 'PUT' || method === 'PATCH') {
       const rawBody = await readBody(req, maxBodySize);
+      req.rawBody = rawBody;
       if (rawBody.length > 0) {
         const contentType = req.headers['content-type'] ?? '';
         if (contentType.includes('application/json')) {

package/server/ws/realtime.js

@@ -22,16 +22,16 @@ function createRealtimeServer(options) {
   function buildCtx(reqInfo) {
     const requestLog = {
       debug(message, data) {
-        appContext.log.debug(message, { ...data, requestId: reqInfo.requestId });
+        appContext.log.debug(message, { ...data, requestId: reqInfo.id });
       },
       info(message, data) {
-        appContext.log.info(message, { ...data, requestId: reqInfo.requestId });
+        appContext.log.info(message, { ...data, requestId: reqInfo.id });
       },
       warn(message, data) {
-        appContext.log.warn(message, { ...data, requestId: reqInfo.requestId });
+        appContext.log.warn(message, { ...data, requestId: reqInfo.id });
       },
       error(message, data) {
-        appContext.log.error(message, { ...data, requestId: reqInfo.requestId });
+        appContext.log.error(message, { ...data, requestId: reqInfo.id });
       },
     };
     return buildContext({ ...appContext, log: requestLog }, { req: reqInfo });
@@ -70,7 +70,7 @@ function createRealtimeServer(options) {
       ...params,
     };
     return {
-      requestId: randomUUID(),
+      id: randomUUID(),
       method: wsMsg.method,
       path: wsMsg.path,
       query: mergedQuery,

package/server/ws/ws-router.js

@@ -270,7 +270,7 @@ class WsRouter {
 
   _buildRequestInfo(client, wsMsg, params) {
     return {
-      requestId: randomUUID(),
+      id: randomUUID(),
       method: wsMsg.method,
       path: wsMsg.path,
       query: { ...(wsMsg.query ?? {}), ...params },