arcway 0.1.0

package/server/bin/commands/schema.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { makeConfig } from '#server/config/loader.js';
+import { loadEnvFiles } from '#server/env.js';
+import { createDB } from '#server/db/index.js';
+async function runSchema(outFile) {
+  const rootDir = process.cwd();
+  const mode = process.env.NODE_ENV === 'production' ? 'production' : 'development';
+  loadEnvFiles(rootDir, mode);
+  try {
+    const config = await makeConfig(rootDir);
+    const db = await createDB(config.database);
+    await db.runMigrations();
+    console.log('Introspecting database schema...');
+    const schema = await db.introspectSchema();
+    if (schema.tables.length === 0) {
+      console.log('No tables found.');
+      await db.destroy();
+      return;
+    }
+    const markdown = db.generateSchemaMarkdown(schema);
+    const outputPath = path.resolve(rootDir, outFile);
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await fs.writeFile(outputPath, markdown, 'utf-8');
+    console.log(`  Tables: ${schema.tables.length}`);
+    console.log(`
+Schema written to ${path.relative(rootDir, outputPath)}`);
+    await db.destroy();
+  } catch (err) {
+    console.error('Schema generation failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+function register(program) {
+  program
+    .command('schema')
+    .description('Generate database schema documentation from introspected tables')
+    .argument('[outFile]', 'output file path', 'docs/schema.md')
+    .action(runSchema);
+}
+export default register;

package/server/bin/commands/seed.js

@@ -0,0 +1,36 @@
+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';
+import { runSeeds } from '#server/db/seeds.js';
+async function runSeed() {
+  const rootDir = process.cwd();
+  const mode = process.env.NODE_ENV === 'production' ? 'production' : 'development';
+  loadEnvFiles(rootDir, mode);
+  try {
+    const config = await makeConfig(rootDir);
+    const db = await createDB(config.database);
+    await db.runMigrations();
+    const seedsDir = path.join(rootDir, 'seeds');
+    const results = await runSeeds(db, seedsDir);
+    if (results.length === 0) {
+      console.log('No seed files found.');
+      await db.destroy();
+      return;
+    }
+    console.log(`\nRunning ${results.length} seed file(s)...`);
+    for (const result of results) {
+      const icon = result.status === 'completed' ? '+' : 'x';
+      console.log(`  [${icon}] ${result.name}`);
+    }
+    console.log('\nSeeding complete.');
+    await db.destroy();
+  } catch (err) {
+    console.error('Seed failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+function register(program) {
+  program.command('seed').description('Run database seed files').action(runSeed);
+}
+export default register;

package/server/bin/commands/start.js

@@ -0,0 +1,31 @@
+import boot from '#server/boot.js';
+
+async function startServer(mode) {
+  if (mode === 'production') {
+    process.env.NODE_ENV = 'production';
+  }
+
+  const app = await boot({ mode, rootDir: process.cwd() });
+  app.logger.info('Arcway framework ready', { mode, port: app.port });
+
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    app.logger.info(`Received ${signal}, shutting down...`);
+    await app.shutdown();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+
+  return app;
+}
+
+function register(program) {
+  program.command('start').description('Start production server').action(() => startServer('production'));
+}
+
+export { startServer };
+export default register;

package/server/bin/commands/test.js

@@ -0,0 +1,20 @@
+import { execFileSync } from 'node:child_process';
+function runTest(args) {
+  try {
+    execFileSync('npx', ['vitest', 'run', ...args], {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+    });
+  } catch {
+    process.exit(1);
+  }
+}
+function register(program) {
+  program
+    .command('test')
+    .description('Run domain tests via vitest')
+    .allowUnknownOption()
+    .argument('[args...]', 'additional arguments passed to vitest')
+    .action(runTest);
+}
+export default register;

package/server/bin/solo.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { createProgram } from './cli.js';
+const program = createProgram();
+program.parse(process.argv);

package/server/boot/index.js

@@ -0,0 +1,150 @@
+import { makeConfig } from '../config/loader.js';
+import { createDB } from '../db/index.js';
+import Redis from '../redis/index.js';
+import Events from '../events/index.js';
+import { EventHandler } from '../events/handler.js';
+import { JobRunner } from '../jobs/runner.js';
+import Logger from '../logger/index.js';
+import { loadEnvFiles } from '../env.js';
+import { McpRouter } from '../mcp/index.js';
+import Queue from '../queue/index.js';
+import Cache from '../cache/index.js';
+import Files from '../files/index.js';
+import { Mail } from '../mail/index.js';
+import WebServer from '../web-server.js';
+import { FileWatcher } from '../filewatcher/index.js';
+import { ApiRouter } from '../router/api-router.js';
+import { PagesRouter } from '../pages/pages-router.js';
+import { SystemRouter } from '../system-routes/index.js';
+import { StaticRouter } from '../static/index.js';
+import { WsRouter } from '../ws/ws-router.js';
+import path from 'node:path';
+
+async function boot(options) {
+  const rootDir = options.rootDir ?? process.cwd();
+  const mode = options.mode;
+
+  const envFiles = loadEnvFiles(rootDir, mode);
+  const config = await makeConfig(rootDir, { overrides: options.configOverrides, mode });
+
+  const log = new Logger(config.logger);
+  const mcpRouter = new McpRouter(config.mcp, { log });
+
+  if (envFiles.length > 0) log.info('Env files loaded', { envFiles });
+
+  const db = await createDB(config.database, { log });
+  await db.runMigrations();
+
+  const redis = new Redis(config.redis, { log });
+  await redis.connect();
+
+  const queue = new Queue(config.queue, { db, redis, log });
+  await queue.init();
+
+  const cache = new Cache(config.cache, { redis, log });
+  await cache.init();
+
+  const files = new Files(config.files, { log });
+  await files.init();
+
+  const mail = new Mail(config.mail, { db, log, queue });
+
+  const events = new Events(config.events, { redis, log });
+
+  const eventHandler = new EventHandler(config.events, {
+    events,
+    log,
+    appContext: { db, events, queue, cache, files, mail, log },
+  });
+  await eventHandler.init();
+
+  const jobRunner = new JobRunner(config.jobs, { db, queue, cache, files, mail, events, log });
+  await jobRunner.init();
+
+  const fileWatcher = new FileWatcher(rootDir, { log });
+  await fileWatcher.start();
+
+  const appContext = { db, redis, events, queue, cache, files, mail, log, fileWatcher };
+
+  // ── Routers ──
+
+  const apiRouter = new ApiRouter(config.api, {
+    log,
+    fileWatcher,
+    appContext,
+    sessionConfig: config.session,
+  });
+  await apiRouter.init();
+
+  const pagesRouter = new PagesRouter(config, { rootDir, log, fileWatcher, appContext });
+  await pagesRouter.init();
+
+  const healthDeps = {
+    db,
+    redisClients: [{ name: 'redis', client: redis?.client }],
+  };
+  const systemRouter = new SystemRouter({ healthDeps });
+
+  const staticRouter = new StaticRouter({
+    outDir: config.pages?.outDir ?? path.resolve(rootDir, '.build/pages'),
+    publicDir: path.join(rootDir, 'public'),
+  });
+
+  const wsRouter = new WsRouter(config.websocket, {
+    apiRouter,
+    log,
+    sessionConfig: config.session,
+  });
+
+  const webServer = new WebServer(config, { log });
+
+  // Register handlers in priority order
+  mcpRouter.init({ jobRunner, apiRouter, db, mode });
+  webServer.use(mcpRouter, '/_mcp');
+  webServer.use(systemRouter, '/_system');
+  webServer.use(apiRouter, apiRouter.prefix);
+  webServer.use(wsRouter, config.websocket.path);
+  webServer.use(staticRouter);
+  webServer.use(pagesRouter);
+
+  await webServer.listen();
+
+  wsRouter.attachToServer(webServer.server);
+
+  jobRunner.start();
+
+  const shutdown = async () => {
+    await jobRunner.shutdown();
+    await pagesRouter.close();
+    await apiRouter.close();
+    await webServer.close();
+    await fileWatcher.close();
+    await events.disconnect();
+    await redis.disconnect();
+    await db.destroy();
+    await mcpRouter.cleanup(rootDir);
+  };
+
+  const app = {
+    config,
+    db,
+    webServer,
+    apiRouter,
+    events,
+    jobRunner,
+    server: webServer.server,
+    port: webServer.port,
+    mode,
+    logger: log,
+    mcpRuntime: mcpRouter.runtime,
+    fileWatcher,
+    systemRouter,
+    shutdown,
+  };
+
+  await mcpRouter.writeDevMetadata(rootDir, webServer.port);
+
+  return app;
+}
+
+export default boot;

package/server/boot.js

@@ -0,0 +1,2 @@
+import boot from './boot/index.js';
+export default boot;

package/server/build.js

@@ -0,0 +1,23 @@
+import { makeConfig } from './config/loader.js';
+import { buildPages } from './pages/build.js';
+
+async function build(options) {
+  const rootDir = options?.rootDir ?? process.cwd();
+  const config = await makeConfig(rootDir).catch(() => null);
+  const buildTarget = config?.build?.target ?? 'node22';
+
+  let pages;
+  const pagesEnabled = config?.pages?.enabled !== false;
+  if (pagesEnabled) {
+    pages = await buildPages({
+      rootDir,
+      serverTarget: buildTarget,
+      minify: true,
+      fonts: config?.pages?.fonts,
+    });
+  }
+
+  return { pages };
+}
+
+export { build };

package/server/cache/drivers/memory.js

@@ -0,0 +1,23 @@
+import { createCache } from 'cache-manager';
+class MemoryCacheDriver {
+  cache;
+  constructor() {
+    this.cache = createCache();
+  }
+  async init() {}
+
+  _key(namespace, key) {
+    return `${namespace}:${key}`;
+  }
+  async get(namespace, key) {
+    const val = await this.cache.get(this._key(namespace, key));
+    return val ?? null;
+  }
+  async set(namespace, key, value, ttlMs) {
+    await this.cache.set(this._key(namespace, key), value, ttlMs);
+  }
+  async delete(namespace, key) {
+    await this.cache.del(this._key(namespace, key));
+  }
+}
+export default MemoryCacheDriver;

package/server/cache/drivers/redis.js

@@ -0,0 +1,28 @@
+class RedisCacheDriver {
+  client;
+  prefix;
+  constructor(client, keyPrefix = 'arcway:') {
+    this.client = client;
+    this.prefix = `${keyPrefix}cache:`;
+  }
+  async init() {}
+
+  _key(namespace, key) {
+    return `${this.prefix}${namespace}:${key}`;
+  }
+  async get(namespace, key) {
+    return this.client.get(this._key(namespace, key));
+  }
+  async set(namespace, key, value, ttlMs) {
+    const redisKey = this._key(namespace, key);
+    if (ttlMs && ttlMs > 0) {
+      await this.client.set(redisKey, value, 'PX', ttlMs);
+    } else {
+      await this.client.set(redisKey, value);
+    }
+  }
+  async delete(namespace, key) {
+    await this.client.del(this._key(namespace, key));
+  }
+}
+export default RedisCacheDriver;

package/server/cache/index.js

@@ -0,0 +1,69 @@
+import MemoryCacheDriver from './drivers/memory.js';
+import RedisCacheDriver from './drivers/redis.js';
+
+class Cache {
+  _driver;
+  _log;
+  _namespace;
+
+  constructor(config, { redis, log } = {}) {
+    this._log = log;
+    this._namespace = config?.namespace ?? '';
+
+    if (config?.driver === 'redis') {
+      this._driver = new RedisCacheDriver(redis.client, redis.keyPrefix);
+      log?.info('Cache driver: redis');
+    } else {
+      this._driver = new MemoryCacheDriver();
+      log?.info('Cache driver: memory');
+    }
+  }
+
+  async init() {
+    await this._driver.init();
+  }
+
+  async get(key) {
+    const raw = await this._driver.get(this._namespace, key);
+    if (raw === null) return null;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      this._log?.warn('Cache get: corrupt JSON, returning null', { key });
+      return null;
+    }
+  }
+
+  async set(key, value, ttlMs) {
+    await this._driver.set(this._namespace, key, JSON.stringify(value), ttlMs);
+  }
+
+  async delete(key) {
+    await this._driver.delete(this._namespace, key);
+  }
+
+  async wrap(key, fn, ttlMs) {
+    const raw = await this._driver.get(this._namespace, key);
+    if (raw !== null) {
+      try {
+        return JSON.parse(raw);
+      } catch {
+        this._log?.warn('Cache wrap: corrupt JSON, recomputing', { key });
+      }
+    }
+    const value = await fn();
+    await this._driver.set(this._namespace, key, JSON.stringify(value), ttlMs);
+    return value;
+  }
+
+  /** Return a namespaced child that shares the same driver. */
+  withNamespace(namespace) {
+    const child = Object.create(Cache.prototype);
+    child._driver = this._driver;
+    child._log = this._log;
+    child._namespace = namespace;
+    return child;
+  }
+}
+
+export default Cache;

package/server/config/loader.js

@@ -0,0 +1,89 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { loadModule } from '../module-loader.js';
+import resolveServer from './modules/server.js';
+import resolveApi from './modules/api.js';
+import resolveDatabase from './modules/database.js';
+import resolveLogger from './modules/logger.js';
+import resolveJobs from './modules/jobs.js';
+import resolveQueue from './modules/queue.js';
+import resolveFiles from './modules/files.js';
+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 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';
+
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      typeof result[key] === 'object' &&
+      result[key] !== null
+    ) {
+      result[key] = deepMerge(result[key], value);
+    } else if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+const modules = [
+  resolveServer,
+  resolveApi,
+  resolveDatabase,
+  resolveLogger,
+  resolveJobs,
+  resolveQueue,
+  resolveCache,
+  resolveEvents,
+  resolveFiles,
+  resolveMail,
+  resolveRedis,
+  resolveSession,
+  resolvePages,
+  resolveBuild,
+  resolveMcp,
+  resolveWebsocket,
+];
+
+async function makeConfig(rootDir, { overrides, mode } = {}) {
+  const configPath = path.join(rootDir, 'arcway.config.js');
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`No arcway.config.js found in ${rootDir}`);
+  }
+
+  let module;
+  try {
+    module = await loadModule(configPath, import.meta.url);
+  } catch (err) {
+    throw new Error(`Failed to load arcway config at ${configPath}: ${err}`);
+  }
+
+  const raw = module.default;
+  if (!raw) {
+    throw new Error(`Arcway config at ${configPath} must have a default export`);
+  }
+  if (!raw.database) {
+    throw new Error('Arcway config must include a "database" configuration');
+  }
+
+  const merged = overrides ? deepMerge(raw, overrides) : raw;
+  const opts = { rootDir, mode };
+  let resolved = merged;
+  for (const resolve of modules) {
+    resolved = resolve(resolved, opts);
+  }
+
+  return resolved;
+}
+
+export { makeConfig };

