Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.8 KB
Raw Blame
#!/usr/bin/env bun
/**
 * Windows hidden-console guard (#4992; docs/ci-guards.md#windows-hidden-console-guard).
 *
 * On Windows a detached gbrain child has no console, so every console program
 * it launches without `windowsHide` opens a visible console window that takes
 * focus. src/core/spawn.ts is the one module that launches subprocesses and
 * defaults `windowsHide: true`. Outside it, this guard fails on any runtime
 * use of `child_process` in src/ (a static, dynamic or `require` import that
 * is not type-only) and on any `Bun.spawn` / `Bun.spawnSync` reference, so a
 * NEW spawn site, detached or not, cannot skip the default. It is a RATCHET:
 * NOT_YET_MIGRATED lists the files that still launch directly today, each
 * with its reason; a listed file that no longer does fails as stale, so the
 * list only shrinks. It also fails on an explicit `windowsHide: false` outside
 * ALLOWLIST, which names each deliberate opt-out; a stale entry fails.
 *
 * Fix: import the launcher from src/core/spawn.ts (`spawn`, `spawnSync`,
 * `exec`, `execSync`, `execFile`, `execFileSync`, `bunSpawn`, `bunSpawnSync`)
 * and delete the file's NOT_YET_MIGRATED entry if it has one.
 *
 * Contributed by @rokas-tarasevicius (PR #6105); the ratchet form is wave 14's.
 * Seam: GBRAIN_GUARD_ROOT (fixture tree root).
 */
import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
import { join, relative } from 'node:path';
import ts from 'typescript';

const ROOT = process.env.GBRAIN_GUARD_ROOT ?? join(import.meta.dir, '..');
const ANCHOR = 'docs/ci-guards.md#windows-hidden-console-guard';
const SEAM = 'src/core/spawn.ts';
const MODULES = new Set(['child_process', 'node:child_process']);

/** Files allowed an explicit `windowsHide: false`. Each entry names its reason; a stale entry fails. */
const ALLOWLIST: Record<string, string> = {
  'src/core/creds/redirect.ts': 'openBrowser launches the system browser through `cmd /c start`; the launch stays as visible as before',
};

/**
 * Files that still import child_process or call Bun.spawn* directly. Delete
 * a file's entry when you move it onto the seam; an entry whose file no
 * longer launches directly fails as stale (the ratchet only goes down).
 */
const NOT_YET_MIGRATED: Record<string, string> = {
  'src/commands/bootstrap.ts': 'not yet migrated: open PR #6283, #6319 edits this file',
  'src/commands/setup.ts': 'not yet migrated: open PR #6406 edits this file',
  'src/commands/takes.ts': 'not yet migrated: open PR #6505 edits this file',
  'src/core/harness/install.ts': 'not yet migrated: open PR #6319, #6406 edits this file',
  'src/core/persistence/engine-graduation.ts': 'not yet migrated: persistence write path, migrated with its owning work (GBRA-101)',
  'src/core/persistence/sync-blobs.ts': 'not yet migrated: persistence write path, migrated with its owning work (GBRA-101)',
  'src/core/persistence/sync-discovery.ts': 'not yet migrated: persistence write path, migrated with its owning work (GBRA-101)',
  'src/core/persistence/topology-filesystem.ts': 'not yet migrated: persistence write path, migrated with its owning work (GBRA-101)',
};

function tsFiles(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(...tsFiles(full));
    else if (/\.(ts|tsx|mts)$/.test(entry) && !entry.endsWith('.d.ts')) out.push(full);
  }
  return out;
}

const isModule = (node: ts.Node | undefined): boolean => !!node && ts.isStringLiteralLike(node) && MODULES.has(node.text);

/** An import that loads child_process at runtime (not `import type`, not all-`type` specifiers). */
function valueImport(node: ts.ImportDeclaration | ts.ExportDeclaration): boolean {
  if (ts.isImportDeclaration(node)) {
    const clause = node.importClause;
    if (!clause) return true;
    if (clause.isTypeOnly) return false;
    if (clause.name) return true;
    const bindings = clause.namedBindings;
    return !bindings || ts.isNamespaceImport(bindings) || bindings.elements.length === 0 || bindings.elements.some(e => !e.isTypeOnly);
  }
  if (node.isTypeOnly) return false;
  const clause = node.exportClause;
  return !clause || !ts.isNamedExports(clause) || clause.elements.some(e => !e.isTypeOnly);
}

