Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
22.4 KB
Raw Blame
import { describe, test, expect, spyOn } from 'bun:test';
import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'fs';
import { dirname, join } from 'path';
import { tmpdir } from 'os';
import * as upgradeModule from '../src/commands/upgrade.ts';
import { resolveBunGlobalRoot } from '../src/commands/upgrade.ts';
import { formatMarker } from '../src/core/self-upgrade.ts';
import type { BinarySelfUpdateResult } from '../src/core/binary-self-update.ts';
import { VERSION } from '../src/version.ts';
import { fileURLToPath } from 'node:url';

// Install-method detection runs in-process where it spawns nothing (argv[1] /
// execPath patched); PATH-shimmed paths (bun-link, bun update) run
// runUpgrade in a subprocess, because Bun snapshots PATH at process start.

describe('upgrade command', () => {
  test('--help prints usage and exits 0', async () => {
    const proc = Bun.spawn(['bun', 'run', 'src/cli.ts', 'upgrade', '--help'], {
      cwd: fileURLToPath(new URL('..', import.meta.url)),
      stdout: 'pipe',
      stderr: 'pipe',
    });
    const stdout = await new Response(proc.stdout).text();
    const exitCode = await proc.exited;
    expect(stdout).toContain('Usage: gbrain upgrade');
    expect(stdout).toContain('Detects install method');
    expect(exitCode).toBe(0);
  });

  test('-h also prints usage', async () => {
    const proc = Bun.spawn(['bun', 'run', 'src/cli.ts', 'upgrade', '-h'], {
      cwd: fileURLToPath(new URL('..', import.meta.url)),
      stdout: 'pipe',
      stderr: 'pipe',
    });
    const stdout = await new Response(proc.stdout).text();
    const exitCode = await proc.exited;
    expect(stdout).toContain('Usage: gbrain upgrade');
    expect(exitCode).toBe(0);
  });
});

describe('detectInstallMethod — package-install classification (in-process)', () => {
  // The node_modules branch spawns nothing, so argv[1] / execPath are patched
  // in-process (serial file). The bun-link and cwd contracts need
  // PATH shims and live in the subprocess suite below.
  const originalArgv1 = process.argv[1];
  const originalExecPath = process.execPath;

  function detectFrom(pkg: Record<string, unknown>, entry: string, execPath?: string) {
    const root = mkdtempSync(join(tmpdir(), 'gbrain-upgrade-detect-'));
    const pkgDir = join(root, 'node_modules', 'gbrain');
    const argv1 = join(pkgDir, entry);
    mkdirSync(dirname(argv1), { recursive: true });
    writeFileSync(join(pkgDir, 'package.json'), JSON.stringify(pkg));
    writeFileSync(argv1, '');
    const warn = spyOn(console, 'warn').mockImplementation(() => {});
    try {
      process.argv[1] = argv1;
      if (execPath) Object.defineProperty(process, 'execPath', { value: execPath, configurable: true, writable: true });
      const method = upgradeModule.detectInstallMethod();
      return { method, warnings: warn.mock.calls.map(c => c.join(' ')).join('\n') };
    } finally {
      warn.mockRestore();
      process.argv[1] = originalArgv1;
      Object.defineProperty(process, 'execPath', { value: originalExecPath, configurable: true, writable: true });
      rmSync(root, { recursive: true, force: true });
    }
  }

  test('canonical by repository.url: bun, no squatter warning', () => {
    const r = detectFrom({ name: 'gbrain', repository: { url: 'git+https://github.com/GarryTan/GBrain.git' } }, 'dist/cli.js');
    expect(r.method).toBe('bun');
    expect(r.warnings).toBe('');
  });

  test('canonical by shipped src/cli.ts marker when repository is absent', () => {
    const r = detectFrom({ name: 'gbrain' }, 'src/cli.ts');
    expect(r.method).toBe('bun');
    expect(r.warnings).toBe('');
  });

  test('npm squatter (no repository, no source) warns with clone + release recovery (#658)', () => {
    const r = detectFrom({ name: 'gbrain', version: '1.3.0' }, 'dist/cli.js');
    expect(r.method).toBe('bun');
    expect(r.warnings).toContain('WARNING');
    expect(r.warnings).toContain('git clone https://github.com/garrytan/gbrain.git');
    expect(r.warnings).toContain('https://github.com/garrytan/gbrain/releases');
    expect(r.warnings).toContain('#658');
  });

  test('node_modules is checked before the compiled-binary execPath name', () => {
    const r = detectFrom({ name: 'gbrain', repository: 'github:garrytan/gbrain' }, 'dist/cli.js', '/opt/bin/gbrain');
    expect(r.method).toBe('bun');
  });

  // #8464: a release asset run under its published name is the compiled binary, found by Bun's virtual entrypoint.
  for (const [argv1, execPath] of [
    ['/$bunfs/root/gbrain-linux-x64', '/opt/bin/gbrain-linux-x64'],
    ['/$bunfs/root/gbrain-darwin-arm64', '/Users/alice-example/Downloads/gbrain-darwin-arm64'],
    ['B:\\~BUN\\root\\gb.exe', 'C:\\tools\\gb.exe'],
  ] as const) {
    test(`a compiled binary named ${execPath} is the binary install`, () => {
      const cwd = process.cwd();
      const elsewhere = mkdtempSync(join(tmpdir(), 'gbrain-upgrade-compiled-'));
      try {
        process.chdir(elsewhere);
        process.argv[1] = argv1;
        Object.defineProperty(process, 'execPath', { value: execPath, configurable: true, writable: true });
        expect(upgradeModule.detectInstallMethod()).toBe('binary');
      } finally {
        process.chdir(cwd);
        rmSync(elsewhere, { recursive: true, force: true });
        process.argv[1] = originalArgv1;
        Object.defineProperty(process, 'execPath', { value: originalExecPath, configurable: true, writable: true });
      }
    });
  }
});

