Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

12.8 KB
Raw Blame
/**
 * The mounted HTTP route graph, derived from source at first use.
 *
 * Express routers are the runtime source of truth, but Express 5 deliberately
 * hides a nested router's mount path inside a matcher closure. Introspecting
 * private router internals would lose paths such as `/api/brain/songbook/*`
 * and couple PortOS to an undocumented Express representation. This scanner
 * follows the checked-in source graph instead:
 *
 *   server/index.js app.use('/api/...', router)
 *     -> route module imports
 *     -> router.use('/optional-prefix', childRouter)
 *     -> router.get/post/put/patch/delete(...)
 *
 * PortOS route paths are string literals by convention, so the scan is
 * deterministic, and it reads exactly the route modules the server is running,
 * so it cannot be stale. `getApiRouteCatalog()` runs it once per process, the
 * way `socketEventInventory.js` derives the Socket.IO inventory; why it is not
 * a committed manifest is in `server/AGENTS.md` ("Generated manifests").
 *
 * `scanRouteGraph()` also returns every declaration's content key
 * (`routeDeclarationKey`) so `apiRouteGraph.test.js` can prove the walk reaches
 * every declaration under `server/routes/` by comparing two in-memory scans,
 * and each operation's `declarations` (module, router id, local path) so the
 * host-control guard can find the handler a mounted route runs. The catalog
 * omits `declarations`.
 */

import { readFileSync, statSync } from 'node:fs';
import { dirname, extname, join, relative, resolve } from 'node:path';
import { resolveCodeRootForModule } from './dataRoot.js';
import { toModuleKey } from './staticImportGraph.js';

const DEFAULT_REPO_ROOT = resolveCodeRootForModule(import.meta.url);

const INDEX_RELATIVE_PATH = 'server/index.js';
const DERIVED_FROM = Object.freeze(['server/index.js', 'server/routes/**/*.js', 'server/lib/aiToolkit/routes/*.js']);
const ROUTE_METHODS = Object.freeze(['delete', 'get', 'head', 'options', 'patch', 'post', 'put']);
const ROUTE_METHOD_SET = new Set([...ROUTE_METHODS, 'all']);