package/server/config/modules/api.js

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

package/server/config/modules/build.js

@@ -0,0 +1,9 @@
+const DEFAULTS = {
+  target: 'node22',
+};
+
+function resolve(config) {
+  return { ...config, build: { ...DEFAULTS, ...config.build } };
+}
+
+export default resolve;

package/server/config/modules/cache.js

@@ -0,0 +1,10 @@
+const DEFAULTS = {
+  driver: 'memory',
+};
+
+function resolve(config) {
+  if (!config.cache) return config;
+  return { ...config, cache: { ...DEFAULTS, ...config.cache } };
+}
+
+export default resolve;

package/server/config/modules/database.js

@@ -0,0 +1,29 @@
+import path from 'node:path';
+
+const DEFAULTS = {
+  sqliteFilename: '.build/db/arcway.db',
+  migrationsDir: 'migrations',
+};
+
+const CLIENT_MAP = {
+  sqlite: 'better-sqlite3',
+  postgres: 'pg',
+  mysql: 'mysql2',
+};
+
+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);
+  }
+  const isSqlite = db.client === 'better-sqlite3' || db.client === 'sqlite3';
+  if (isSqlite && !db.connection) {
+    const filename = db.sqliteFilename;
+    db.connection = { filename: path.resolve(rootDir, filename) };
+  }
+  return { ...config, database: db };
+}
+
+export default resolve;