const violations: string[] = [];
const optedOut = new Set<string>();
const launchesDirectly = new Set<string>();
for (const abs of tsFiles(join(ROOT, 'src'))) {
  const rel = relative(ROOT, abs).replace(/\\/g, '/');
  if (rel === SEAM) continue;
  const sf = ts.createSourceFile(abs, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
  const fail = (node: ts.Node, code: string, what: string, fix: string) => {
    const line = sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
    violations.push(`FAIL [${code}]: ${rel}:${line} ${what}\n      Fix: ${fix}`);
  };
  const direct = (node: ts.Node, code: string, what: string, fix: string) => {
    launchesDirectly.add(rel);
    if (!NOT_YET_MIGRATED[rel]) fail(node, code, what, fix);
  };
  const useSeam = `import it from ${SEAM}, which defaults windowsHide: true`;
  const visit = (node: ts.Node): void => {
    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && isModule(node.moduleSpecifier) && valueImport(node)) {
      direct(node, 'windows_hide_direct_child_process', 'imports child_process directly', useSeam);
    } else if (ts.isCallExpression(node) && isModule(node.arguments[0])
      && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === 'require'))) {
      direct(node, 'windows_hide_direct_child_process', `loads child_process with ${node.expression.getText(sf)}()`, useSeam);
    } else if (ts.isPropertyAccessExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'Bun'
      && (node.name.text === 'spawn' || node.name.text === 'spawnSync')) {
      const wrapper = node.name.text === 'spawn' ? 'bunSpawn' : 'bunSpawnSync';
      direct(node, 'windows_hide_direct_bun_spawn', `calls Bun.${node.name.text}`, `call ${wrapper} from ${SEAM}, which defaults windowsHide: true`);
    } else if (ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteralLike(node.name))
      && node.name.text === 'windowsHide' && node.initializer.kind === ts.SyntaxKind.FalseKeyword) {
      optedOut.add(rel);
      if (!ALLOWLIST[rel]) fail(node, 'windows_hide_opt_out', 'sets windowsHide: false', `drop it, or add ${rel} to ALLOWLIST in scripts/check-windows-hide.ts with the reason the window must show`);
    }
    ts.forEachChild(node, visit);
  };
  visit(sf);
}
for (const [rel, reason] of Object.entries(ALLOWLIST)) {
  if (existsSync(join(ROOT, rel)) && !optedOut.has(rel)) {
    violations.push(`FAIL [windows_hide_stale_allowlist]: ${rel} no longer sets windowsHide: false (allowlisted: ${reason})\n      Fix: delete its ALLOWLIST entry in scripts/check-windows-hide.ts`);
  }
}
for (const [rel, reason] of Object.entries(NOT_YET_MIGRATED)) {
  if (existsSync(join(ROOT, rel)) && !launchesDirectly.has(rel)) {
    violations.push(`FAIL [windows_hide_stale_migration_entry]: ${rel} no longer launches subprocesses directly (listed: ${reason})\n      Fix: delete its NOT_YET_MIGRATED entry in scripts/check-windows-hide.ts; the ratchet only goes down`);
  }
}

if (violations.length) {
  for (const v of violations) console.error(v);
  console.error('Why:  on Windows a console program launched from a detached gbrain process without windowsHide opens a visible console window that takes focus (#4992).');
  console.error(`See:  ${ANCHOR}`);
  console.error(`check-windows-hide: ${violations.length} violation(s)`);
  process.exit(1);
}
console.log(`check-windows-hide: ok (src/, seam ${SEAM}, ${Object.keys(ALLOWLIST).length} allowlisted opt-out, ${Object.keys(NOT_YET_MIGRATED).length} not yet migrated)`);