const DEFAULT_IMPORT_RE = /\bimport\s+([A-Za-z_$][\w$]*)(?:\s*,\s*\{[^}]*\})?\s+from\s*(['"])(\.{1,2}\/[^'"\n]+)\2\s*;?/g;
// `[^}]*` rather than a lazy `[\s\S]*?`: the lazy form can run from a bare
// package import (`import { Router } from 'express'`) into the next relative
// import and swallow that statement's first binding.
const NAMED_IMPORT_RE = /\bimport\s*(?:[A-Za-z_$][\w$]*\s*,\s*)?\{([^}]*)\}\s*from\s*(['"])(\.{1,2}\/[^'"\n]+)\2\s*;?/g;
const ROUTER_DECL_RE = /\b(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:express\.)?Router\s*\(/g;
const DEFAULT_EXPORT_RE = /\bexport\s+default\s+([A-Za-z_$][\w$]*)\s*;?/;
const ROUTE_DECL_RE = /\b([A-Za-z_$][\w$]*)\.(get|post|put|patch|delete|head|options|all)\(\s*(['"])([^'"\n]*)\3/g;
const ROUTER_USE_RE = /\b([A-Za-z_$][\w$]*)\.use\(\s*(?:(['"])([^'"\n]*)\2\s*,\s*)?([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\)/g;
const APP_MOUNT_RE = /\bapp\.use\(\s*(['"])(\/(?:api|sdapi)[^'"\n]*)\1\s*,\s*([A-Za-z_$][\w$]*)(?:\s*\([^;]*?\))?\s*\)/g;
const COMPOSED_ROUTER_RE = /^([A-Za-z_$][\w$]*)\.routes\.([A-Za-z_$][\w$]*)$/;
const RETURN_COMPOSED_ROUTER_RE = /\breturn\s+([A-Za-z_$][\w$]*\.routes\.[A-Za-z_$][\w$]*)\s*;/;

const isFile = (path) => statSync(path, { throwIfNoEntry: false })?.isFile() === true;

const isDirectory = (path) => statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;

const resolveLocalModule = (fromFile, specifier) => {
  const candidate = resolve(dirname(fromFile), specifier);
  if (extname(candidate) && isFile(candidate)) return candidate;
  if (isFile(`${candidate}.js`)) return `${candidate}.js`;
  if (isDirectory(candidate) && isFile(join(candidate, 'index.js'))) return join(candidate, 'index.js');
  return null;
};

const importedName = (fragment) => {
  const normalized = fragment.trim().replace(/^type\s+/, '');
  if (!normalized) return null;
  const match = normalized.match(/^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
  return match ? { imported: match[1], local: match[2] || match[1] } : null;
};

const parseImports = (source, filePath) => {
  const imports = new Map();
  for (const match of source.matchAll(DEFAULT_IMPORT_RE)) {
    const resolved = resolveLocalModule(filePath, match[3]);
    if (resolved) imports.set(match[1], { file: resolved, imported: 'default' });
  }
  for (const match of source.matchAll(NAMED_IMPORT_RE)) {
    const resolved = resolveLocalModule(filePath, match[3]);
    if (!resolved) continue;
    for (const fragment of match[1].split(',')) {
      const name = importedName(fragment);
      if (name) imports.set(name.local, { file: resolved, imported: name.imported });
    }
  }
  return imports;
};

/**
 * Content identity for one `router.<method>('<path>')` call, stable across
 * the two scans the coverage guard compares.
 *
 * Two declarations collide when the same file registers the same method and
 * path on the same router *name* — normally a duplicate registration rather
 * than two distinct bindings. The exception is shadowing: a module-level
 * `const router = Router()` and a second one inside a factory share the id
 * `router`, so distinct bindings could collide and silently undercount. That
 * is why `scanRouteGraph` reports `duplicateDeclarationKeys` instead of just
 * folding them into a Set — see the collision assertion in the test.
 */
export const routeDeclarationKey = ({ source, routerId, method, path }) =>
  `${source}#${routerId} ${method.toUpperCase()} ${path || '/'}`;

const resolveComposedRouter = (expression, repoRoot) => {
  const routeName = expression.match(COMPOSED_ROUTER_RE)?.[2];
  if (!routeName) return null;
  const file = join(repoRoot, 'server', 'lib', 'aiToolkit', 'routes', `${routeName}.js`);
  return isFile(file) ? { file, imported: 'factory-router' } : null;
};

export function parseRouteModule(filePath, repoRoot = DEFAULT_REPO_ROOT) {
  const source = readFileSync(filePath, 'utf8');
  const moduleKey = toModuleKey(relative(repoRoot, filePath));
  const routerIds = new Set([...source.matchAll(ROUTER_DECL_RE)].map((match) => match[1]));
  const imports = parseImports(source, filePath);
  const defaultExport = source.match(DEFAULT_EXPORT_RE)?.[1] || null;
  const rootChild = resolveComposedRouter(source.match(RETURN_COMPOSED_ROUTER_RE)?.[1] || '', repoRoot);
  const routes = [];
  const mounts = [];

  for (const match of source.matchAll(ROUTE_DECL_RE)) {
    if (!routerIds.has(match[1]) || !ROUTE_METHOD_SET.has(match[2])) continue;
    const methods = match[2] === 'all' ? ROUTE_METHODS : [match[2]];
    for (const method of methods) {
      routes.push({ routerId: match[1], method, path: match[4], source: moduleKey });
    }
  }

  for (const match of source.matchAll(ROUTER_USE_RE)) {
    if (!routerIds.has(match[1])) continue;
    const childId = match[4];
    const child = imports.get(childId) || resolveComposedRouter(childId, repoRoot);
    if (!routerIds.has(childId) && !child) continue;
    mounts.push({
      routerId: match[1],
      prefix: match[3] || '',
      childId,
      child,
    });
  }

  const rootRouterId = defaultExport && routerIds.has(defaultExport)
    ? defaultExport
    : routerIds.has('router') ? 'router' : [...routerIds][0] || null;

  return { filePath, source, routerIds, imports, defaultExport, rootRouterId, rootChild, routes, mounts };
}

const joinRoutePath = (...parts) => {
  const joined = parts
    .filter((part) => typeof part === 'string' && part.length > 0)
    .map((part) => part.replace(/^\/+|\/+$/g, ''))
    .filter(Boolean)
    .join('/');
  return `/${joined}`.replace(/\/{2,}/g, '/');
};

const parseTopLevelMounts = ({ source, filePath }) => {
  const imports = parseImports(source, filePath);
  const mounts = [];
  for (const match of source.matchAll(APP_MOUNT_RE)) {
    const imported = imports.get(match[3]);
    if (!imported) continue;
    mounts.push({ mountPath: match[2], filePath: imported.file });
  }
  return mounts;
};

/**
 * Walk the mounted route graph and return everything the scan learned,
 * including the `declarationKeys` that never reach the catalog —
 * `buildApiRouteCatalog` narrows this to the serializable subset.
 */
export function scanRouteGraph({ repoRoot = DEFAULT_REPO_ROOT, indexSource } = {}) {
  const indexPath = join(repoRoot, INDEX_RELATIVE_PATH);
  const source = indexSource ?? readFileSync(indexPath, 'utf8');
  const topLevelMounts = parseTopLevelMounts({ source, filePath: indexPath });
  const moduleCache = new Map();
  const operations = new Map();
  const declarationKeys = new Set();

  const readModule = (filePath) => {
    if (!moduleCache.has(filePath)) moduleCache.set(filePath, parseRouteModule(filePath, repoRoot));
    return moduleCache.get(filePath);
  };

  const record = ({ method, path, mountPath, declaration }) => {
    const key = `${method.toUpperCase()} ${path}`;
    declarationKeys.add(routeDeclarationKey(declaration));
    const existing = operations.get(key) || {
      method: method.toUpperCase(),
      path,
      mountPath,
      sources: [],
      declarations: [],
    };
    existing.sources.push(declaration.source);
    existing.declarations.push(declaration);
    operations.set(key, existing);
  };

  const walkRouter = ({ filePath, routerId, prefix, mountPath, ancestry }) => {
    const cycleKey = `${filePath}#${routerId}`;
    if (ancestry.has(cycleKey)) return;
    const nextAncestry = new Set(ancestry).add(cycleKey);
    const parsed = readModule(filePath);
    if (!routerId) {
      if (parsed.rootChild) {
        const childModule = readModule(parsed.rootChild.file);
        walkRouter({
          filePath: parsed.rootChild.file,
          routerId: childModule.rootRouterId,
          prefix,
          mountPath,
          ancestry: nextAncestry,
        });
      }
      return;
    }

    for (const route of parsed.routes.filter((entry) => entry.routerId === routerId)) {
      record({
        method: route.method,
        path: joinRoutePath(prefix, route.path),
        mountPath,
        declaration: route,
      });
    }

    for (const mount of parsed.mounts.filter((entry) => entry.routerId === routerId)) {
      if (mount.child) {
        const childModule = readModule(mount.child.file);
        walkRouter({
          filePath: mount.child.file,
          routerId: childModule.rootRouterId,
          prefix: joinRoutePath(prefix, mount.prefix),
          mountPath,
          ancestry: nextAncestry,
        });
      } else {
        walkRouter({
          filePath,
          routerId: mount.childId,
          prefix: joinRoutePath(prefix, mount.prefix),
          mountPath,
          ancestry: nextAncestry,
        });
      }
    }
  };

  for (const mount of topLevelMounts) {
    const parsed = readModule(mount.filePath);
    walkRouter({
      filePath: mount.filePath,
      routerId: parsed.rootRouterId,
      prefix: mount.mountPath,
      mountPath: mount.mountPath,
      ancestry: new Set(),
    });
  }

  const routes = [...operations.values()]
    .map((operation) => ({
      ...operation,
      sources: [...new Set(operation.sources)].sort(),
      declarations: [...new Map(operation.declarations.map((d) => [routeDeclarationKey(d), d])).values()],
    }))
    .sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));

  // Collisions are counted PER MODULE, from the parsed declarations rather than
  // from `record`: one router mounted at two prefixes reaches `record` twice
  // with the same declaration, which is the same binding seen twice, not two
  // bindings sharing a key. Within a single file, a repeated key is the real
  // thing — a duplicate registration, or two shadowed routers sharing a name.
  const duplicateDeclarationKeys = [...moduleCache.values()].flatMap((module) => {
    const seen = new Set();
    return module.routes
      .map((declaration) => routeDeclarationKey(declaration))
      .filter((key) => {
        if (seen.has(key)) return true;
        seen.add(key);
        return false;
      });
  }).sort();

  return {
    mounts: [...new Set(topLevelMounts.map((mount) => mount.mountPath))].sort(),
    routes,
    declarationKeys,
    duplicateDeclarationKeys,
    sourceFileCount: moduleCache.size,
  };
}

/** The serializable route inventory: `{ derivedFrom, mounts, routes, stats }`. */
export function buildApiRouteCatalog(options = {}) {
  const { mounts, routes, declarationKeys, sourceFileCount } = scanRouteGraph(options);
  return {
    derivedFrom: DERIVED_FROM,
    mounts,
    routes: routes.map(({ declarations: _declarations, ...route }) => route),
    stats: {
      mounts: mounts.length,
      operations: routes.length,
      declarations: declarationKeys.size,
      sourceFiles: sourceFileCount,
    },
  };
}

// Once per process, on the first request that needs it: route modules cannot
// change under a running server without a restart, and deferring the ~50 ms
// scan past import keeps it off every suite that merely reaches this module.
let cachedCatalog = null;
export const getApiRouteCatalog = () => (cachedCatalog ??= buildApiRouteCatalog());