package/server/config/modules/events.js

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

package/server/config/modules/files.js

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

package/server/config/modules/jobs.js

@@ -0,0 +1,20 @@
+import path from 'node:path';
+
+const DEFAULTS = {
+  enabled: true,
+  backoffMs: 1000,
+  pollIntervalMs: 60000,
+  tableName: 'arcway_jobs',
+  leaseTable: 'arcway_job_leases',
+  jobsDir: 'jobs',
+};
+
+function resolve(config, { rootDir } = {}) {
+  const jobs = { ...DEFAULTS, ...config.jobs };
+  if (jobs.jobsDir && !path.isAbsolute(jobs.jobsDir)) {
+    jobs.jobsDir = path.resolve(rootDir, jobs.jobsDir);
+  }
+  return { ...config, jobs };
+}
+
+export default resolve;

package/server/config/modules/logger.js

@@ -0,0 +1,9 @@
+const DEFAULTS = {
+  level: 'info',
+};
+
+function resolve(config) {
+  return { ...config, logger: { ...DEFAULTS, ...config.logger } };
+}
+
+export default resolve;

package/server/config/modules/mail.js

@@ -0,0 +1,11 @@
+const DEFAULTS = {
+  driver: 'console',
+  enabled: true,
+};
+
+function resolve(config) {
+  if (!config.mail) return config;
+  return { ...config, mail: { ...DEFAULTS, ...config.mail } };
+}
+
+export default resolve;

package/server/config/modules/mcp.js

@@ -0,0 +1,9 @@
+const DEFAULTS = {
+  enabled: true,
+};
+
+function resolve(config) {
+  return { ...config, mcp: { ...DEFAULTS, ...config.mcp } };
+}
+
+export default resolve;