arcway 0.1.0

package/server/config/modules/pages.js

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

package/server/config/modules/queue.js

@@ -0,0 +1,10 @@
+const DEFAULTS = {
+  tableName: 'arcway_queue',
+  lockCooldownMs: 5 * 60 * 1000,
+};
+
+function resolve(config) {
+  return { ...config, queue: { ...DEFAULTS, ...config.queue } };
+}
+
+export default resolve;

package/server/config/modules/redis.js

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

package/server/config/modules/server.js

@@ -0,0 +1,30 @@
+const DEFAULTS = {
+  host: '0.0.0.0',
+  port: 3000,
+  maxBodySize: 1024 * 1024,
+  shutdownTimeoutMs: 10000,
+};
+
+const DEFAULT_CORS = {
+  origin: '*',
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  allowedHeaders: ['Content-Type', 'Authorization'],
+  exposedHeaders: [],
+  credentials: false,
+  maxAge: 86400,
+};
+
+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 };
+}
+
+function resolve(config, { mode } = {}) {
+  const server = { ...DEFAULTS, ...config.server };
+  server.cors = resolveCors(server.cors, mode);
+  return { ...config, server };
+}
+
+export default resolve;

package/server/config/modules/session.js

@@ -0,0 +1,9 @@
+import { resolveSessionConfig } from '../../session/index.js';
+
+function resolve(config, { mode } = {}) {
+  if (!config.session) return config;
+  const session = resolveSessionConfig(config.session, mode);
+  return { ...config, session };
+}
+
+export default resolve;

package/server/config/modules/websocket.js

@@ -0,0 +1,11 @@
+const DEFAULTS = {
+  path: '/ws',
+  pingIntervalMs: 30000,
+};
+
+function resolve(config) {
+  const websocket = { ...DEFAULTS, ...config.websocket };
+  return { ...config, websocket };
+}
+
+export default resolve;

package/server/constants.js

@@ -0,0 +1,67 @@
+import Module from 'node:module';
+
+const REDIS_SCAN_COUNT = 100;
+const LEASE_HEARTBEAT_INTERVAL_MS = 1e4;
+const LEASE_EXPIRY_MS = 3e4;
+const SESSION_COOKIE_MAX_AGE_SKEW = 60;
+
+const NODE_BUILTINS = new Set(
+  Module.builtinModules.flatMap((m) => (m.startsWith('node:') ? [m] : [m, `node:${m}`])),
+);
+const SERVER_ONLY_PACKAGES = new Set([
+  'knex',
+  'better-sqlite3',
+  'pg',
+  'pg-native',
+  'pg-query-stream',
+  'tedious',
+  'mysql',
+  'mysql2',
+  'oracledb',
+  'sqlite3',
+  'pino',
+  'pino-pretty',
+  'ws',
+  'graphql-yoga',
+  'graphql-ws',
+  '@graphql-tools/schema',
+  '@graphql-tools/merge',
+  'ioredis',
+  'iron-session',
+  'bcryptjs',
+  'dotenv',
+  'chokidar',
+  'commander',
+  'glob',
+  'esbuild',
+  'postcss',
+  '@tailwindcss/postcss',
+  'tailwindcss',
+  '@tailwindcss/oxide',
+  'tsx',
+  'cache-manager',
+  'rate-limiter-flexible',
+  'cron-parser',
+  '@aws-sdk/client-s3',
+  '@modelcontextprotocol/sdk',
+  'dataloader',
+  'cookie',
+]);
+const ErrorCodes = {
+  BODY_TOO_LARGE: 'BODY_TOO_LARGE',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  NOT_FOUND: 'NOT_FOUND',
+  INVALID_JSON: 'INVALID_JSON',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  HANDLER_ERROR: 'HANDLER_ERROR',
+  RATE_LIMITED: 'RATE_LIMITED',
+};
+export {
+  ErrorCodes,
+  LEASE_EXPIRY_MS,
+  LEASE_HEARTBEAT_INTERVAL_MS,
+  NODE_BUILTINS,
+  REDIS_SCAN_COUNT,
+  SERVER_ONLY_PACKAGES,
+  SESSION_COOKIE_MAX_AGE_SKEW,
+};

