Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.1 KB
Raw Blame
/**
 * Per-surface source-text loaders for structural guards (refactor wave 1, A10).
 *
 * A "surface" is one god file plus the modules it is being decomposed into.
 * Guards that read a surface's source must keep seeing their target after a
 * peel moves it, or they rot into permanently-green no-ops. Two loaders, two
 * guard classes (same split as doctor-source.ts, which now delegates here):
 *
 * - surfaceSource(surface): the whole surface, façade first, then every other
 *   listed file, then every file under the surface's new module dirs (sorted),
 *   joined with a file-boundary marker. For CONTAINMENT assertions only
 *   (toContain / not.toContain / toMatch with no ordering or cross-line span).
 * - surfaceFileSource(surface, rel): exactly one named file of the surface, for
 *   POSITIONAL assertions (indexOf ordering, slice windows, multi-line regex
 *   spans, line counts). Concatenation would let those match across files,
 *   which is weaker than the guard intends, so the caller names the file that
 *   holds the code; a file outside the surface throws.
 *
 * Today every surface except doctor resolves to its single current file (the
 * module dirs below do not exist yet), so re-pointing a guard here is a no-op.
 * A lane that moves code out of a façade adds the destination: a new dir is
 * globbed automatically; a module in an EXISTING dir or flat file set (e.g.
 * src/core/minions/handlers/, src/commands/serve-http-oauth.ts) must be added
 * to `files` explicitly in the same commit, because globbing an existing dir
 * would widen today's assertions instead of preserving them.
 */
import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
import { join, relative } from 'node:path';

const REPO_ROOT = join(import.meta.dir, '..', '..');

interface SurfaceDef {
  /** Repo-relative files, façade first. Missing files are skipped (planned modules). */
  files: string[];
  /** Repo-relative module dirs created by the decomposition; every .ts file below is included. */
  dirs: string[];
}

export const SOURCE_SURFACES = {
  sync: { files: ['src/commands/sync.ts'], dirs: ['src/commands/sync'] },
  cli: { files: ['src/cli.ts'], dirs: ['src/cli'] },
  'serve-http': {
    files: [
      'src/commands/serve-http.ts',
      'src/commands/serve-http-admin-api.ts',
      'src/commands/serve-http-mcp.ts',
      'src/commands/serve-http-spa.ts',
      'src/commands/serve-http-oauth.ts',
      'src/commands/serve-http-metrics.ts',
      'src/commands/serve-http-webhooks.ts',
    ],
    dirs: [],
  },
  jobs: {
    files: [
      'src/commands/jobs.ts',
      // W4 jobs: registerBuiltinHandlers' inline handler bodies, moved into an existing dir.
      'src/core/minions/handlers/autopilot-cycle.ts',
      'src/core/minions/handlers/autopilot-global-maintenance.ts',
      'src/core/minions/handlers/backlinks.ts',
      'src/core/minions/handlers/chronicle-extract.ts',
      'src/core/minions/handlers/cycle-phase.ts',
      'src/core/minions/handlers/embed-catch-up.ts',
      'src/core/minions/handlers/embed.ts',
      'src/core/minions/handlers/enrich.ts',
      'src/core/minions/handlers/extract-atoms-drain.ts',
      'src/core/minions/handlers/extract-conversation-facts.ts',
      'src/core/minions/handlers/extract-ner.ts',
      'src/core/minions/handlers/extract-takes-from-pages.ts',
      'src/core/minions/handlers/extract-timeline-from-meetings.ts',
      'src/core/minions/handlers/extract.ts',
      'src/core/minions/handlers/facts-absorb.ts',
      'src/core/minions/handlers/import.ts',
      'src/core/minions/handlers/integrity-auto.ts',
      'src/core/minions/handlers/integrity.ts',
      'src/core/minions/handlers/job-pull.ts',
      'src/core/minions/handlers/lint-fix.ts',
      'src/core/minions/handlers/lint.ts',
      'src/core/minions/handlers/loops-extract.ts',
      'src/core/minions/handlers/orphans.ts',
      'src/core/minions/handlers/purge.ts',
      'src/core/minions/handlers/reindex.ts',
      'src/core/minions/handlers/repair-jsonb.ts',
      'src/core/minions/handlers/sync-retry-failed.ts',
      'src/core/minions/handlers/sync.ts',
      'src/core/minions/handlers/unify-types.ts',
    ],
    dirs: ['src/commands/jobs'],
  },
  hybrid: { files: ['src/core/search/hybrid.ts'], dirs: ['src/core/search/hybrid'] },
  autopilot: {
    files: [
      'src/commands/autopilot.ts',
      // W4 autopilot: daemon modules peeled out of runAutopilot into the flat autopilot-*.ts set.
      'src/commands/autopilot-daemon.ts',
      'src/commands/autopilot-dispatch.ts',
      'src/commands/autopilot-probes.ts',
      // #6828: the self-upgrade swap's outcome handling, moved into core.
      'src/core/self-upgrade-swap.ts',
    ],
    dirs: ['src/commands/autopilot'],
  },
  migrate: { files: ['src/core/migrate.ts'], dirs: ['src/core/schema-migrations'] },
  'pglite-engine': { files: ['src/core/pglite-engine.ts'], dirs: ['src/core/engine-sql'] },
  'postgres-engine': { files: ['src/core/postgres-engine.ts', 'src/core/search/vector-statement.ts'], dirs: ['src/core/engine-sql'] },
  doctor: { files: ['src/commands/doctor.ts'], dirs: ['src/commands/doctor'] },
} satisfies Record<string, SurfaceDef>;