describe('resolveBunGlobalRoot', () => {
  const originalBunInstall = process.env.BUN_INSTALL;
  const originalHome = process.env.HOME;
  const originalArgv1 = process.argv[1];

  function restoreEnv() {
    if (originalBunInstall === undefined) delete process.env.BUN_INSTALL;
    else process.env.BUN_INSTALL = originalBunInstall;

    if (originalHome === undefined) delete process.env.HOME;
    else process.env.HOME = originalHome;

    process.argv[1] = originalArgv1;
  }

  test('honors BUN_INSTALL override', () => {
    try {
      process.env.BUN_INSTALL = '/custom/bun';
      process.env.HOME = '/ignored/home';
      expect(resolveBunGlobalRoot()).toBe('/custom/bun/install/global');
    } finally {
      restoreEnv();
    }
  });

  test('uses canonical ~/.bun/install/global when present', () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-upgrade-home-'));
    try {
      delete process.env.BUN_INSTALL;
      process.env.HOME = home;
      const globalRoot = join(home, '.bun', 'install', 'global');
      mkdirSync(join(globalRoot, 'node_modules'), { recursive: true });
      writeFileSync(join(globalRoot, 'package.json'), '{}');

      expect(resolveBunGlobalRoot()).toBe(globalRoot);
    } finally {
      restoreEnv();
      rmSync(home, { recursive: true, force: true });
    }
  });

  test('falls back to the package root above node_modules/gbrain', () => {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-upgrade-home-'));
    const globalRoot = mkdtempSync(join(tmpdir(), 'gbrain-upgrade-global-'));
    try {
      delete process.env.BUN_INSTALL;
      process.env.HOME = home;
      const cliPath = join(globalRoot, 'node_modules', 'gbrain', 'src', 'cli.ts');
      mkdirSync(dirname(cliPath), { recursive: true });
      mkdirSync(join(globalRoot, 'node_modules'), { recursive: true });
      writeFileSync(join(globalRoot, 'package.json'), '{}');
      writeFileSync(cliPath, '');
      process.argv[1] = cliPath;

      expect(resolveBunGlobalRoot()).toBe(realpathSync(globalRoot));
    } finally {
      restoreEnv();
      rmSync(home, { recursive: true, force: true });
      rmSync(globalRoot, { recursive: true, force: true });
    }
  });
});