package/server/context.js

@@ -0,0 +1,15 @@
+function buildContext(appContext, extras) {
+  const ctx = {
+    db: appContext.db,
+    log: appContext.log,
+    events: appContext.events,
+    cache: appContext.cache,
+    queue: appContext.queue,
+    files: appContext.files,
+    mail: appContext.mail,
+    ...extras,
+  };
+  return ctx;
+}
+
+export { buildContext };

package/server/db/index.js

@@ -0,0 +1,87 @@
+import fsSync from 'node:fs';
+import path from 'node:path';
+import knex from 'knex';
+import { discoverFiles } from '../discovery.js';
+import { loadModule } from '../module-loader.js';
+import { introspectSchema, generateSchemaMarkdown } from './schema/index.js';
+
+class MigrationSource {
+  constructor(directory) {
+    this.directory = directory;
+  }
+  async getMigrations() {
+    const files = await discoverFiles(this.directory, { skipUnderscore: false });
+    return files.map((f) => f.name);
+  }
+  getMigrationName(migration) {
+    return migration;
+  }
+  async getMigration(migration) {
+    const filePath = path.resolve(this.directory, migration);
+    return loadModule(filePath, import.meta.url);
+  }
+}
+
+async function createDB(config, { log } = {}) {
+  const client = config.client;
+  const isSqlite = client === 'better-sqlite3' || client === 'sqlite3';
+  const connection = config.connection;
+
+  if (isSqlite && connection?.filename) {
+    fsSync.mkdirSync(path.dirname(connection.filename), { recursive: true });
+  }
+
+  const db = knex({
+    client,
+    connection,
+    ...(isSqlite ? { useNullAsDefault: true } : {}),
+  });
+
+  try {
+    await db.raw('SELECT 1');
+    log?.info('Database connected');
+  } catch (err) {
+    await db.destroy();
+    throw new Error(`Database connection failed: ${err}`);
+  }
+
+  const origDestroy = db.destroy.bind(db);
+  Object.defineProperty(db, 'destroy', {
+    value: async () => {
+      await origDestroy();
+      log?.info('Database connection closed');
+    },
+    writable: true,
+    configurable: true,
+  });
+
+  db.runMigrations = async () => {
+    const migrationsDir = config.migrationsDir;
+    if (!migrationsDir) return;
+    const [batch, migrations] = await db.migrate.latest({
+      migrationSource: new MigrationSource(migrationsDir),
+    });
+    if (migrations.length > 0) {
+      log?.info(`Migrations (batch ${batch}): ${migrations.join(', ')}`);
+    } else {
+      log?.info('Migrations: up to date');
+    }
+  };
+
+  db.runRollback = async () => {
+    const migrationsDir = config.migrationsDir;
+    if (!migrationsDir) throw new Error('No migrationsDir configured');
+    const [batch, entries] = await db.migrate.rollback({
+      migrationSource: new MigrationSource(migrationsDir),
+    });
+    return { batch, log: entries };
+  };
+
+  db.introspectSchema = () => introspectSchema(db);
+
+  db.generateSchemaMarkdown = generateSchemaMarkdown;
+
+  return db;
+}
+
+export { createDB, MigrationSource };

package/server/db/schema/drivers/mysql.js

@@ -0,0 +1,28 @@
+const EXCLUDED = new Set(['knex_migrations', 'knex_migrations_lock']);
+
+export default {
+  clients: ['mysql2'],
+
+  async tables(db) {
+    const [rows] = await db.raw('SHOW TABLES');
+    const key = Object.keys(rows[0] || {})[0];
+    return rows.map((r) => r[key]).filter((n) => !EXCLUDED.has(n));
+  },
+
+  async foreignKeys(db, tableName) {
+    const [rows] = await db.raw(
+      `
+      SELECT
+        COLUMN_NAME AS \`from\`,
+        REFERENCED_TABLE_NAME AS \`table\`,
+        REFERENCED_COLUMN_NAME AS \`to\`
+      FROM information_schema.KEY_COLUMN_USAGE
+      WHERE TABLE_NAME = ?
+        AND TABLE_SCHEMA = DATABASE()
+        AND REFERENCED_TABLE_NAME IS NOT NULL
+    `,
+      [tableName],
+    );
+    return rows.map((r) => ({ from: r.from, table: r.table, column: r.to }));
+  },
+};