export type SourceSurface = keyof typeof SOURCE_SURFACES;

function listTs(dir: string): string[] {
  if (!existsSync(dir)) return [];
  const out: string[] = [];
  for (const entry of readdirSync(dir).sort()) {
    const full = join(dir, entry);
    if (statSync(full).isDirectory()) out.push(...listTs(full));
    else if (entry.endsWith('.ts')) out.push(full);
  }
  return out;
}

/** Absolute paths of every file on the surface: listed files in order, then sorted module-dir files. */
export function surfaceFiles(surface: SourceSurface): string[] {
  const def: SurfaceDef = SOURCE_SURFACES[surface];
  const listed = def.files.map((f) => join(REPO_ROOT, f)).filter((f) => existsSync(f));
  const seen = new Set(listed);
  const moduleFiles = def.dirs.flatMap((d) => listTs(join(REPO_ROOT, d))).filter((f) => !seen.has(f));
  return [...listed, ...moduleFiles];
}

/** A separator no plausible TS source contains, so cross-file matches are visible. */
export function surfaceFileBoundary(surface: SourceSurface): string {
  return `\n /* __${surface}-source-file-boundary__ */ \n`;
}

/** Concatenated surface for CONTAINMENT assertions. */
export function surfaceSource(surface: SourceSurface): string {
  return surfaceFiles(surface)
    // test-reads-source-ok[structural]: A10 containment loader; guards assert a construct exists somewhere on the surface.
    .map((f) => readFileSync(f, 'utf-8'))
    .join(surfaceFileBoundary(surface));
}

/**
 * One named file of the surface for POSITIONAL assertions.
 * @param rel repo-relative path, e.g. 'src/commands/sync.ts'
 */
export function surfaceFileSource(surface: SourceSurface, rel: string): string {
  const abs = join(REPO_ROOT, rel);
  if (!surfaceFiles(surface).includes(abs)) {
    const members = surfaceFiles(surface).map((f) => relative(REPO_ROOT, f));
    throw new Error(`surfaceFileSource: ${rel} is not on the ${surface} surface (${members.join(', ')})`);
  }
  // test-reads-source-ok[structural]: A10 positional loader; the caller names the single file that holds the code.
  return readFileSync(abs, 'utf-8');
}