Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
21.1 KB
Raw Blame
/**
 * v0.39.3.0 WARN-5 + WARN-6 — CLI help discoverability.
 *
 * WARN-5: `gbrain capture --help` was showing only the generic
 * `Usage: gbrain capture` line because `capture` was missing from
 * CLI_ONLY_SELF_HELP (src/cli.ts:34-53). Fix added it to the set AND
 * added a pre-engine-bind `--help` short-circuit at handleCliOnly so
 * the HELP constant is reachable on a fresh tmpdir with no config.
 *
 * WARN-6: `capture`, `brainstorm`, `lsd` were missing from the main
 * `gbrain --help` text. Added a BRAIN section to printHelp.
 *
 * These tests spawn `bun src/cli.ts` as a subprocess so they exercise
 * the real dispatcher flow end-to-end (no mocking of cli.ts internals).
 * Help output is read-only, so calls route through runCliMemo
 * (test/helpers/cli-spawn.ts) — one spawn per unique argv (`--help`
 * repeats 8x, `takes --help` 3x, ...). The lone un-memoized call is
 * `sources detach --help`: it depends on cwd and asserts a filesystem
 * non-side-effect, both outside the memo's argv+home key.
 */

import { describe, test, expect } from 'bun:test';
import { mkdtempSync, writeFileSync, existsSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { runCli, runCliMemo } from './helpers/cli-spawn.ts';

// Hermetic no-brain environment, matching cli-help-without-brain.test.ts:
// GBRAIN_HOME alone is not enough — loadConfig also honours GBRAIN_DATABASE_URL
// and DATABASE_URL, so a developer or CI runner exporting either would let the
// CLI connect anyway and these assertions would go inert. cli-spawn strips both
// from every child env; opts.home points HOME + GBRAIN_HOME at a nonexistent
// dir. The helper also spawns with `bun --no-env-file` (as the old local
// wrapper did) so a repo-root .env cannot re-add the stripped vars.
const NO_BRAIN_HOME = '/tmp/gbrain-test-help-nonexistent';

// Memoized: identical argv returns the cached CliResult without respawning.
// Safe here because every invocation is a pure --help/-h read.
function help(args: string[]) {
  return runCliMemo(args, { home: NO_BRAIN_HOME });
}

describe('WARN-5 — `gbrain capture --help` reaches the detailed HELP constant', () => {
  test('output contains every documented flag', async () => {
    const { stdout, exitCode } = await help(['capture', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('--slug');
    expect(stdout).toContain('--type');
    expect(stdout).toContain('--file');
    expect(stdout).toContain('--stdin');
    expect(stdout).toContain('--source');
    expect(stdout).toContain('--quiet');
    expect(stdout).toContain('--json');
  });

  test('output is NOT the generic short-circuit fallback', async () => {
    const { stdout } = await help(['capture', '--help']);
    // Pre-fix output was: "Usage: gbrain capture\n\ngbrain capture - run gbrain --help ..."
    // Post-fix HELP is much longer and includes Examples.
    expect(stdout).toContain('Examples:');
    expect(stdout.split('\n').length).toBeGreaterThan(10);
    expect(stdout).not.toMatch(/^Usage: gbrain capture\s*$/m);
  });

  test('-h short flag also works', async () => {
    const { stdout, exitCode } = await help(['capture', '-h']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('--file PATH');
  });
});

describe('WARN-6 — main `gbrain --help` lists capture/brainstorm/lsd', () => {
  test('output mentions all three commands by name', async () => {
    const { stdout, exitCode } = await help(['--help']);
    expect(exitCode).toBe(0);
    // Must appear as command names (not just words in prose somewhere)
    expect(stdout).toMatch(/^\s*capture\s/m);
    expect(stdout).toMatch(/^\s*brainstorm\s/m);
    expect(stdout).toMatch(/^\s*lsd\s/m);
  });

  test('BRAIN section heading is present and groups the three commands', async () => {
    const { stdout } = await help(['--help']);
    expect(stdout).toContain('BRAIN');
    // The 3 commands should appear AFTER the BRAIN heading in textual order.
    const brainIdx = stdout.indexOf('BRAIN');
    expect(brainIdx).toBeGreaterThan(-1);
    expect(stdout.indexOf('capture', brainIdx)).toBeGreaterThan(brainIdx);
    expect(stdout.indexOf('brainstorm', brainIdx)).toBeGreaterThan(brainIdx);
    expect(stdout.indexOf('lsd', brainIdx)).toBeGreaterThan(brainIdx);
  });

  test('regression: existing top-level commands still listed', async () => {
    // Snapshot guard against accidentally deleting other groups when we
    // added the BRAIN section. Spot-check a few commands from different
    // groups (SETUP, PAGES, SEARCH, IMPORT/EXPORT).
    const { stdout } = await help(['--help']);
    expect(stdout).toContain('init');
    expect(stdout).toContain('doctor');
    expect(stdout).toContain('get');
    expect(stdout).toContain('search');
    expect(stdout).toContain('query');
    expect(stdout).toContain('import');
    expect(stdout).toContain('export');
    expect(stdout).toContain('files');
    expect(stdout).toContain('embed');
  });
});

describe('#2795 — `sync --install-cron` help line no longer promises an unbuilt feature', () => {
  test('main `gbrain --help` does not advertise install-cron', async () => {
    // Pre-fix: `sync --install-cron  Install persistent sync daemon` was
    // listed in the top-level help with no flag parsing or handler behind
    // it anywhere in src/commands/sync.ts — `gbrain sync --install-cron`
    // silently ran an ordinary sync instead of installing anything.
    const { stdout, exitCode } = await help(['--help']);
    expect(exitCode).toBe(0);
    expect(stdout).not.toContain('install-cron');
    expect(stdout).not.toContain('Install persistent sync daemon');
  });

  test('main `gbrain --help` points sync users at the real continuous-daemon command', async () => {
    const { stdout } = await help(['--help']);
    // autopilot --install already runs sync+extract+embed on a schedule
    // (docs/architecture/KEY_FILES.md); point discoverability there instead
    // of promising a separate sync-only cron installer that never existed.
    expect(stdout).toMatch(/sync --watch \[--interval N\][^\n]*\n\s*See also: autopilot --install/);
  });

  test('`gbrain sync --help` never listed install-cron either', async () => {
    const { stdout, exitCode } = await help(['sync', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).not.toContain('install-cron');
  });
});

describe('#1175 — main `gbrain --help` SOURCES block matches the real subcommand set', () => {
  test('archive and its lifecycle siblings are listed', async () => {
    const { stdout, exitCode } = await help(['--help']);
    expect(exitCode).toBe(0);
    // Pre-fix the SOURCES block listed only list/add/remove; the soft-delete
    // alternative that `sources remove` itself recommends was undiscoverable.
    expect(stdout).toMatch(/^\s*sources archive <id>\s/m);
    expect(stdout).toMatch(/^\s*sources restore <id>\s/m);
    expect(stdout).toMatch(/^\s*sources archived\s/m);
    expect(stdout).toMatch(/^\s*sources purge/m);
    expect(stdout).toMatch(/^\s*sources status\s/m);
    // Pointer at the full per-subcommand help for the long tail.
    expect(stdout).toMatch(/^\s*sources --help\s/m);
  });
});

describe('#4003 — `gbrain auth --help` reaches the detailed usage block', () => {
  test('output contains the real auth subcommand usage, not the generic stub', async () => {
    const { stdout, exitCode } = await help(['auth', '--help']);
    expect(exitCode).toBe(0);
    // Pre-fix: `auth` was missing from CLI_ONLY_SELF_HELP, so this printed
    // only "gbrain auth - run gbrain --help for the full command list."
    expect(stdout).toContain('GBrain Token Management');
    expect(stdout).toContain('gbrain auth create <name>');
    expect(stdout).toContain('gbrain auth register-client');
    expect(stdout).not.toContain('run gbrain --help for the full command list');
  });

  test('auth help points at the owner login flow without inventing a CLI command', async () => {
    const { stdout, exitCode } = await help(['auth', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('Admin dashboard login (running HTTP server):');
    expect(stdout).toContain('POST /admin/api/issue-magic-link');
    expect(stdout).toContain('do not GET the generated link');
    expect(stdout).toContain('See docs/mcp/DEPLOY.md.');
  });

  test('-h short flag also works', async () => {
    const { stdout, exitCode } = await help(['auth', '-h']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('GBrain Token Management');
  });

  test('main `gbrain --help` lists auth', async () => {
    const { stdout, exitCode } = await help(['--help']);
    expect(exitCode).toBe(0);
    expect(stdout).toMatch(/^\s*auth </m);
    expect(stdout).toMatch(/^\s*auth --help\s/m);
  });
});

describe('#4083 follow-up — auth subcommand + --help shows usage, never executes', () => {
  // Caught by automated PR review on #4083: once `auth` joined
  // CLI_ONLY_SELF_HELP, the generic --help short-circuit in cli.ts stopped
  // intercepting `gbrain auth <subcommand> --help` before it reached
  // runAuth. Without an early --help check inside runAuth itself, a
  // trailing --help on a real subcommand fell through to that
  // subcommand's real handler instead of showing help — e.g. `gbrain auth
  // create foo --help` would mint a real token named "foo".
  test('`gbrain auth create <name> --help` shows usage, does not create a token', async () => {
    const { stdout, exitCode } = await help(['auth', 'create', 'definitely-not-a-real-token-name', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('GBrain Token Management');
    expect(stdout).not.toContain('Token created for');
  });

  test('`gbrain auth revoke <name> --help` shows usage, does not attempt a revoke', async () => {
    const { stdout, exitCode } = await help(['auth', 'revoke', 'definitely-not-a-real-token-name', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('GBrain Token Management');
  });

  test('`gbrain auth register-client <name> --help` shows usage, does not register a client', async () => {
    const { stdout, exitCode } = await help(['auth', 'register-client', 'definitely-not-a-real-client', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('GBrain Token Management');
  });

  test('-h works the same way as --help on a subcommand', async () => {
    const { stdout, exitCode } = await help(['auth', 'create', 'definitely-not-a-real-token-name', '-h']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('GBrain Token Management');
    expect(stdout).not.toContain('Token created for');
  });
});

describe('#3834 — extract flags are discoverable from both help surfaces', () => {
  const implementedFlags = [
    '--by-mention',
    '--catch-up',
    '--concurrency',
    '--explain',
    '--from-meetings',
    '--include-frontmatter',
    '--infer-dates',
    '--ner',
    '--source-id',
    '--stale',
    '--workers',
  ];

  test('`gbrain extract --help` reaches detailed command help without a configured brain', async () => {
    const { stdout, stderr, exitCode } = await help(['extract', '--help']);
    expect(exitCode).toBe(0);
    expect(stderr).toBe('');
    expect(stdout).toContain('Usage: gbrain extract');
    expect(stdout).not.toContain('run gbrain --help for the full command list');
    for (const flag of implementedFlags) expect(stdout).toContain(flag);
  });

  test('`gbrain extract -h` reaches the same detailed command help', async () => {
    const { stdout, exitCode } = await help(['extract', '-h']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('--stale');
    expect(stdout).toContain('--include-frontmatter');
  });

  test('main `gbrain --help` documents every implemented extract flag', async () => {
    const { stdout, exitCode } = await help(['--help']);
    expect(exitCode).toBe(0);
    const extractStart = stdout.indexOf('  extract <links|timeline|all>');
    const publishStart = stdout.indexOf('  publish <page.md>', extractStart);
    expect(extractStart).toBeGreaterThan(-1);
    expect(publishStart).toBeGreaterThan(extractStart);
    const extractHelp = stdout.slice(extractStart, publishStart);
    for (const flag of implementedFlags) expect(extractHelp).toContain(flag);
  });
});

describe('sources --help reaches its own usage block instead of the circular generic stub', () => {
  test('`gbrain sources --help` reaches detailed command help without a configured brain', async () => {
    const { stdout, stderr, exitCode } = await help(['sources', '--help']);
    expect(exitCode).toBe(0);
    expect(stderr).toBe('');
    expect(stdout).toContain('Subcommands:');
    // Pre-fix output was the generic short-circuit, which itself points back
    // at `gbrain --help` — a circular pointer, since the top-level help's own
    // SOURCES block promises `sources --help` as the place to find these.
    expect(stdout).not.toContain('run gbrain --help for the full command list');
    // Subcommands the top-level `gbrain --help` SOURCES block does NOT list
    // (it only lists list/add/remove/archive/restore/archived/purge/status)
    // and instead defers to `sources --help` for.
    expect(stdout).toContain('rename');
    expect(stdout).toContain('set-cr-mode');
    expect(stdout).toContain('federate');
    expect(stdout).toContain('attach');
    expect(stdout).toContain('harden');
  });

  test('`gbrain sources -h` reaches the same detailed command help', async () => {
    const { stdout, exitCode } = await help(['sources', '-h']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('set-cr-mode');
    expect(stdout).not.toContain('run gbrain --help for the full command list');
  });
});

describe('regression: nested `sources <sub> --help` must print help, not dispatch to <sub>', () => {
  // `hasHelpFlag` in src/cli.ts matches --help/-h in ANY position, which is
  // what routes `sources list --help` into SELF_HELP_WITHOUT_ENGINE with a
  // placeholder null engine. Before the sources.ts guard, runSources's
  // switch dispatched on args[0] only ('list'), so the '--help' in position
  // 1 was silently dropped and runList(nullEngine, ['--help']) actually ran
  // — crashing on the placeholder engine. Some subcommands (`detach`) don't
  // even touch the engine and would perform their real, destructive action
  // instead of crashing.
  test('`sources list --help` prints help and does not dispatch into runList (no null-engine crash)', async () => {
    const { stdout, stderr, exitCode } = await help(['sources', 'list', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('Subcommands:');
    expect(stdout).not.toContain('run gbrain --help for the full command list');
    // Pre-fix this crashed inside runList with something like
    // "null is not an object (evaluating 'engine.executeRaw')".
    expect(stderr).not.toContain('executeRaw');
    expect(stderr).not.toContain('TypeError');
  });

  test('`sources detach --help` prints help and does NOT delete .gbrain-source', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'gbrain-sources-detach-help-'));
    const dotfile = join(dir, '.gbrain-source');
    writeFileSync(dotfile, 'example-source\n');
    try {
      // Un-memoized on purpose: the spawned process's cwd must point at the
      // scratch directory, and the assertion is a filesystem non-side-effect
      // — neither is part of runCliMemo's argv+home cache key.
      const { stdout, exitCode } = await runCli(['sources', 'detach', '--help'], {
        home: NO_BRAIN_HOME,
        cwd: dir,
      });
      expect(exitCode).toBe(0);
      expect(stdout).toContain('Subcommands:');
      // The regression: runDetach() takes no engine and unconditionally
      // unlinks .gbrain-source — with no guard, `detach --help` silently
      // deletes the caller's dotfile instead of showing usage.
      expect(existsSync(dotfile)).toBe(true);
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });
});

describe('`sources webhook --help` reaches its own detailed help, not the general block or runWebhook*', () => {
  test('`sources webhook --help` prints the webhook-specific usage (set/show/rotate/clear), not the general SOURCES block', async () => {
    const { stdout, exitCode } = await help(['sources', 'webhook', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('Usage: gbrain sources webhook');
    expect(stdout).toContain('rotate <id>');
    expect(stdout).toContain('clear <id>');
    expect(stdout).toContain('One-time reveal');
    // The general block's opening line + a subcommand only it lists —
    // absence of both confirms this reached SOURCES_WEBHOOK_HELP, not
    // printHelp().
    expect(stdout).not.toContain('gbrain sources — manage multi-source brain configuration');
    expect(stdout).not.toContain('add <id> --path');
  });

  test('`sources webhook set x --help` prints webhook help and does NOT reach runWebhookSet', async () => {
    const { stdout, stderr, exitCode } = await help(['sources', 'webhook', 'set', 'x', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).toContain('Usage: gbrain sources webhook');
    // runWebhookSet's own usage-error / not-found text must never appear —
    // its presence would mean the guard let dispatch fall through to it.
    expect(stdout).not.toContain('Source "x" not found');
    expect(stderr).not.toContain('Source "x" not found');
    expect(stderr).not.toContain('--github-repo');
    expect(stderr).not.toContain('TypeError');
  });
});

describe('`gbrain takes --help` reaches the detailed subcommand block', () => {
  test('every mutate + read subcommand is listed', async () => {
    const { stdout, exitCode } = await help(['takes', '--help']);
    expect(exitCode).toBe(0);
    // Pre-fix these were undiscoverable from the CLI: `takes` was in CLI_ONLY
    // but not CLI_ONLY_SELF_HELP, so the generic stub fired before runTakes.
    expect(stdout).toContain('takes add');
    expect(stdout).toContain('takes update');
    expect(stdout).toContain('takes supersede');
    expect(stdout).toContain('takes resolve');
    expect(stdout).toContain('takes scorecard');
    expect(stdout).toContain('takes calibration');
    expect(stdout).toContain('takes search');
  });

  test('output is NOT the generic short-circuit fallback', async () => {
    const { stdout } = await help(['takes', '--help']);
    // Pre-fix output was exactly: "Usage: gbrain takes\n\ngbrain takes - run
    // gbrain --help for the full command list."
    expect(stdout).not.toContain('run gbrain --help for the full command list');
    expect(stdout).not.toMatch(/^Usage: gbrain takes\s*$/m);
    expect(stdout.split('\n').length).toBeGreaterThan(10);
  });

  test('help works with no brain configured (pre-engine-bind branch)', async () => {
    // `help` points GBRAIN_HOME at a nonexistent dir. Without the pre-engine
    // branch this printed "No brain configured. Run: gbrain init".
    const { stdout, exitCode } = await help(['takes', '--help']);
    expect(exitCode).toBe(0);
    expect(stdout).not.toContain('No brain configured');
    expect(stdout).toContain('--dir <path>');
  });
});

describe('D3: shadowed handler help and curated help are reachable', () => {
  // Each printed its own usage but was hidden behind the generic one-line
  // stub (record lacked selfHelp). One distinctive line per handler.
  const SELF_HELP_MARKERS: Record<string, string> = {
    advisor: 'gbrain advisor [--json] [--apply <finding-id>]',
    backfill: 'gbrain backfill',
    'book-mirror': 'gbrain book-mirror',
    'claw-test': 'gbrain claw-test',
    founder: 'Usage: gbrain founder scorecard <entity-slug>',
    'graph-query': 'Usage: gbrain graph-query <slug>',
    mounts: 'gbrain mounts',
    recall: 'Usage: gbrain recall [<entity>] [options]',
    think: 'Usage: gbrain think',
  };
  for (const [command, marker] of Object.entries(SELF_HELP_MARKERS)) {
    test(`\`${command} --help\` prints the handler's own usage, not the stub`, async () => {
      const { stdout, exitCode } = await help([command, '--help']);
      expect(exitCode).toBe(0);
      expect(stdout).toContain(marker);
      expect(stdout).not.toContain('run gbrain --help for the full command list');
    });
  }

  test('`doctor --help` lists the remediation flags with their consent effects', async () => {
    const { stdout, exitCode } = await help(['doctor', '--help']);
    expect(exitCode).toBe(0);
    for (const flag of ['--remediation-plan', '--remediate', '--include-repairs', '--max-usd', '--target-score', '--yes']) {
      expect(stdout).toContain(flag);
    }
    expect(stdout).toContain('[consent: destructive]');
  });
});

describe('#6606 — `gbrain --help` lists the memory verbs agents save facts with', () => {
  test('remember, recall and forget have their own section; capture points at remember for facts', async () => {
    const { stdout, exitCode } = await help(['--help']);
    expect(exitCode).toBe(0);
    const memory = stdout.slice(stdout.indexOf('MEMORY ('), stdout.indexOf('\nPAGES'));
    expect(memory).toContain('remember "<fact>" --entity <slug>');
    expect(memory).toContain('pushed into new agent sessions');
    expect(memory).toContain('recall [<entity>] [--query <q>]');
    expect(memory).toContain('forget <fact-id>');
    expect(stdout).toMatch(/capture \[content\][^\n]*\(a page;\n\s+a fact to recall later is `remember`\)/);
  });
});