package/server/db/schema/drivers/pg.js

@@ -0,0 +1,34 @@
+const EXCLUDED = new Set(['knex_migrations', 'knex_migrations_lock']);
+
+export default {
+  clients: ['pg'],
+
+  async tables(db) {
+    const result = await db.raw(
+      "SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename",
+    );
+    return result.rows.map((r) => r.tablename).filter((n) => !EXCLUDED.has(n));
+  },
+
+  async foreignKeys(db, tableName) {
+    const result = await db.raw(
+      `
+      SELECT
+        kcu.column_name AS "from",
+        ccu.table_name AS "table",
+        ccu.column_name AS "to"
+      FROM information_schema.key_column_usage kcu
+      JOIN information_schema.referential_constraints rc
+        ON kcu.constraint_name = rc.constraint_name
+        AND kcu.constraint_schema = rc.constraint_schema
+      JOIN information_schema.constraint_column_usage ccu
+        ON rc.unique_constraint_name = ccu.constraint_name
+        AND rc.unique_constraint_schema = ccu.constraint_schema
+      WHERE kcu.table_name = ?
+        AND kcu.table_schema = 'public'
+    `,
+      [tableName],
+    );
+    return result.rows.map((r) => ({ from: r.from, table: r.table, column: r.to }));
+  },
+};

package/server/db/schema/drivers/sqlite.js

@@ -0,0 +1,22 @@
+const EXCLUDED = new Set(['knex_migrations', 'knex_migrations_lock', 'sqlite_sequence']);
+
+function assertSafeIdentifier(name) {
+  if (!/^[a-zA-Z_]\w*$/.test(name)) {
+    throw new Error(`Unsafe table name: ${JSON.stringify(name)}`);
+  }
+}
+
+export default {
+  clients: ['better-sqlite3', 'sqlite3'],
+
+  async tables(db) {
+    const rows = await db.raw("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name");
+    return rows.map((r) => r.name).filter((n) => !EXCLUDED.has(n) && !n.startsWith('_'));
+  },
+
+  async foreignKeys(db, tableName) {
+    assertSafeIdentifier(tableName);
+    const fks = await db.raw(`PRAGMA foreign_key_list('${tableName}')`);
+    return fks.map((fk) => ({ from: fk.from, table: fk.table, column: fk.to }));
+  },
+};

package/server/db/schema/index.js

