arcway 0.1.0

package/server/mcp/debug-api.js

@@ -0,0 +1,137 @@
+import { toErrorMessage } from '../helpers.js';
+const DEBUG_PREFIX = '/_mcp';
+function isDebugRequest(url) {
+  return url.startsWith(DEBUG_PREFIX);
+}
+function createDebugHandler(runtime, deps, secret, logger) {
+  const { jobRunner, apiRouter, db, mode } = deps;
+  let port = deps.port ?? 0;
+
+  function numParam(params, key, fallback) {
+    return params.has(key) ? Number(params.get(key)) : fallback;
+  }
+  function strParam(params, key) {
+    return params.get(key) ?? void 0;
+  }
+
+  const routes = {
+    '/logs': (params, json) => {
+      const entries = logger.query({
+        level: strParam(params, 'level'),
+        logger: strParam(params, 'logger'),
+        since: strParam(params, 'since'),
+        limit: numParam(params, 'limit', 100),
+      });
+      json(200, { entries, total: entries.length });
+    },
+    '/errors': (params, json) => {
+      const entries = logger.errors(numParam(params, 'limit', 50), strParam(params, 'since'));
+      json(200, { entries, total: entries.length });
+    },
+    '/traces': (params, json) => {
+      const traces = logger.query({
+        message: 'request',
+        method: strParam(params, 'method'),
+        path: strParam(params, 'path'),
+        status: params.has('status') ? Number(params.get('status')) : void 0,
+        minDurationMs: params.has('minDurationMs') ? Number(params.get('minDurationMs')) : void 0,
+        since: strParam(params, 'since'),
+        limit: numParam(params, 'limit', 50),
+      });
+      json(200, { traces, total: traces.length });
+    },
+    '/traces/get': (params, json) => {
+      const id = params.get('id');
+      if (!id) {
+        json(400, { error: 'Missing id parameter' });
+        return;
+      }
+      const entries = logger.query({ requestId: id });
+      if (entries.length === 0) {
+        json(404, { error: 'Trace not found' });
+        return;
+      }
+      json(200, { requestId: id, entries });
+    },
+    '/events': (params, json) => {
+      const events = logger.query({
+        message: 'event',
+        eventName: strParam(params, 'eventName'),
+        since: strParam(params, 'since'),
+        limit: numParam(params, 'limit', 50),
+      });
+      json(200, { events, total: events.length });
+    },
+    '/jobs': (_params, json) => {
+      json(200, {
+        queueSize: jobRunner.dispatcher.size,
+        runnerActive: jobRunner.running,
+      });
+    },
+    '/queue': (_params, json) => {
+      json(200, { queueSize: jobRunner.dispatcher.size });
+    },
+    '/health': (_params, json) => {
+      json(200, {
+        status: 'running',
+        bootedAt: runtime.bootedAt,
+        uptime: Math.floor((Date.now() - new Date(runtime.bootedAt).getTime()) / 1e3),
+        port,
+        mode,
+        domains: [],
+        routes: apiRouter?.routes.length ?? 0,
+      });
+    },
+    '/schema': (params, json, res) => {
+      const format = params.get('format') ?? 'json';
+      db.introspectSchema()
+        .then((schema) => {
+          if (format === 'markdown') {
+            res.writeHead(200, { 'Content-Type': 'text/markdown' });
+            res.end(db.generateSchemaMarkdown(schema));
+          } else {
+            json(200, schema);
+          }
+        })
+        .catch((err) => {
+          json(500, { error: toErrorMessage(err) });
+        });
+    },
+  };
+
+  const handler = (req, res) => {
+    const url = req.url ?? '';
+    if (!url.startsWith(DEBUG_PREFIX)) return false;
+    const route = url.slice(DEBUG_PREFIX.length).split('?')[0];
+    const params = new URL(url, 'http://localhost').searchParams;
+    const json = (status, data) => {
+      res.writeHead(status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(data));
+    };
+    if (secret) {
+      const authHeader = req.headers['authorization'];
+      const bearerToken =
+        typeof authHeader === 'string' && authHeader.startsWith('Bearer ')
+          ? authHeader.slice(7)
+          : void 0;
+      const queryToken = params.get('token') ?? void 0;
+      const providedToken = bearerToken ?? queryToken;
+      if (providedToken !== secret) {
+        json(401, { error: 'Unauthorized \u2014 invalid or missing debug API token' });
+        return true;
+      }
+    }
+    const routeHandler = routes[route];
+    if (routeHandler) {
+      routeHandler(params, json, res);
+    } else {
+      json(404, { error: `Unknown debug route: ${route}` });
+    }
+    return true;
+  };
+  handler.setPort = (p) => {
+    port = p;
+  };
+  return handler;
+}
+export { createDebugHandler, isDebugRequest };