describe('post-upgrade behavior (post v0.12.0 merge)', () => {
  // The earlier --execute / --yes / auto_execute tests were removed when the
  // master merge replaced the markdown-driven runPostUpgrade with the TS
  // migration registry + apply-migrations orchestrator. The new contract:
  //   - Prints feature pitches for migrations newer than the prior binary
  //     (via the TS registry, not skills/migrations/*.md).
  //   - Always invokes `apply-migrations --yes` (idempotent; no-op when
  //     nothing is pending).
  //   - --help still prints usage.

  test('--help prints usage', async () => {
    const proc = Bun.spawn(['bun', 'run', 'src/cli.ts', 'post-upgrade', '--help'], {
      cwd: fileURLToPath(new URL('..', import.meta.url)),
      stdout: 'pipe',
      stderr: 'pipe',
    });
    const stdout = await new Response(proc.stdout).text();
    const exitCode = await proc.exited;
    expect(exitCode).toBe(0);
    expect(stdout).toContain('Usage: gbrain post-upgrade');
  });
});

describe('assessUpgradeOutcome (#4366)', () => {
  test('mismatch when still running an older version than the target', () => {
    expect(upgradeModule.assessUpgradeOutcome('0.46.25.0', '0.46.21.0')).toBe('mismatch');
  });

  test('ok when the observed version reaches or passes the target', () => {
    expect(upgradeModule.assessUpgradeOutcome('0.46.25.0', '0.46.25.0')).toBe('ok');
    expect(upgradeModule.assessUpgradeOutcome('0.46.25.0', '0.47.0.0')).toBe('ok');
  });

  test('ok when no target is known (legacy callers keep current behavior)', () => {
    expect(upgradeModule.assessUpgradeOutcome(undefined, '0.40.0.0')).toBe('ok');
  });

  test('unverified when the observed version is missing or unparseable', () => {
    expect(upgradeModule.assessUpgradeOutcome('0.46.25.0', '')).toBe('unverified');
    expect(upgradeModule.assessUpgradeOutcome('0.46.25.0', 'not-a-version')).toBe('unverified');
  });

  test('accepts a v-prefixed target tag', () => {
    expect(upgradeModule.assessUpgradeOutcome('v0.46.25.0', '0.46.21.0')).toBe('mismatch');
  });
});