@@ -0,0 +1,78 @@
+import sqlite from './drivers/sqlite.js';
+import pg from './drivers/pg.js';
+import mysql from './drivers/mysql.js';
+
+const drivers = [sqlite, pg, mysql];
+
+function getDriver(client) {
+  for (const driver of drivers) {
+    if (driver.clients.includes(client)) return driver;
+  }
+  return null;
+}
+
+// ── Introspection ──
+
+function formatType(type, maxLength) {
+  if (maxLength != null && maxLength !== '' && Number(maxLength) > 0) {
+    return `${type}(${maxLength})`;
+  }
+  return type;
+}
+
+async function introspectTable(db, tableName, driver) {
+  const columnInfo = await db(tableName).columnInfo();
+  const fks = driver ? await driver.foreignKeys(db, tableName) : [];
+  const fkMap = new Map(fks.map((fk) => [fk.from, { table: fk.table, column: fk.column }]));
+
+  return Object.entries(columnInfo).map(([name, info]) => {
+    const col = {
+      name,
+      type: formatType(info.type, info.maxLength),
+      nullable: info.nullable,
+      defaultValue: info.defaultValue != null ? String(info.defaultValue) : null,
+    };
+    const fk = fkMap.get(name);
+    if (fk) col.references = fk;
+    return col;
+  });
+}
+
+async function introspectSchema(db) {
+  const client = db.client?.config?.client;
+  const driver = getDriver(client);
+  const tableNames = driver ? await driver.tables(db) : [];
+  const tables = [];
+  for (const tableName of tableNames) {
+    const columns = await introspectTable(db, tableName, driver);
+    tables.push({ name: tableName, columns });
+  }
+  tables.sort((a, b) => a.name.localeCompare(b.name));
+  return { tables };
+}
+
+// ── Markdown generation ──
+
+function generateSchemaMarkdown(schema) {
+  const lines = [];
+  lines.push('# Database Schema');
+  lines.push('');
+  lines.push('> Auto-generated by `arcway schema`. Do not edit manually.');
+  lines.push('');
+  for (const table of schema.tables) {
+    lines.push(`## ${table.name}`);
+    lines.push('');
+    lines.push('| Column | Type | Nullable | Default | References |');
+    lines.push('|--------|------|----------|---------|------------|');
+    for (const col of table.columns) {
+      const nullable = col.nullable ? 'yes' : 'no';
+      const defaultVal = col.defaultValue ?? '';
+      const ref = col.references ? `${col.references.table}.${col.references.column}` : '';
+      lines.push(`| ${col.name} | ${col.type} | ${nullable} | ${defaultVal} | ${ref} |`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export { generateSchemaMarkdown, introspectSchema };

package/server/db/seeds.js

@@ -0,0 +1,22 @@
+import { discoverModules } from '../discovery.js';
+
+async function runSeeds(db, seedsDir) {
+  const entries = await discoverModules(seedsDir, { label: 'seed file' });
+  const results = [];
+  for (const { name, filePath, module } of entries) {
+    const seedFn = module.default;
+    if (typeof seedFn !== 'function') {
+      throw new Error(`Seed file "${name}" must export a default function`);
+    }
+    try {
+      await seedFn(db);
+      results.push({ name, status: 'completed' });
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      throw new Error(`Seed "${name}" failed: ${error.message}`);
+    }
+  }
+  return results;
+}
+
+export { runSeeds };

package/server/discovery.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from './glob.js';
+import { loadModule } from './module-loader.js';
+
+/**
+ * Discover files in a directory, optionally recursing into subdirectories.
+ * Skips files starting with underscore by default.
+ * Returns sorted array of { name, filePath, relativePath }.
+ */
+async function discoverFiles(dir, { recursive = false, extensions = ['.js'], skipUnderscore = true, filter } = {}) {
+  if (!dir) return [];
+
+  let files;
+  if (recursive) {
+    const extGlob = extensions.length === 1 ? `*${extensions[0]}` : `*{${extensions.join(',')}}`;
+    files = await glob(path.join(dir, '**', extGlob));
+  } else {
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch (err) {
+      if (err.code === 'ENOENT') return [];
+      throw err;
+    }
+    const extSet = new Set(extensions);
+    files = entries
+      .filter((name) => extSet.has(path.extname(name)))
+      .map((name) => path.join(dir, name));
+  }
+
+  const results = [];
+  for (const filePath of files) {
+    const name = path.basename(filePath);
+    if (skipUnderscore && name.startsWith('_')) continue;
+    if (filter && !filter(name)) continue;
+    results.push({
+      name,
+      filePath,
+      relativePath: path.relative(dir, filePath),
+    });
+  }
+  results.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+  return results;
+}
+
+/**
+ * Discover and load modules from a directory.
+ * Returns sorted array of { name, filePath, relativePath, module }.
+ * Throws with a descriptive message if any file fails to import.
+ */
+async function discoverModules(dir, { recursive = false, extensions = ['.js'], skipUnderscore = true, filter, label = 'file' } = {}) {
+  const files = await discoverFiles(dir, { recursive, extensions, skipUnderscore, filter });
+  const results = [];
+  for (const entry of files) {
+    let module;
+    try {
+      module = await loadModule(entry.filePath, import.meta.url);
+    } catch (err) {
+      throw new Error(`Failed to load ${label} at ${entry.filePath}: ${err}`);
+    }
+    results.push({ ...entry, module });
+  }
+  return results;
+}
+
+export { discoverFiles, discoverModules };

package/server/docs/openapi.js

@@ -0,0 +1,153 @@
+function typeToOpenAPISchema(schema) {
+  const jsonSchema = schema.toJsonSchema();
+  const { $schema: _$schema, ...rest } = jsonSchema;
+  return rest;
+}
+function toOpenAPIPath(pattern) {
+  return pattern.replace(/:([^/]+)/g, '{$1}');
+}
+function buildPathParameters(route) {
+  const params = [];
+  for (const name of route.paramNames) {
+    const param = {
+      name,
+      in: 'path',
+      required: true,
+      schema: { type: 'string' },
+    };
+    if (route.config.schema?.query) {
+      try {
+        const fullSchema = typeToOpenAPISchema(route.config.schema.query);
+        if (fullSchema.properties && typeof fullSchema.properties === 'object') {
+          const fieldSchema = fullSchema.properties[name];
+          if (fieldSchema) {
+            param.schema = fieldSchema;
+          }
+        }
+      } catch {}
+    }
+    params.push(param);
+  }
+  return params;
+}
+function buildQueryParameters(route) {
+  if (!route.config.schema?.query) return [];
+  try {
+    const schema = typeToOpenAPISchema(route.config.schema.query);
+    if (!schema.properties || typeof schema.properties !== 'object') return [];
+    const required = new Set(schema.required ?? []);
+    const params = [];
+    for (const [name, fieldSchema] of Object.entries(schema.properties)) {
+      params.push({
+        name,
+        in: 'query',
+        required: required.has(name),
+        schema: fieldSchema,
+      });
+    }
+    return params;
+  } catch {
+    return [];
+  }
+}
+function generateOpenAPISpec(routes, info) {
+  const spec = {
+    openapi: '3.0.3',
+    info: {
+      title: info?.title ?? 'Arcway API',
+      version: info?.version ?? '1.0.0',
+      ...(info?.description ? { description: info.description } : {}),
+    },
+    paths: {},
+  };
+  for (const route of routes) {
+    const openApiPath = toOpenAPIPath(route.pattern);
+    const method = route.method.toLowerCase();
+    if (!spec.paths[openApiPath]) {
+      spec.paths[openApiPath] = {};
+    }
+    const operation = {
+      operationId: `${method}_${openApiPath
+        .replace(/[{}\/]/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '')}`,
+    };
+    const meta = route.config.meta;
+    if (meta?.summary) operation.summary = meta.summary;
+    if (meta?.description) operation.description = meta.description;
+    if (meta?.tags && meta.tags.length > 0) {
+      operation.tags = meta.tags;
+    } else {
+      const firstSegment = route.pattern.split('/')[1] || 'default';
+      operation.tags = [firstSegment];
+    }
+    const parameters = [...buildPathParameters(route), ...buildQueryParameters(route)];
+    if (parameters.length > 0) {
+      operation.parameters = parameters;
+    }
+    if (route.config.schema?.body) {
+      try {
+        const bodySchema = typeToOpenAPISchema(route.config.schema.body);
+        operation.requestBody = {
+          required: true,
+          content: {
+            'application/json': {
+              schema: bodySchema,
+            },
+          },
+        };
+      } catch {}
+    }
+    const responseSchema = route.config.schema?.response
+      ? (() => {
+          try {
+            return typeToOpenAPISchema(route.config.schema.response);
+          } catch {
+            return void 0;
+          }
+        })()
+      : void 0;
+    operation.responses = {
+      200: {
+        description: 'Successful response',
+        content: {
+          'application/json': {
+            schema: responseSchema ?? {
+              type: 'object',
+              properties: {
+                data: {},
+              },
+            },
+          },
+        },
+      },
+      ...(route.config.schema?.body || route.config.schema?.query
+        ? {
+            400: {
+              description: 'Validation error',
+              content: {
+                'application/json': {
+                  schema: {
+                    type: 'object',
+                    properties: {
+                      error: {
+                        type: 'object',
+                        properties: {
+                          code: { type: 'string' },
+                          message: { type: 'string' },
+                          details: {},
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          }
+        : {}),
+    };
+    spec.paths[openApiPath][method] = operation;
+  }
+  return spec;
+}
+export { generateOpenAPISpec, toOpenAPIPath, typeToOpenAPISchema };