arcway 0.1.0

package/server/env.js

@@ -0,0 +1,17 @@
+import path from 'node:path';
+import dotenv from 'dotenv';
+
+function loadEnvFiles(rootDir, mode) {
+  const files = ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`];
+  const loaded = [];
+  for (const file of files) {
+    const filePath = path.join(rootDir, file);
+    const result = dotenv.config({ path: filePath, quiet: true });
+    if (!result.error) {
+      loaded.push(file);
+    }
+  }
+  return loaded;
+}
+
+export { loadEnvFiles };

package/server/events/drivers/memory.js

@@ -0,0 +1,45 @@
+import { patternToRegex } from '../pattern.js';
+class MemoryTransport {
+  subscriptions = [];
+  /** Subscribe to events matching a pattern. */
+  subscribe(pattern, handler) {
+    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.
+   */
+  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(
+      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,
+        );
+      }
+    }
+    if (errors.length > 0 && errors.length === matching.length) {
+      throw new Error(`All ${errors.length} listener(s) for event "${eventName}" failed`);
+    }
+  }
+  async disconnect() {}
+
+  /** Get the number of registered subscriptions. */
+  get size() {
+    return this.subscriptions.length;
+  }
+}
+export default MemoryTransport;

package/server/events/drivers/redis.js

@@ -0,0 +1,64 @@
+import { patternToRegex } from '../pattern.js';
+class RedisTransport {
+  pub;
+  sub;
+  prefix;
+  subscriptions = [];
+  listening = false;
+  constructor(pub, sub, keyPrefix = 'arcway:') {
+    this.pub = pub;
+    this.sub = sub;
+    this.prefix = `${keyPrefix}events:`;
+  }
+  subscribe(pattern, handler) {
+    const regex = patternToRegex(pattern);
+    this.subscriptions.push({ pattern, regex, handler });
+    if (!this.listening) {
+      this.listening = true;
+      this.startListening();
+    }
+  }
+  async emit(eventName, payload) {
+    const channel = `${this.prefix}${eventName}`;
+    const message = JSON.stringify({ event: eventName, payload });
+    await this.pub.publish(channel, message);
+  }
+  startListening() {
+    const channelPattern = `${this.prefix}*`;
+    this.sub.psubscribe(channelPattern).catch((err) => {
+      console.error('[RedisTransport] Failed to psubscribe:', err);
+    });
+    this.sub.on('pmessage', (_pattern, _channel, message) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(message);
+      } catch {
+        console.warn('[RedisTransport] Malformed event message, skipping');
+        return;
+      }
+      const { event: eventName, payload } = parsed;
+      const matching = this.subscriptions.filter((sub) => sub.regex.test(eventName));
+      if (matching.length === 0) return;
+      Promise.allSettled(matching.map((sub) => sub.handler(eventName, payload))).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,
+            );
+          }
+        }
+      });
+    });
+  }
+  /** Disconnect both pub and sub clients. */
+  async disconnect() {
+    await this.sub.punsubscribe();
+    this.sub.disconnect();
+    this.pub.disconnect();
+  }
+  get size() {
+    return this.subscriptions.length;
+  }
+}
+export default RedisTransport;

package/server/events/handler.js

@@ -0,0 +1,67 @@
+import path from 'node:path';
+import { discoverModules } from '../discovery.js';
+import { buildContext } from '../context.js';
+
+function listenerPathToEvent(relativePath) {
+  return relativePath
+    .replace(/\\/g, '/')
+    .replace(/\.js$/, '')
+    .replace(/\[\.\.\.([^\]]+)\]/g, '*');
+}
+
+function validateListener(exported, filePath) {
+  if (!exported) throw new Error(`Listener file at ${filePath} must have a default export`);
+  if (typeof exported === 'function') return { handler: exported };
+  if (typeof exported === 'object' && typeof exported.handler === 'function') return exported;
+  throw new Error(
+    `Listener at ${filePath} must export a function or an object with a "handler" function`,
+  );
+}
+
+class EventHandler {
+  _events;
+  _listenersDir;
+  _log;
+  _appContext;
+  _listeners = [];
+
+  constructor(config, { events, log, appContext } = {}) {
+    this._listenersDir = config?.listenersDir;
+    this._events = events;
+    this._log = log;
+    this._appContext = appContext ?? {
+      db: null,
+      events,
+      log,
+      cache: null,
+      queue: null,
+      files: null,
+      mail: null,
+    };
+  }
+
+  async init() {
+    if (!this._listenersDir) return;
+    const entries = await discoverModules(this._listenersDir, {
+      recursive: true,
+      label: 'listener file',
+    });
+    for (const { filePath, relativePath, module } of entries) {
+      const { handler, event: explicitEvent } = validateListener(module.default, filePath);
+      const event = explicitEvent ?? listenerPathToEvent(relativePath);
+      if (event.startsWith('system/') || event === 'system') continue;
+      this._events.subscribe(event, (_eventName, payload) => {
+        const ctx = buildContext(this._appContext, { event: { name: _eventName, payload } });
+        handler(ctx);
+      });
+      this._listeners.push({ event, fileName: relativePath });
+      this._log?.info(`  ${relativePath} → ${event}`);
+    }
+  }
+
+  get listeners() {
+    return this._listeners;
+  }
+}
+
+export { EventHandler, listenerPathToEvent };

package/server/events/index.js

@@ -0,0 +1,35 @@
+import MemoryTransport from './drivers/memory.js';
+import RedisTransport from './drivers/redis.js';
+
+class Events {
+  _transport;
+  _log;
+
+  constructor(config, { redis, log } = {}) {
+    this._log = log;
+
+    if (config?.driver === 'redis') {
+      const pub = redis.createClient();
+      const sub = redis.createClient();
+      this._transport = new RedisTransport(pub, sub, redis.keyPrefix);
+      log?.info('Event transport: redis');
+    } else {
+      this._transport = new MemoryTransport();
+    }
+  }
+
+  subscribe(pattern, handler) {
+    this._transport.subscribe(pattern, handler);
+  }
+
+  async emit(eventName, payload) {
+    await this._transport.emit(eventName, payload);
+    this._log?.debug('event', { eventName, payload });
+  }
+
+  async disconnect() {
+    await this._transport.disconnect();
+  }
+}
+
+export default Events;

package/server/events/pattern.js

@@ -0,0 +1,5 @@
+function patternToRegex(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]+');
+  return new RegExp(`^${escaped}$`);
+}
+export { patternToRegex };

package/server/files/drivers/local.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+class LocalFileDriver {
+  constructor(storageDir) {
+    this.storageDir = storageDir;
+  }
+  async init() {
+    await fs.mkdir(this.storageDir, { recursive: true });
+  }
+  resolvePath(namespace, filePath) {
+    const namespaceDir = path.join(this.storageDir, namespace);
+    const resolved = path.resolve(namespaceDir, filePath);
+    if (!resolved.startsWith(namespaceDir + path.sep) && resolved !== namespaceDir) {
+      throw new Error(`Path traversal detected: "${filePath}" escapes namespace directory`);
+    }
+    return resolved;
+  }
+  async write(namespace, filePath, data) {
+    const resolved = this.resolvePath(namespace, filePath);
+    await fs.mkdir(path.dirname(resolved), { recursive: true });
+    await fs.writeFile(resolved, data);
+  }
+  async read(namespace, filePath) {
+    const resolved = this.resolvePath(namespace, filePath);
+    try {
+      return await fs.readFile(resolved);
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+  }
+  async delete(namespace, filePath) {
+    const resolved = this.resolvePath(namespace, filePath);
+    try {
+      await fs.unlink(resolved);
+    } catch (err) {
+      if (err.code === 'ENOENT') return;
+      throw err;
+    }
+  }
+  async list(namespace, prefix) {
+    const namespaceDir = path.join(this.storageDir, namespace);
+    let searchDir = namespaceDir;
+    if (prefix) {
+      const resolved = path.resolve(namespaceDir, prefix);
+      if (!resolved.startsWith(namespaceDir + path.sep) && resolved !== namespaceDir) {
+        throw new Error(`Path traversal detected: "${prefix}" escapes namespace directory`);
+      }
+      searchDir = resolved;
+    }
+    try {
+      const entries = await this.walkDir(searchDir);
+      return entries.map((entry) => path.relative(namespaceDir, entry).replace(/\\/g, '/'));
+    } catch (err) {
+      if (err.code === 'ENOENT') return [];
+      throw err;
+    }
+  }
+  async exists(namespace, filePath) {
+    const resolved = this.resolvePath(namespace, filePath);
+    try {
+      await fs.access(resolved);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async walkDir(dir) {
+    const results = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const nested = await this.walkDir(fullPath);
+        results.push(...nested);
+      } else {
+        results.push(fullPath);
+      }
+    }
+    return results;
+  }
+}
+export default LocalFileDriver;

package/server/files/drivers/s3.js

@@ -0,0 +1,113 @@
+import {
+  S3Client,
+  GetObjectCommand,
+  PutObjectCommand,
+  DeleteObjectCommand,
+  ListObjectsV2Command,
+  HeadObjectCommand,
+} from '@aws-sdk/client-s3';
+class S3FileDriver {
+  client;
+  bucket;
+  constructor(config) {
+    this.bucket = config.bucket;
+    this.client = new S3Client({
+      region: config.region ?? 'us-east-1',
+      ...(config.endpoint ? { endpoint: config.endpoint } : {}),
+      ...(config.forcePathStyle ? { forcePathStyle: true } : {}),
+    });
+  }
+  async init() {}
+
+  key(namespace, filePath) {
+    const decoded = decodeURIComponent(filePath);
+    if (decoded.includes('..') || decoded.startsWith('/')) {
+      throw new Error(`Path traversal detected: "${filePath}" escapes namespace directory`);
+    }
+    const normalized = decoded.replace(/\/+/g, '/');
+    return `${namespace}/${normalized}`;
+  }
+  async write(namespace, filePath, data) {
+    const body = typeof data === 'string' ? Buffer.from(data, 'utf-8') : data;
+    await this.client.send(
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: this.key(namespace, filePath),
+        Body: body,
+      }),
+    );
+  }
+  async read(namespace, filePath) {
+    try {
+      const response = await this.client.send(
+        new GetObjectCommand({
+          Bucket: this.bucket,
+          Key: this.key(namespace, filePath),
+        }),
+      );
+      if (!response.Body) return null;
+      const bytes = await response.Body.transformToByteArray();
+      return Buffer.from(bytes);
+    } catch (err) {
+      if (err.name === 'NoSuchKey' || err.$metadata?.httpStatusCode === 404) {
+        return null;
+      }
+      throw err;
+    }
+  }
+  async delete(namespace, filePath) {
+    await this.client.send(
+      new DeleteObjectCommand({
+        Bucket: this.bucket,
+        Key: this.key(namespace, filePath),
+      }),
+    );
+  }
+  async list(namespace, prefix) {
+    if (prefix) {
+      const decodedPrefix = decodeURIComponent(prefix);
+      if (decodedPrefix.includes('..') || decodedPrefix.startsWith('/')) {
+        throw new Error(`Path traversal detected: "${prefix}" escapes namespace directory`);
+      }
+    }
+    const s3Prefix = prefix ? `${namespace}/${prefix}` : `${namespace}/`;
+    const files = [];
+    let continuationToken;
+    do {
+      const response = await this.client.send(
+        new ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: s3Prefix,
+          ContinuationToken: continuationToken,
+        }),
+      );
+      if (response.Contents) {
+        for (const obj of response.Contents) {
+          if (obj.Key) {
+            const relative = obj.Key.slice(namespace.length + 1);
+            if (relative) files.push(relative);
+          }
+        }
+      }
+      continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+    } while (continuationToken);
+    return files;
+  }
+  async exists(namespace, filePath) {
+    try {
+      await this.client.send(
+        new HeadObjectCommand({
+          Bucket: this.bucket,
+          Key: this.key(namespace, filePath),
+        }),
+      );
+      return true;
+    } catch (err) {
+      if (err.name === 'NotFound' || err.$metadata?.httpStatusCode === 404) {
+        return false;
+      }
+      throw err;
+    }
+  }
+}
+export default S3FileDriver;

package/server/files/index.js

@@ -0,0 +1,57 @@
+import LocalFileDriver from './drivers/local.js';
+import S3FileDriver from './drivers/s3.js';
+
+class Files {
+  _driver;
+  _log;
+  _namespace;
+
+  constructor(config, { log } = {}) {
+    this._log = log;
+    this._namespace = config?.namespace ?? '';
+
+    if (config?.driver === 's3') {
+      if (!config.s3) throw new Error('files.s3 config is required when driver is "s3"');
+      this._driver = new S3FileDriver(config.s3);
+      log?.info(`File driver: s3 (bucket: ${config.s3.bucket})`);
+    } else {
+      this._driver = new LocalFileDriver(config.storageDir);
+      log?.info('File driver: local');
+    }
+  }
+
+  async init() {
+    await this._driver.init();
+  }
+
+  async write(filePath, data) {
+    await this._driver.write(this._namespace, filePath, data);
+  }
+
+  async read(filePath) {
+    return this._driver.read(this._namespace, filePath);
+  }
+
+  async delete(filePath) {
+    await this._driver.delete(this._namespace, filePath);
+  }
+
+  async list(prefix) {
+    return this._driver.list(this._namespace, prefix);
+  }
+
+  async exists(filePath) {
+    return this._driver.exists(this._namespace, filePath);
+  }
+
+  /** Return a namespaced child that shares the same driver. */
+  withNamespace(namespace) {
+    const child = Object.create(Files.prototype);
+    child._driver = this._driver;
+    child._log = this._log;
+    child._namespace = namespace;
+    return child;
+  }
+}
+
+export default Files;

package/server/filewatcher/index.js

@@ -0,0 +1,156 @@
+import path from 'node:path';
+import { watch } from 'chokidar';
+
+class FileWatcher {
+  _rootDir;
+  _log;
+  _ignored;
+  _watcher = null;
+  _subscribers = new Map();
+  _started = false;
+
+  constructor(rootDir, { log, ignored } = {}) {
+    this._rootDir = rootDir;
+    this._log = log;
+    this._ignored = ignored ?? [/(^|[/\\])\../, /node_modules/, /\.build/, /dist/];
+  }
+
+  /**
+   * Subscribe to file changes.
+   *
+   * @param {string} name - Unique subscriber name (e.g. 'routes', 'pages')
+   * @param {object} options
+   * @param {string[]} options.dirs - Directories to watch, relative to rootDir (e.g. ['api'])
+   *                                  If omitted, matches all watched files.
+   * @param {string[]} options.extensions - File extensions to match (e.g. ['.js', '.ts'])
+   *                                       If omitted, matches all extensions.
+   * @param {number}   options.debounceMs - Debounce window in ms (default: 200)
+   * @param {function} options.onChange - Called with array of { path, relativePath, event } objects.
+   *                                     event is 'add' | 'change' | 'unlink'.
+   */
+  subscribe(name, options) {
+    if (this._subscribers.has(name)) {
+      throw new Error(`FileWatcher: subscriber "${name}" already exists`);
+    }
+
+    const dirs = options.dirs
+      ? options.dirs.map((d) => path.resolve(this._rootDir, d))
+      : null;
+
+    const extensions = options.extensions ? new Set(options.extensions) : null;
+
+    const sub = {
+      name,
+      dirs,
+      extensions,
+      debounceMs: options.debounceMs ?? 200,
+      onChange: options.onChange,
+      // internal state
+      _timer: null,
+      _pending: [],
+      _running: false,
+      _queued: false,
+    };
+
+    this._subscribers.set(name, sub);
+    this._log?.info(`FileWatcher: subscribed "${name}"`);
+    return this;
+  }
+
+  unsubscribe(name) {
+    const sub = this._subscribers.get(name);
+    if (!sub) return this;
+    if (sub._timer) clearTimeout(sub._timer);
+    this._subscribers.delete(name);
+    this._log?.info(`FileWatcher: unsubscribed "${name}"`);
+    return this;
+  }
+
+  async start() {
+    if (this._started) return;
+    this._started = true;
+
+    this._watcher = watch(this._rootDir, {
+      ignoreInitial: true,
+      ignored: this._ignored,
+      depth: 10,
+    });
+
+    this._watcher.on('add', (filePath) => this._dispatch(filePath, 'add'));
+    this._watcher.on('change', (filePath) => this._dispatch(filePath, 'change'));
+    this._watcher.on('unlink', (filePath) => this._dispatch(filePath, 'unlink'));
+
+    this._log?.info('FileWatcher: started');
+  }
+
+  _dispatch(filePath, event) {
+    const normalized = path.resolve(filePath);
+    const ext = path.extname(normalized);
+    const relativePath = path.relative(this._rootDir, normalized);
+
+    for (const sub of this._subscribers.values()) {
+      if (!this._matches(sub, normalized, ext)) continue;
+
+      sub._pending.push({ path: normalized, relativePath, event });
+
+      if (sub._timer) clearTimeout(sub._timer);
+      sub._timer = setTimeout(() => {
+        sub._timer = null;
+        this._flush(sub);
+      }, sub.debounceMs);
+    }
+  }
+
+  _matches(sub, filePath, ext) {
+    if (sub.extensions && !sub.extensions.has(ext)) return false;
+    if (sub.dirs) {
+      const match = sub.dirs.some(
+        (dir) => filePath.startsWith(dir + path.sep) || filePath.startsWith(dir + '/'),
+      );
+      if (!match) return false;
+    }
+    return true;
+  }
+
+  async _flush(sub) {
+    const events = sub._pending.splice(0);
+    if (events.length === 0) return;
+
+    if (sub._running) {
+      // Re-queue — these events will be picked up after current run finishes
+      sub._pending.push(...events);
+      sub._queued = true;
+      return;
+    }
+
+    sub._running = true;
+    try {
+      await sub.onChange(events);
+    } catch (err) {
+      this._log?.error(`FileWatcher: "${sub.name}" onChange error`, { error: String(err) });
+    } finally {
+      sub._running = false;
+      if (sub._queued) {
+        sub._queued = false;
+        this._flush(sub);
+      }
+    }
+  }
+
+  async close() {
+    for (const sub of this._subscribers.values()) {
+      if (sub._timer) clearTimeout(sub._timer);
+    }
+    this._subscribers.clear();
+
+    if (this._watcher) {
+      await this._watcher.close();
+      this._watcher = null;
+    }
+
+    this._started = false;
+    this._log?.info('FileWatcher: closed');
+  }
+}
+
+export { FileWatcher };

package/server/glob.js

@@ -0,0 +1,6 @@
+import { glob as _glob } from 'glob';
+async function glob(pattern, options) {
+  const results = await _glob(pattern, { windowsPathsNoEscape: true, ...options });
+  return results.map((p) => p.replace(/\\/g, '/'));
+}
+export { glob };