describe('runUpgrade target verification (#4366)', () => {
  const TARGET = '99.99.99.0';
  const OLD = '0.40.0.0';
  const repoRoot = fileURLToPath(new URL('..', import.meta.url));

  /**
   * Build a hermetic fake install under a temp HOME and run runUpgrade in a
   * subprocess (Bun snapshots environ at birth, so PATH shims cannot be
   * injected in-process):
   *   - by default a global package install whose PATH `bun` shim exits 0
   *     without changing anything (`bun update` on an exact-tag Git pin, the
   *     issue's install);
   *   - a PATH `clawhub` CLI that answers every command and logs it to
   *     HOME/clawhub.log, which must never be run (#8464);
   *   - a PATH-first `gbrain` shim that keeps reporting `observedVersion`;
   *   - a pre-seeded upgrade-available marker so cache retention is observable;
   *   - with `binaryResult`, the driver runs under a copy of bun named `gbrain`
   *     (detectInstallMethod keys on execPath's basename) and the driver mocks
   *     runBinarySelfUpdate to return that result, reaching the binary branch;
   *   - with `execName`, the driver runs outside any install under a copy of
   *     bun with that name.
   */
  async function runUpgradeAgainstFakeInstall(opts: {
    observedVersion: string;
    targetVersion?: string;
    binaryResult?: BinarySelfUpdateResult;
    /** Body of the PATH `clawhub` shim after it logs the call (default: exit 0 for everything). */
    clawhub?: string;
    /** Run the driver outside any install under a copy of bun with this name. */
    execName?: string;
    /** Driver directory relative to the fake HOME (default: HOME itself). */
    driverDir?: string;
    /** Shim `git` and `bun` as recorders appending `<cwd>|<args>` to HOME/calls.log. */
    recordGitAndBun?: boolean;
    /** Lay out extra install-shape files under HOME before the spawn. */
    setup?: (home: string) => void;
  }): Promise<{ home: string; exitCode: number; stdout: string; stderr: string }> {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-upgrade-target-'));
    const bin = join(home, 'bin');
    mkdirSync(bin);
    writeFileSync(join(bin, 'clawhub'), `#!/bin/sh\necho "$*" >> "${join(home, 'clawhub.log')}"\n${opts.clawhub ?? 'exit 0'}\n`);
    writeFileSync(join(bin, 'gbrain'), `#!/bin/sh\necho "gbrain ${opts.observedVersion}"\n`);
    chmodSync(join(bin, 'clawhub'), 0o755);
    chmodSync(join(bin, 'gbrain'), 0o755);
    // #6662: verify-target probes the release tag with `git ls-remote`; report it published, offline.
    writeFileSync(join(bin, 'git'), `#!/bin/sh\ncase "$1" in ls-remote) exit 0;; esac\nexec ${JSON.stringify(Bun.which('git') ?? '/usr/bin/git')} "$@"\n`);
    chmodSync(join(bin, 'git'), 0o755);
    if (opts.recordGitAndBun) {
      for (const tool of ['git', 'bun']) {
        writeFileSync(join(bin, tool), `#!/bin/sh\necho "$(pwd)|$*" >> "${join(home, 'calls.log')}"\nexit 0\n`);
        chmodSync(join(bin, tool), 0o755);
      }
    }

    mkdirSync(join(home, '.gbrain'), { recursive: true });
    writeFileSync(
      join(home, '.gbrain', 'last-update-check'),
      formatMarker({ kind: 'upgrade_available', current: OLD, latest: TARGET }) + '\n',
    );

    // The driver lives OUTSIDE the repo so detectInstallMethod() cannot see the
    // checkout's node_modules/.git ancestor.
    const globalInstall = opts.driverDir === undefined && !opts.binaryResult && !opts.execName;
    const driverDir = join(home, globalInstall ? join('global', 'node_modules', 'gbrain', 'src') : opts.driverDir ?? '');
    mkdirSync(driverDir, { recursive: true });
    if (globalInstall) {
      writeFileSync(join(home, 'global', 'package.json'), '{}');
      writeFileSync(join(home, 'global', 'node_modules', 'gbrain', 'package.json'), JSON.stringify({ name: 'gbrain', repository: 'github:garrytan/gbrain' }));
      if (!opts.recordGitAndBun) {
        writeFileSync(join(bin, 'bun'), '#!/bin/sh\nexit 0\n');
        chmodSync(join(bin, 'bun'), 0o755);
      }
    }
    opts.setup?.(home);
    const driverPath = join(driverDir, 'driver.ts');
    const mockPrelude = opts.binaryResult
      ? `import { mock } from 'bun:test';\n` +
        `mock.module('${repoRoot}src/core/binary-self-update.ts', () => ({\n` +
        `  runBinarySelfUpdate: async () => (${JSON.stringify(opts.binaryResult)}),\n` +
        `}));\n`
      : '';
    writeFileSync(
      driverPath,
      mockPrelude +
        `import { runUpgrade } from '${repoRoot}src/commands/upgrade.ts';\n` +
        `const t = process.env.TEST_TARGET_VERSION;\n` +
        `await runUpgrade(['--swap-only', '--no-bun-floor-check'], t ? { targetVersion: t } : {});\n`,
    );
    let bunExec = process.execPath;
    if (opts.binaryResult || opts.execName) {
      bunExec = join(home, 'exec', opts.execName ?? 'gbrain');
      mkdirSync(dirname(bunExec));
      copyFileSync(process.execPath, bunExec);
      chmodSync(bunExec, 0o755);
    }

    const env: Record<string, string | undefined> = {
      ...process.env,
      HOME: home,
      GBRAIN_HOME: home,
      // The install method's own path (alpha); the stable channel has its own suite (upgrade-stable-channel).
      GBRAIN_RELEASE_CHANNEL: 'alpha',
      PATH: `${bin}:${process.env.PATH}`,
    };
    delete env.TEST_TARGET_VERSION;
    delete env.BUN_INSTALL;
    if (opts.targetVersion) env.TEST_TARGET_VERSION = opts.targetVersion;

    const proc = Bun.spawn([bunExec, 'run', driverPath], {
      cwd: repoRoot,
      env,
      stdout: 'pipe',
      stderr: 'pipe',
    });
    const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
    const exitCode = await proc.exited;
    return { home, exitCode, stdout, stderr };
  }

  test('mismatch exits nonzero, keeps the pending-upgrade cache, and records verify-target', async () => {
    const { home, exitCode, stderr } = await runUpgradeAgainstFakeInstall({
      observedVersion: OLD,
      targetVersion: TARGET,
    });
    try {
      expect(exitCode).toBe(1);
      // The upgrade-available marker must survive so future nags still fire.
      expect(existsSync(join(home, '.gbrain', 'last-update-check'))).toBe(true);
      // No false JUST_UPGRADED breadcrumb for an upgrade that never happened.
      expect(existsSync(join(home, '.gbrain', 'just-upgraded-from'))).toBe(false);
      // The operator gets the exact-tag reinstall remediation.
      expect(stderr).toContain(`github:garrytan/gbrain#v${TARGET}`);

      const errPath = join(home, '.gbrain', 'upgrade-errors.jsonl');
      const records = existsSync(errPath)
        ? readFileSync(errPath, 'utf-8').trim().split('\n').map((l) => JSON.parse(l))
        : [];
      expect(records.some((r) => r.phase === 'verify-target')).toBe(true);
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  });

  test('reaching the target keeps the success path: cache cleared, breadcrumb written, exit 0', async () => {
    const { home, exitCode } = await runUpgradeAgainstFakeInstall({
      observedVersion: TARGET,
      targetVersion: TARGET,
    });
    try {
      expect(exitCode).toBe(0);
      expect(existsSync(join(home, '.gbrain', 'last-update-check'))).toBe(false);
      expect(readFileSync(join(home, '.gbrain', 'just-upgraded-from'), 'utf-8').trim()).toBe(VERSION);
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  });

  test('no target (legacy caller) preserves prior behavior even when the version is stale', async () => {
    const { home, exitCode } = await runUpgradeAgainstFakeInstall({
      observedVersion: OLD,
    });
    try {
      expect(exitCode).toBe(0);
      expect(existsSync(join(home, '.gbrain', 'last-update-check'))).toBe(false);
      expect(existsSync(join(home, '.gbrain', 'just-upgraded-from'))).toBe(true);
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  });

  // A failed binary swap must still name the release it attempted. With no
  // caller target (plain `gbrain upgrade`), to_version comes from the release
  // tag runBinarySelfUpdate resolved — never '' — so doctor can say which
  // version failed to install.
  for (const [reason, error] of [
    ['smoke_failed', undefined],
    ['version_mismatch', undefined],
    ['replace_failed', 'EACCES: permission denied'],
  ] as const) {
    test(`binary self-update ${reason} records to_version = attempted release`, async () => {
      const { home } = await runUpgradeAgainstFakeInstall({
        observedVersion: OLD,
        binaryResult: { ok: false, reason, targetVersion: TARGET, error },
      });
      try {
        const errPath = join(home, '.gbrain', 'upgrade-errors.jsonl');
        const records = readFileSync(errPath, 'utf-8').trim().split('\n').map((l) => JSON.parse(l));
        const rec = records.find((r) => r.phase === 'binary-self-update');
        expect(rec?.to_version).toBe(TARGET);
        expect(rec?.error).toBe(error ? `${reason}: ${error}` : reason);
      } finally {
        rmSync(home, { recursive: true, force: true });
      }
    });
  }

  // ── install-method detection + upgrade commands (PATH-shimmed) ──────────

  // #8464: `clawhub update gbrain` installs whatever skill anyone publishes as gbrain, so a working clawhub CLI on
  // PATH must never become the install method, for a renamed release asset or any other undetected install.
  for (const execName of ['gbrain-linux-x64', 'bun']) {
    test(`an undetected install run as ${execName} never runs clawhub, even when the clawhub CLI works`, async () => {
      const { home, stdout, stderr } = await runUpgradeAgainstFakeInstall({ observedVersion: OLD, execName });
      try {
        expect(stdout).toContain('Detected install method: unknown');
        expect(stderr).toContain('Could not detect installation method.');
        expect(existsSync(join(home, 'clawhub.log'))).toBe(false);
        expect(`${stdout}${stderr}`).not.toMatch(/clawhub|\bnpm\b/i);
      } finally {
        rmSync(home, { recursive: true, force: true });
      }
    });
  }

  test('a hung clawhub CLI on PATH is never probed, so upgrade cannot wedge on it', async () => {
    const started = Date.now();
    const { home, stdout } = await runUpgradeAgainstFakeInstall({
      observedVersion: OLD,
      execName: 'gbrain-linux-x64',
      clawhub: 'exec sleep 60',
    });
    try {
      expect(stdout).toContain('Detected install method: unknown');
      expect(existsSync(join(home, 'clawhub.log'))).toBe(false);
      expect(Date.now() - started).toBeLessThan(30_000);
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  }, 60_000);

  test('bun-link: case-insensitive .git/config marker; git pull + bun install run at the repo root without a shell', async () => {
    // The checkout path carries shell metacharacters: a template-string
    // execSync would run the `touch`; execFileSync passes it through intact.
    const marker = `INJECTED-${process.pid}-${Date.now()}`;
    const repoDir = `clone $(touch ${marker})`;
    const { home, stdout } = await runUpgradeAgainstFakeInstall({
      observedVersion: OLD,
      driverDir: join(repoDir, 'src'),
      recordGitAndBun: true,
      setup: (h) => {
        mkdirSync(join(h, repoDir, '.git'), { recursive: true });
        writeFileSync(join(h, repoDir, '.git', 'config'), '[remote "origin"]\n\turl = https://github.com/GarryTan/GBrain.git\n');
      },
    });
    try {
      const root = join(home, repoDir);
      expect(stdout).toContain('Detected install method: bun-link');
      // `rev-parse HEAD` records the pre-swap commit for #5855's recovery text.
      const calls = readFileSync(join(home, 'calls.log'), 'utf-8').trim().split('\n').filter((c) => !c.endsWith(' rev-parse HEAD'));
      expect(calls[0]!.split('|')[1]).toBe(`-C ${root} pull --ff-only`);
      expect(calls[1]).toBe(`${realpathSync(root)}|install`);
      for (const dir of [home, repoRoot, join(root, 'src')]) {
        expect(existsSync(join(dir, marker))).toBe(false);
      }
    } finally {
      rmSync(join(repoRoot, marker), { force: true });
      rmSync(home, { recursive: true, force: true });
    }
  });

  test('bun global install: `bun update --backend=copyfile gbrain` runs in the bun global root', async () => {
    const { home, stdout } = await runUpgradeAgainstFakeInstall({
      observedVersion: OLD,
      driverDir: join('global', 'node_modules', 'gbrain', 'src'),
      recordGitAndBun: true,
      setup: (h) => {
        writeFileSync(join(h, 'global', 'package.json'), '{}');
        writeFileSync(join(h, 'global', 'node_modules', 'gbrain', 'package.json'), JSON.stringify({ name: 'gbrain', repository: 'github:garrytan/gbrain' }));
      },
    });
    try {
      expect(stdout).toContain('Detected install method: bun');
      const calls = readFileSync(join(home, 'calls.log'), 'utf-8').trim().split('\n');
      expect(calls).toEqual([`${realpathSync(join(home, 'global'))}|update --backend=copyfile gbrain`]);
    } finally {
      rmSync(home, { recursive: true, force: true });
    }
  });
});