package/server/mcp/helpers.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const BUILD_DIR = '.build';
+const DEV_INFO_FILE = 'dev.json';
+async function readDevInfo(rootDir) {
+  try {
+    const raw = await fs.readFile(path.join(rootDir, BUILD_DIR, DEV_INFO_FILE), 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function fetchDebug(port, endpoint, params) {
+  const url = new URL(`http://localhost:${port}/_mcp${endpoint}`);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0 && v !== '') url.searchParams.set(k, v);
+    }
+  }
+  const res = await fetch(url.toString());
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Debug API error (${res.status}): ${text}`);
+  }
+  return res.json();
+}
+function textResult(text) {
+  return { content: [{ type: 'text', text }] };
+}
+export { fetchDebug, readDevInfo, textResult };

package/server/mcp/index.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { createMcpRuntime } from './runtime.js';
+import { createDebugHandler, isDebugRequest } from './debug-api.js';
+import { startMcpServer } from './server.js';
+
+const DEBUG_PREFIX = '/_mcp';
+
+class McpRouter {
+  _config;
+  _log;
+  _runtime;
+  _handler = null;
+
+  constructor(config, { log } = {}) {
+    this._config = config;
+    this._log = log;
+    this._runtime = config.enabled !== false ? createMcpRuntime() : null;
+  }
+
+  get enabled() {
+    return this._runtime !== null;
+  }
+
+  get bootedAt() {
+    return this._runtime?.bootedAt;
+  }
+
+  get runtime() {
+    return this._runtime;
+  }
+
+  init({ jobRunner, apiRouter, db, mode } = {}) {
+    if (!this._runtime) return;
+    this._handler = createDebugHandler(
+      this._runtime,
+      { jobRunner, apiRouter, db, mode },
+      this._config.secret,
+      this._log,
+    );
+    this._log.info('MCP debug API enabled at /_mcp/*');
+  }
+
+  async handle(req, res) {
+    if (!this._handler) return false;
+    const url = req.url ?? '';
+    if (!url.startsWith(DEBUG_PREFIX)) return false;
+    return this._handler(req, res);
+  }
+
+  setPort(port) {
+    if (this._handler) this._handler.setPort(port);
+  }
+
+  async writeDevMetadata(rootDir, port) {
+    if (!this._runtime) return;
+    this.setPort(port);
+    const buildDir = path.join(rootDir, '.build');
+    try {
+      const { mkdir, writeFile } = await import('node:fs/promises');
+      await mkdir(buildDir, { recursive: true });
+      await writeFile(
+        path.join(buildDir, 'dev.json'),
+        JSON.stringify({ port, pid: process.pid, bootedAt: this._runtime.bootedAt }),
+      );
+    } catch {}
+  }
+
+  async cleanup(rootDir) {
+    if (!this._runtime) return;
+    try {
+      const { unlink } = await import('node:fs/promises');
+      await unlink(path.join(rootDir, '.build', 'dev.json'));
+    } catch {}
+  }
+}
+
+export { McpRouter, createDebugHandler, createMcpRuntime, isDebugRequest, startMcpServer };

package/server/mcp/runtime.js

@@ -0,0 +1,7 @@
+function createMcpRuntime() {
+  return {
+    bootedAt: new Date().toISOString(),
+  };
+}
+
+export { createMcpRuntime };

package/server/mcp/server.js

@@ -0,0 +1,19 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerIntrospectionTools } from './tools/introspection.js';
+import { registerDebuggingTools } from './tools/debugging.js';
+async function startMcpServer(rootDir) {
+  const server = new McpServer(
+    { name: 'arcway-mcp', version: '1.0.0' },
+    {
+      capabilities: { tools: {} },
+      instructions:
+        'Arcway framework MCP server. Provides debugging, logging, and project introspection tools for AI coding agents.',
+    },
+  );
+  registerIntrospectionTools(server, rootDir);
+  registerDebuggingTools(server, rootDir);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+export { startMcpServer };

package/server/mcp/tools/debugging.js

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import { readDevInfo, fetchDebug, textResult } from '../helpers.js';
+import { toErrorMessage } from '../../helpers.js';
+
+const NOT_RUNNING = 'Dev server is not running. Start it with `arcway dev`.';
+
+function registerDebugTool(server, rootDir, name, meta, endpoint, mapArgs) {
+  server.registerTool(
+    name,
+    { ...meta, annotations: { readOnlyHint: true } },
+    async (args) => {
+      try {
+        const devInfo = await readDevInfo(rootDir);
+        if (!devInfo) return textResult(NOT_RUNNING);
+        const params = mapArgs ? mapArgs(args) : {};
+        const data = await fetchDebug(devInfo.port, endpoint, params);
+        return textResult(JSON.stringify(data, null, 2));
+      } catch (err) {
+        return textResult(`Error: ${toErrorMessage(err)}`);
+      }
+    },
+  );
+}
+
+function registerDebuggingTools(server, rootDir) {
+  registerDebugTool(server, rootDir, 'arcway_logs', {
+    title: 'Query Logs',
+    description:
+      'Query recent log entries from the running dev server. Filter by level (debug/info/warn/error), domain, and time range.',
+    inputSchema: {
+      level: z.enum(['debug', 'info', 'warn', 'error']).optional().describe('Filter by log level'),
+      domain: z.string().optional().describe('Filter by domain name'),
+      since: z.string().optional().describe('ISO timestamp to filter entries after'),
+      limit: z.number().optional().describe('Max entries to return (default: 100)'),
+    },
+  }, '/logs', (args) => {
+    const params = {};
+    if (args.level) params.level = args.level;
+    if (args.domain) params.logger = args.domain;
+    if (args.since) params.since = args.since;
+    if (args.limit) params.limit = String(args.limit);
+    return params;
+  });
+
+  registerDebugTool(server, rootDir, 'arcway_errors', {
+    title: 'Recent Errors',
+    description: 'Get recent error log entries from the running dev server.',
+    inputSchema: {
+      limit: z.number().optional().describe('Max errors to return (default: 50)'),
+      since: z.string().optional().describe('ISO timestamp to filter errors after'),
+    },
+  }, '/errors', (args) => {
+    const params = {};
+    if (args.limit) params.limit = String(args.limit);
+    if (args.since) params.since = args.since;
+    return params;
+  });
+
+  // Request trace has special id-lookup logic
+  server.registerTool(
+    'arcway_request_trace',
+    {
+      title: 'Request Traces',
+      description:
+        'Query recent HTTP request traces. When given an id, returns all correlated log entries for that request across every subsystem.',
+      inputSchema: {
+        id: z.string().optional().describe('Specific trace ID to look up'),
+        method: z.string().optional().describe('Filter by HTTP method (GET, POST, etc.)'),
+        path: z.string().optional().describe('Filter by path (substring match)'),
+        status: z.number().optional().describe('Filter by status code'),
+        minDurationMs: z.number().optional().describe('Filter by minimum duration'),
+        limit: z.number().optional().describe('Max traces to return (default: 50)'),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async (args) => {
+      try {
+        const devInfo = await readDevInfo(rootDir);
+        if (!devInfo) return textResult(NOT_RUNNING);
+        if (args.id) {
+          const data = await fetchDebug(devInfo.port, '/traces/get', { id: args.id });
+          return textResult(JSON.stringify(data, null, 2));
+        }
+        const params = {};
+        if (args.method) params.method = args.method;
+        if (args.path) params.path = args.path;
+        if (args.status) params.status = String(args.status);
+        if (args.minDurationMs) params.minDurationMs = String(args.minDurationMs);
+        if (args.limit) params.limit = String(args.limit);
+        const data = await fetchDebug(devInfo.port, '/traces', params);
+        return textResult(JSON.stringify(data, null, 2));
+      } catch (err) {
+        return textResult(`Error: ${toErrorMessage(err)}`);
+      }
+    },
+  );
+
+  registerDebugTool(server, rootDir, 'arcway_event_trace', {
+    title: 'Event Traces',
+    description:
+      'Query recent event emission traces. Shows which listeners fired (immediate + async), their results/errors, and timing for each event.',
+    inputSchema: {
+      eventName: z.string().optional().describe('Filter by event name (substring match)'),
+      domain: z.string().optional().describe('Filter by emitter domain'),
+      limit: z.number().optional().describe('Max traces to return (default: 50)'),
+      since: z.string().optional().describe('ISO timestamp to filter after'),
+    },
+  }, '/events', (args) => {
+    const params = {};
+    if (args.eventName) params.eventName = args.eventName;
+    if (args.domain) params.domain = args.domain;
+    if (args.limit) params.limit = String(args.limit);
+    if (args.since) params.since = args.since;
+    return params;
+  });
+
+  registerDebugTool(server, rootDir, 'arcway_job_status', {
+    title: 'Job Status',
+    description: 'Get the status of the job queue and runner from the running dev server.',
+  }, '/jobs');
+
+  registerDebugTool(server, rootDir, 'arcway_queue_inspect', {
+    title: 'Queue Inspect',
+    description: 'Inspect domain queues from the running dev server.',
+  }, '/queue');
+
+  registerDebugTool(server, rootDir, 'arcway_health', {
+    title: 'Server Health',
+    description:
+      'Get dev server health status: uptime, port, mode, domain count, route count, log/trace buffer sizes.',
+  }, '/health');
+}
+export { registerDebuggingTools };

package/server/mcp/tools/introspection.js

@@ -0,0 +1,87 @@
+import path from 'node:path';
+import { z } from 'zod';
+import { makeConfig } from '#server/config/loader.js';
+import { discoverRoutes } from '#server/router/routes.js';
+import { createDB } from '#server/db/index.js';
+import { loadEnvFiles } from '#server/env.js';
+import { textResult } from '../helpers.js';
+function registerIntrospectionTools(server, rootDir) {
+  server.registerTool(
+    'arcway_project_overview',
+    {
+      title: 'Project Overview',
+      description:
+        'Returns the full project topology: all routes (with methods, patterns, schemas), config overview. This is the single most useful tool for understanding an Arcway project.',
+      annotations: { readOnlyHint: true },
+    },
+    async () => {
+      try {
+        const config = await makeConfig(rootDir);
+        const routes = await discoverRoutes(config.api.dir);
+        const routeSummaries = routes.map((r) => ({
+          method: r.method,
+          pattern: r.pattern,
+          hasSchema: !!(r.config.schema?.query || r.config.schema?.body),
+          hasResponseSchema: !!r.config.schema?.response,
+          meta: r.config.meta,
+        }));
+        const overview = {
+          config: {
+            database: config.database.client,
+            server: {
+              port: config.server?.port ?? 3e3,
+              host: config.server?.host ?? '0.0.0.0',
+            },
+            hasSession: !!config.session,
+            hasRedis: !!(config.cache?.driver === 'redis' || config.events?.driver === 'redis'),
+            mcp: config.mcp,
+          },
+          routes: routeSummaries,
+          totals: {
+            routes: routeSummaries.length,
+          },
+        };
+        return textResult(JSON.stringify(overview, null, 2));
+      } catch (err) {
+        return textResult(`Error: ${err.message}`);
+      }
+    },
+  );
+  server.registerTool(
+    'arcway_db_schema',
+    {
+      title: 'Database Schema',
+      description:
+        'Introspect the database schema: column types, nullability, defaults, and foreign key references. Returns structured data or markdown.',
+      inputSchema: {
+        format: z
+          .enum(['json', 'markdown'])
+          .optional()
+          .describe('Output format: json (default) or markdown.'),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    async ({ format }) => {
+      try {
+        loadEnvFiles(rootDir, 'development');
+        const config = await makeConfig(rootDir);
+        const db = await createDB(config.database);
+        try {
+          await db.runMigrations();
+          const schema = await db.introspectSchema();
+          await db.destroy();
+          if (format === 'markdown') {
+            return textResult(db.generateSchemaMarkdown(schema));
+          }
+          return textResult(JSON.stringify(schema, null, 2));
+        } catch (err) {
+          await db.destroy();
+          throw err;
+        }
+      } catch (err) {
+        return textResult(`Error: ${err.message}`);
+      }
+    },
+  );
+}
+export { registerIntrospectionTools };

package/server/middlewares/cors.js

@@ -0,0 +1,30 @@
+function corsMiddleware(options) {
+  const methods = options.methods ?? ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+  const allowedHeaders = options.allowedHeaders ?? ['Content-Type', 'Authorization'];
+  const maxAge = options.maxAge ?? 86400;
+  return (ctx) => {
+    const requestOrigin = ctx.req.headers['origin'];
+    if (!requestOrigin) return;
+    let allowOrigin;
+    if (options.origin === '*') {
+      allowOrigin = options.credentials ? requestOrigin : '*';
+    } else {
+      const origins = Array.isArray(options.origin) ? options.origin : [options.origin];
+      if (origins.includes(requestOrigin)) {
+        allowOrigin = requestOrigin;
+      }
+    }
+    if (!allowOrigin) return;
+    ctx.req.headers['access-control-allow-origin'] = allowOrigin;
+    ctx.req.headers['access-control-allow-methods'] = methods.join(', ');
+    ctx.req.headers['access-control-allow-headers'] = allowedHeaders.join(', ');
+    if (options.credentials) {
+      ctx.req.headers['access-control-allow-credentials'] = 'true';
+    }
+    if (options.exposedHeaders?.length) {
+      ctx.req.headers['access-control-expose-headers'] = options.exposedHeaders.join(', ');
+    }
+    ctx.req.headers['access-control-max-age'] = String(maxAge);
+  };
+}
+export { corsMiddleware };

package/server/middlewares/index.js

@@ -0,0 +1,3 @@
+import { requireSession } from './require-session.js';
+import { corsMiddleware } from './cors.js';
+export { corsMiddleware, requireSession };

package/server/middlewares/require-session.js

@@ -0,0 +1,15 @@
+function requireSession(options) {
+  const sessionKey = options?.sessionKey ?? 'userId';
+  const errorCode = options?.errorCode ?? 'UNAUTHORIZED';
+  const message = options?.message ?? 'Authentication required';
+  const status = options?.status ?? 401;
+  return (ctx) => {
+    if (!ctx.req.session || !ctx.req.session[sessionKey]) {
+      return {
+        status,
+        error: { code: errorCode, message },
+      };
+    }
+  };
+}
+export { requireSession };

package/server/module-loader.js

@@ -0,0 +1,9 @@
+import { pathToFileURL } from 'node:url';
+
+let importCounter = 0;
+async function loadModule(filePath) {
+  const cacheBuster = `?v=${++importCounter}`;
+  return import(pathToFileURL(filePath).href + cacheBuster);
+}
+
+export { loadModule };