Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
33.5 KB
Raw Blame
/**
 * Guard tests for scripts/check-bootstrap-tag.sh [C1 = D6-A] and
 * scripts/check-bootstrap-templates.sh [D4/D5/A1 + privacy], plus the
 * release-mechanics workflow pins (latest-stable advance, publish-template
 * gating) and the verify-dispatcher wiring.
 *
 * Both guards accept GBRAIN_BOOTSTRAP_GUARD_ROOT so every failure mode is
 * exercised against throwaway fixture trees (the no-tracked-symlinks-guard
 * precedent) — the real repo is only asserted green.
 */

import { describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';

const ROOT = resolve(import.meta.dir, '..');
const TAG_GUARD = join(ROOT, 'scripts/check-bootstrap-tag.sh');
const TPL_GUARD = join(ROOT, 'scripts/check-bootstrap-templates.sh');

// The banned fork name must never appear literally in a test file
// (scripts/check-privacy.sh + scripts/check-test-real-names.sh scan test/**),
// so fixtures construct it at runtime.
const BANNED_FORK_NAME = ['winter', 'mute'].join('');

function runGuard(script: string, fixtureRoot: string): { status: number | null; out: string } {
  const r = spawnSync('bash', [script], {
    cwd: ROOT,
    encoding: 'utf-8',
    env: { ...process.env, GBRAIN_BOOTSTRAP_GUARD_ROOT: fixtureRoot },
  });
  return { status: r.status, out: `${r.stdout}\n${r.stderr}` };
}

function makeFixture(files: Record<string, string>): string {
  const dir = mkdtempSync(join(tmpdir(), 'gbrain-bootstrap-guard-'));
  for (const [rel, content] of Object.entries(files)) {
    const p = join(dir, rel);
    mkdirSync(dirname(p), { recursive: true });
    writeFileSync(p, content);
  }
  return dir;
}

function withFixture(files: Record<string, string>, fn: (dir: string) => void): void {
  const dir = makeFixture(files);
  try {
    fn(dir);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

const BANK_JSON = JSON.stringify({
  version: 1,
  maxQuestions: 12,
  interviewKeys: ['AGENT_NAME'],
  consentKeys: ['HOOKS_CONSENT', 'MCP_SCOPE'],
  questions: {
    AGENT_NAME: { maxLength: 64 },
    HOOKS_CONSENT: { consent: true, maxLength: 8 },
    // Section (e) pins the harness-scoping prefix + interview phase on this
    // question — every "clean" fixture must carry a compliant MCP_SCOPE entry.
    MCP_SCOPE: {
      consent: true,
      phase: 'interview',
      question: '(Claude Code and opencode. Codex has no scope flag.) Register for this folder or the whole machine?',
      maxLength: 8,
    },
    UNUSED_OPTIONAL: { maxLength: 8 },
  },
});

// Minimal runbook that satisfies the section (e) counter-signal pins; fixtures
// exercising OTHER failure modes include it so they fail only for their own
// reason.
const RUNBOOK_PINS = 'Claude Code and opencode\nDo NOT offer an MCP scope choice\nNO trust prompt\n';

describe('check-bootstrap-tag.sh', () => {
  test('passes on this repo', () => {
    const r = runGuard(TAG_GUARD, ROOT);
    expect(r.status).toBe(0);
    expect(r.out).toContain('check-bootstrap-tag: ok');
  });

  test('skips with exit 0 when both entry docs are absent', () => {
    withFixture({ VERSION: '1.2.3.4\n' }, (dir) => {
      const r = runGuard(TAG_GUARD, dir);
      expect(r.status).toBe(0);
      expect(r.out).toContain('SKIP');
      expect(r.out).toContain('check-bootstrap-tag: ok');
    });
  });

  test('accepts sanctioned refs + matching runbook stamp', () => {
    withFixture(
      {
        VERSION: '1.2.3.4\n',
        'README.md':
          'Fetch https://raw.githubusercontent.com/garrytan/gbrain/stable/BOOTSTRAP_FOR_AGENTS.md\n' +
          'Install: `bun install -g github:garrytan/gbrain#stable`\n',
        'BOOTSTRAP_FOR_AGENTS.md':
          '<!-- gbrain-runbook-stamp: 1.2.3.4 -->\n# Runbook\n' +
          'Fetched from https://raw.githubusercontent.com/garrytan/gbrain/stable/BOOTSTRAP_FOR_AGENTS.md\n',
      },
      (dir) => {
        const r = runGuard(TAG_GUARD, dir);
        expect(r.status).toBe(0);
        expect(r.out).toContain('check-bootstrap-tag: ok');
      },
    );
  });

  test('fails on a v-prefixed raw pin', () => {
    withFixture(
      {
        VERSION: '1.2.3.4\n',
        'README.md':
          'Fetch https://raw.githubusercontent.com/garrytan/gbrain/v0.42.0.0/BOOTSTRAP_FOR_AGENTS.md\n',
      },
      (dir) => {
        const r = runGuard(TAG_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("unsanctioned ref 'v0.42.0.0'");
      },
    );
  });

  test('fails on the alpha install pin (#latest-stable): new users default to the soaked stable ref', () => {
    withFixture(
      {
        VERSION: '1.2.3.4\n',
        'README.md':
          'Fetch https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/BOOTSTRAP_FOR_AGENTS.md\n' +
          'Install: `bun install -g github:garrytan/gbrain#latest-stable`\n',
      },
      (dir) => {
        const r = runGuard(TAG_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("unsanctioned ref 'latest-stable'"); // pregate-literal: SANCTIONED=latest-stable the refused alpha ref is this test's input
        expect(r.out).toContain("'#latest-stable'");
      },
    );
  });

  test('fails on a branch-ref install pin (#master)', () => {
    withFixture(
      {
        VERSION: '1.2.3.4\n',
        'README.md': 'Install: `bun install -g github:garrytan/gbrain#master`\n',
      },
      (dir) => {
        const r = runGuard(TAG_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("'#master'");
      },
    );
  });

  test('tolerates the pre-bootstrap INSTALL_FOR_AGENTS.md master path (carve-out)', () => {
    withFixture(
      {
        VERSION: '1.2.3.4\n',
        'README.md':
          'OpenClaw path: https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md\n',
      },
      (dir) => {
        expect(runGuard(TAG_GUARD, dir).status).toBe(0);
      },
    );
  });

  test('fails when the runbook stamp mismatches VERSION', () => {
    withFixture(
      {
        VERSION: '1.2.3.4\n',
        'BOOTSTRAP_FOR_AGENTS.md': '<!-- gbrain-runbook-stamp: 9.9.9.9 -->\n# Runbook\n',
      },
      (dir) => {
        const r = runGuard(TAG_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("stamp '9.9.9.9' != VERSION '1.2.3.4'");
      },
    );
  });

  test('fails when the runbook is missing its stamp line entirely', () => {
    withFixture(
      {
        VERSION: '1.2.3.4\n',
        'BOOTSTRAP_FOR_AGENTS.md': '# Runbook without a stamp\n',
      },
      (dir) => {
        const r = runGuard(TAG_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain('missing its');
      },
    );
  });
});

describe('check-bootstrap-templates.sh', () => {
  test('passes on this repo', () => {
    const r = runGuard(TPL_GUARD, ROOT);
    expect(r.status).toBe(0);
    expect(r.out).toContain('check-bootstrap-templates: ok');
  });

  test('skips with exit 0 when templates/bootstrap is absent', () => {
    withFixture({ VERSION: '1.2.3.4\n' }, (dir) => {
      const r = runGuard(TPL_GUARD, dir);
      expect(r.status).toBe(0);
      expect(r.out).toContain('SKIP');
    });
  });

  test('accepts a clean bijection and warns (only) on unused non-consent keys', () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': BANK_JSON,
        'templates/bootstrap/SOUL.md.template':
          '# {{AGENT_NAME}}\nRepo: {{GITHUB_REPO_URL}}\n',
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(0);
        expect(r.out).toContain('WARN');
        expect(r.out).toContain('UNUSED_OPTIONAL');
        // Consent keys are exempt from the usage warning.
        expect(r.out).not.toContain('HOOKS_CONSENT');
      },
    );
  });

  test('fails on a token with no bank or DERIVED_TOKENS entry', () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': BANK_JSON,
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}} {{NOT_IN_BANK}}\n',
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain('NOT_IN_BANK');
      },
    );
  });

  test('fails on a malformed question bank', () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': '{ not json',
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}}\n',
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain('could not parse');
      },
    );
  });

  test('fails when a template carries the banned fork name (placeholder-only assertion)', () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': BANK_JSON,
        'templates/bootstrap/SOUL.md.template': `# {{AGENT_NAME}}, successor to ${BANNED_FORK_NAME}\n`,
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain('banned term');
      },
    );
  });

  test('checks runbook Phase: names against the TS phase list when both exist [D5]', () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': BANK_JSON,
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}}\n',
        'BOOTSTRAP_FOR_AGENTS.md':
          `<!-- gbrain-runbook-stamp: 1.2.3.4 -->\n${RUNBOOK_PINS}Phase: preflight\nPhase: not_a_phase\n`,
        'src/core/bootstrap/status.ts': "export const PHASES = ['preflight', 'interview'] as const;\n",
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("phase 'not_a_phase'");
        expect(r.out).not.toContain("phase 'preflight'");
      },
    );
  });

  test('(e) clean: runbook counter-signals + compliant MCP_SCOPE prefix pass', () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': BANK_JSON,
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}}\n',
        'BOOTSTRAP_FOR_AGENTS.md': `<!-- gbrain-runbook-stamp: 1.2.3.4 -->\n${RUNBOOK_PINS}`,
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(0);
        expect(r.out).toContain('check-bootstrap-templates: ok');
      },
    );
  });

  test('(e) fails when the runbook loses the Codex do-not-offer counter-signal', () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': BANK_JSON,
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}}\n',
        'BOOTSTRAP_FOR_AGENTS.md':
          '<!-- gbrain-runbook-stamp: 1.2.3.4 -->\nClaude Code and opencode\nNO trust prompt\n(counter-signal deleted)\n',
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain('Codex counter-signal');
      },
    );
  });

  test("(e) fails when the runbook loses the 'Claude Code and opencode' consent scoping", () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': BANK_JSON,
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}}\n',
        'BOOTSTRAP_FOR_AGENTS.md':
          '<!-- gbrain-runbook-stamp: 1.2.3.4 -->\nDo NOT offer an MCP scope choice\nNO trust prompt\n',
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("'Claude Code and opencode'");
      },
    );
  });

  test("(e) fails when the runbook loses the opencode 'no trust prompt' rationale", () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': BANK_JSON,
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}}\n',
        'BOOTSTRAP_FOR_AGENTS.md':
          '<!-- gbrain-runbook-stamp: 1.2.3.4 -->\nClaude Code and opencode\nDo NOT offer an MCP scope choice\n',
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain('spawn-gate rationale');
      },
    );
  });

  test('(e) fails when the questions object vanishes (valid JSON that silently passes §a)', () => {
    withFixture(
      {
        'templates/bootstrap/questions.json': '{"version":1,"maxQuestions":12,"interviewKeys":[],"consentKeys":[]}',
        'templates/bootstrap/SOUL.md.template': '# plain\n',
        'BOOTSTRAP_FOR_AGENTS.md': `<!-- gbrain-runbook-stamp: 1.2.3.4 -->\n${RUNBOOK_PINS}`,
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("must start with '(Claude Code and opencode'");
      },
    );
  });

  test('(e) fails when the MCP_SCOPE entry vanishes from the bank', () => {
    const bankNoEntry = JSON.stringify({
      version: 1,
      maxQuestions: 12,
      interviewKeys: ['AGENT_NAME'],
      consentKeys: ['HOOKS_CONSENT'],
      questions: {
        AGENT_NAME: { maxLength: 64 },
        HOOKS_CONSENT: { consent: true, maxLength: 8 },
      },
    });
    withFixture(
      {
        'templates/bootstrap/questions.json': bankNoEntry,
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}}\n',
        'BOOTSTRAP_FOR_AGENTS.md': `<!-- gbrain-runbook-stamp: 1.2.3.4 -->\n${RUNBOOK_PINS}`,
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("must start with '(Claude Code and opencode'");
      },
    );
  });

  test('(e) fails when MCP_SCOPE.phase reverts to wire (schema-vs-runbook contradiction)', () => {
    const bankWirePhase = JSON.stringify({
      version: 1,
      maxQuestions: 12,
      interviewKeys: ['AGENT_NAME'],
      consentKeys: ['HOOKS_CONSENT', 'MCP_SCOPE'],
      questions: {
        AGENT_NAME: { maxLength: 64 },
        HOOKS_CONSENT: { consent: true, maxLength: 8 },
        MCP_SCOPE: {
          consent: true,
          phase: 'wire',
          question: '(Claude Code and opencode. Codex has no scope flag.) Register for this folder or the whole machine?',
          maxLength: 8,
        },
      },
    });
    withFixture(
      {
        'templates/bootstrap/questions.json': bankWirePhase,
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}}\n',
        'BOOTSTRAP_FOR_AGENTS.md': `<!-- gbrain-runbook-stamp: 1.2.3.4 -->\n${RUNBOOK_PINS}`,
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("MCP_SCOPE.phase must be 'interview'");
      },
    );
  });

  test('(e) fails when MCP_SCOPE.question loses its harness prefix (or the entry vanishes)', () => {
    const bankNoPrefix = JSON.stringify({
      version: 1,
      maxQuestions: 12,
      interviewKeys: ['AGENT_NAME'],
      consentKeys: ['HOOKS_CONSENT', 'MCP_SCOPE'],
      questions: {
        AGENT_NAME: { maxLength: 64 },
        HOOKS_CONSENT: { consent: true, maxLength: 8 },
        MCP_SCOPE: { consent: true, phase: 'interview', question: 'Register for this folder or the whole machine?', maxLength: 8 },
      },
    });
    withFixture(
      {
        'templates/bootstrap/questions.json': bankNoPrefix,
        'templates/bootstrap/SOUL.md.template': '# {{AGENT_NAME}}\n',
        'BOOTSTRAP_FOR_AGENTS.md': `<!-- gbrain-runbook-stamp: 1.2.3.4 -->\n${RUNBOOK_PINS}`,
      },
      (dir) => {
        const r = runGuard(TPL_GUARD, dir);
        expect(r.status).toBe(1);
        expect(r.out).toContain("must start with '(Claude Code and opencode'");
      },
    );
  });
});

describe('verify + workflow wiring', () => {

  test('bootstrap guards run for documentation changes without a result-cache bypass [C2]', () => {
    const workflow = require('node:fs').readFileSync(join(ROOT, '.github/workflows/test.yml'), 'utf8');
    expect(workflow).toContain('bun run verify');
    expect(workflow).not.toContain('paths-ignore:');
    expect(workflow).not.toContain('cache-check');
  });

  test('release.yml advances latest-stable only as the final release step [C1]', () => {
    const wf = require('node:fs').readFileSync(join(ROOT, '.github/workflows/release.yml'), 'utf8');
    expect(wf).toContain('git push origin "+${RELEASE_SHA}:refs/tags/latest-stable"');
    expect(wf).toContain('RELEASE_SHA: ${{ needs.ci-gate.outputs.sha }}');
    // The advance comes AFTER the release publish step in the same job.
    expect(wf.indexOf('refs/tags/latest-stable')).toBeGreaterThan(wf.indexOf('Create release'));
  });

  test('release.yml publish-template job gates on TEMPLATE_REPO_PAT via env indirection', () => {
    const wf = require('node:fs').readFileSync(join(ROOT, '.github/workflows/release.yml'), 'utf8');
    expect(wf).toContain('publish-template:');
    expect(wf).toContain('TEMPLATE_REPO_PAT: ${{ secrets.TEMPLATE_REPO_PAT }}');
    // Secrets must never appear in an `if:` expression (unreadable there).
    for (const line of wf.split('\n')) {
      if (line.trimStart().startsWith('if:')) {
        expect(line).not.toContain('secrets.');
      }
    }
    // The byte-diff gate against the vendored tree [A1].
    expect(wf).toContain('diff -r /tmp/template-tree templates/bootstrap/template-repo');
  });

  test('heavy-tests.yml carries the bootstrap Docker e2e placeholder [A7]', () => {
    const wf = require('node:fs').readFileSync(
      join(ROOT, '.github/workflows/heavy-tests.yml'),
      'utf8',
    );
    expect(wf).toContain('tests/docker/bootstrap-e2e.sh');
  });

  test('the nightly-only Docker e2e expects the surface stdio registrations actually pin (#6049)', async () => {
    const { REGISTRATION_SURFACE, stdioServeArgv } = await import('../src/core/mcp-registration.ts');
    const { registerCodexMcp } = await import('../src/core/bootstrap/hooks.ts');
    const inner = require('node:fs').readFileSync(join(ROOT, 'tests/docker/bootstrap-e2e-inner.sh'), 'utf8');
    const expected = /^EXPECTED_SURFACE=(\S+)$/m.exec(inner)?.[1];
    expect(expected).toBe(REGISTRATION_SURFACE);
    expect(inner).toContain('grep -Fq "serve --surface $EXPECTED_SURFACE" "$GB_CODEX_STATE"');
    const [argv] = registerCodexMcp({ gbrainBin: '/opt/gbrain/bin/gbrain', sourceId: 'workspace' });
    expect(argv!.join(' ')).toContain(`serve --surface ${expected}`);
    expect(argv!.slice(-4)).toEqual(stdioServeArgv('/opt/gbrain/bin/gbrain'));
  });
});

// ── check-grok-pin.sh ────────────────────────────────────────────────────────

const GROK_PIN_GUARD = join(ROOT, 'scripts/check-grok-pin.sh');

function runGrokPinGuard(fixtureRoot: string): { status: number | null; out: string } {
  const r = spawnSync('bash', [GROK_PIN_GUARD], {
    cwd: ROOT,
    encoding: 'utf-8',
    env: { ...process.env, GBRAIN_GROK_PIN_GUARD_ROOT: fixtureRoot },
  });
  return { status: r.status, out: `${r.stdout}\n${r.stderr}` };
}

const GROK_PIN_STAMPS_NPM = [
  '<!-- grok-pin: distribution_kind=npm -->',
  '<!-- grok-pin: npm_package=@example/grok -->',
  '<!-- grok-pin: npm_version=1.0.4 -->',
  '<!-- grok-pin: npm_integrity=sha512-AAA= -->',
  '<!-- grok-pin: grok_version=1.0.4 -->',
  '<!-- grok-pin: installer_sha256=abc123 -->',
].join('\n');

function grokDoorWorkflow(envLines: string[]): string {
  return [
    'jobs:',
    '  other-job:',
    '    steps: []',
    '  grok-door:',
    '    env:',
    ...envLines.map((l) => `      ${l}`),
    '    steps: []',
    '  trailing-job:',
    '    env:',
    '      GROK_VERSION: "9.9.9"', // outside the grok-door block — must be ignored
    '    steps: []',
    '',
  ].join('\n');
}

const GROK_NPM_ENV_OK = [
  'GROK_VERSION: "1.0.4"',
  'GROK_NPM_PACKAGE: "@example/grok"',
  'GROK_NPM_INTEGRITY: "sha512-AAA="',
];

describe('check-grok-pin.sh', () => {
  test('ok: npm mode with matching workflow pins (anchored to the grok-door block)', () => {
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${GROK_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow(GROK_NPM_ENV_OK),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.out).toContain('check-grok-pin: ok');
      expect(r.status).toBe(0);
    });
  });

  test('SKIP-graceful pre-landing; FAIL-closed once the door job exists without the pin doc', () => {
    // Door job present + pin doc MISSING = the gate's source of truth was
    // deleted — that must fail, not skip (post-landing fail-closed rule).
    withFixture({
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow(GROK_NPM_ENV_OK),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('pin doc is the gate');
    });
    // No door job yet: pin doc alone is fine to skip (pre-landing posture).
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${GROK_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': 'jobs:\n  other-job:\n    steps: []\n',
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.out).toContain('SKIP');
      expect(r.status).toBe(0);
    });
  });

  test('FAIL: npm_version stamp disagreeing with grok_version can never pass green', () => {
    const stamps = GROK_PIN_STAMPS_NPM.replace(
      '<!-- grok-pin: npm_version=1.0.4 -->',
      '<!-- grok-pin: npm_version=1.0.5 -->',
    );
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${stamps}\n`,
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow(GROK_NPM_ENV_OK),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('npm_version stamp');
    });
  });

  test('single-quoted workflow env values are not read as drift', () => {
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${GROK_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow([
        "GROK_VERSION: '1.0.4'",
        "GROK_NPM_PACKAGE: '@example/grok'",
        "GROK_NPM_INTEGRITY: 'sha512-AAA='",
      ]),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.out).toContain('check-grok-pin: ok');
      expect(r.status).toBe(0);
    });
  });

  test('FAIL: workflow GROK_VERSION drifts from the grok_version stamp', () => {
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${GROK_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow([
        'GROK_VERSION: "1.0.5"',
        'GROK_NPM_PACKAGE: "@example/grok"',
        'GROK_NPM_INTEGRITY: "sha512-AAA="',
      ]),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('GROK_VERSION drift');
    });
  });

  test('FAIL: npm mode with a missing workflow integrity pin', () => {
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${GROK_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow([
        'GROK_VERSION: "1.0.4"',
        'GROK_NPM_PACKAGE: "@example/grok"',
      ]),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('missing GROK_NPM_INTEGRITY');
    });
  });

  test('FAIL: mode exclusivity — npm mode must not also pin GROK_INSTALL_SHA256 in the workflow', () => {
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${GROK_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow([
        ...GROK_NPM_ENV_OK,
        'GROK_INSTALL_SHA256: "abc123"',
      ]),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('mode exclusivity');
    });
  });

  test('FAIL: duplicate stamps in the pin doc', () => {
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${GROK_PIN_STAMPS_NPM}\n<!-- grok-pin: grok_version=1.0.5 -->\n`,
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow(GROK_NPM_ENV_OK),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('duplicate grok-pin stamp');
    });
  });

  test('installer mode: matching sha passes; npm-integrity co-pin fails exclusivity', () => {
    const installerStamps = [
      '<!-- grok-pin: distribution_kind=installer -->',
      '<!-- grok-pin: grok_version=1.0.4 -->',
      '<!-- grok-pin: installer_sha256=abc123 -->',
    ].join('\n');
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${installerStamps}\n`,
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow([
        'GROK_VERSION: "1.0.4"',
        'GROK_INSTALL_SHA256: "abc123"',
      ]),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.out).toContain('check-grok-pin: ok (installer mode');
      expect(r.status).toBe(0);
    });
    withFixture({
      'docs/mcp/GROK-CLI-PIN.md': `# pin\n${installerStamps}\n`,
      '.github/workflows/heavy-tests.yml': grokDoorWorkflow([
        'GROK_VERSION: "1.0.4"',
        'GROK_INSTALL_SHA256: "abc123"',
        'GROK_NPM_INTEGRITY: "sha512-AAA="',
      ]),
    }, (dir) => {
      const r = runGrokPinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('mode exclusivity');
    });
  });

});

// ── check-opencode-pin.sh ────────────────────────────────────────────────────

const OPENCODE_PIN_GUARD = join(ROOT, 'scripts/check-opencode-pin.sh');

function runOpencodePinGuard(fixtureRoot: string): { status: number | null; out: string } {
  const r = spawnSync('bash', [OPENCODE_PIN_GUARD], {
    cwd: ROOT,
    encoding: 'utf-8',
    env: { ...process.env, GBRAIN_OPENCODE_PIN_GUARD_ROOT: fixtureRoot },
  });
  return { status: r.status, out: `${r.stdout}\n${r.stderr}` };
}

const OPENCODE_PIN_STAMPS_NPM = [
  '<!-- opencode-pin: distribution_kind=npm -->',
  '<!-- opencode-pin: npm_package=opencode-ai -->',
  '<!-- opencode-pin: npm_version=1.18.18 -->',
  '<!-- opencode-pin: npm_integrity=sha512-BBB= -->',
  '<!-- opencode-pin: opencode_version=1.18.18 -->',
].join('\n');

function opencodeDoorWorkflow(envLines: string[]): string {
  return [
    'jobs:',
    '  other-job:',
    '    steps: []',
    '  opencode-door:',
    '    env:',
    ...envLines.map((l) => `      ${l}`),
    '    steps: []',
    '  opencode-door-canary:',
    '    env:',
    '      GBRAIN_REAL_OPENCODE_E2E: "1"', // deliberately UNPINNED — must not satisfy the check
    '    steps: []',
    '',
  ].join('\n');
}

const OPENCODE_NPM_ENV_OK = [
  'OPENCODE_VERSION: "1.18.18"',
  'OPENCODE_NPM_PACKAGE: "opencode-ai"',
  'OPENCODE_NPM_INTEGRITY: "sha512-BBB="',
];

describe('check-opencode-pin.sh', () => {
  test('ok: npm mode with matching workflow pins (anchored to the opencode-door block, canary leg ignored)', () => {
    withFixture({
      'docs/mcp/OPENCODE-CLI-PIN.md': `# pin\n${OPENCODE_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': opencodeDoorWorkflow(OPENCODE_NPM_ENV_OK),
    }, (dir) => {
      const r = runOpencodePinGuard(dir);
      expect(r.out).toContain('check-opencode-pin: ok');
      expect(r.status).toBe(0);
    });
  });

  test('SKIP-graceful pre-landing; FAIL-closed once the door job exists without the pin doc', () => {
    withFixture({
      '.github/workflows/heavy-tests.yml': opencodeDoorWorkflow(OPENCODE_NPM_ENV_OK),
    }, (dir) => {
      const r = runOpencodePinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('pin doc is the gate');
    });
    withFixture({
      'docs/mcp/OPENCODE-CLI-PIN.md': `# pin\n${OPENCODE_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': 'jobs:\n  other-job:\n    steps: []\n',
    }, (dir) => {
      const r = runOpencodePinGuard(dir);
      expect(r.out).toContain('SKIP');
      expect(r.status).toBe(0);
    });
  });

  test('FAIL: workflow OPENCODE_VERSION drifts from the opencode_version stamp', () => {
    withFixture({
      'docs/mcp/OPENCODE-CLI-PIN.md': `# pin\n${OPENCODE_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': opencodeDoorWorkflow([
        'OPENCODE_VERSION: "1.18.19"',
        'OPENCODE_NPM_PACKAGE: "opencode-ai"',
        'OPENCODE_NPM_INTEGRITY: "sha512-BBB="',
      ]),
    }, (dir) => {
      const r = runOpencodePinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('OPENCODE_VERSION drift');
    });
  });

  test('FAIL: npm_version stamp disagreeing with opencode_version can never pass green', () => {
    const stamps = OPENCODE_PIN_STAMPS_NPM.replace(
      '<!-- opencode-pin: npm_version=1.18.18 -->',
      '<!-- opencode-pin: npm_version=1.18.19 -->',
    );
    withFixture({
      'docs/mcp/OPENCODE-CLI-PIN.md': `# pin\n${stamps}\n`,
      '.github/workflows/heavy-tests.yml': opencodeDoorWorkflow(OPENCODE_NPM_ENV_OK),
    }, (dir) => {
      const r = runOpencodePinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('npm_version stamp');
    });
  });

  test('FAIL: linux platform-integrity stamps must match the job env (missing AND drifted)', () => {
    const stampsWithLinux = [
      OPENCODE_PIN_STAMPS_NPM,
      '<!-- opencode-pin: npm_linux_x64_integrity=sha512-X64= -->',
      '<!-- opencode-pin: npm_linux_arm64_integrity=sha512-ARM= -->',
    ].join('\n');
    // Missing from the job env → fail.
    withFixture({
      'docs/mcp/OPENCODE-CLI-PIN.md': `# pin\n${stampsWithLinux}\n`,
      '.github/workflows/heavy-tests.yml': opencodeDoorWorkflow(OPENCODE_NPM_ENV_OK),
    }, (dir) => {
      const r = runOpencodePinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('OPENCODE_NPM_LINUX_X64_INTEGRITY');
    });
    // Present but drifted → fail.
    withFixture({
      'docs/mcp/OPENCODE-CLI-PIN.md': `# pin\n${stampsWithLinux}\n`,
      '.github/workflows/heavy-tests.yml': opencodeDoorWorkflow([
        ...OPENCODE_NPM_ENV_OK,
        'OPENCODE_NPM_LINUX_X64_INTEGRITY: "sha512-X64="',
        'OPENCODE_NPM_LINUX_ARM64_INTEGRITY: "sha512-DRIFT="',
      ]),
    }, (dir) => {
      const r = runOpencodePinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('drift');
    });
    // Both matching → ok.
    withFixture({
      'docs/mcp/OPENCODE-CLI-PIN.md': `# pin\n${stampsWithLinux}\n`,
      '.github/workflows/heavy-tests.yml': opencodeDoorWorkflow([
        ...OPENCODE_NPM_ENV_OK,
        'OPENCODE_NPM_LINUX_X64_INTEGRITY: "sha512-X64="',
        'OPENCODE_NPM_LINUX_ARM64_INTEGRITY: "sha512-ARM="',
      ]),
    }, (dir) => {
      const r = runOpencodePinGuard(dir);
      expect(r.out).toContain('check-opencode-pin: ok');
      expect(r.status).toBe(0);
    });
  });

  test('FAIL: a second OPENCODE_VERSION copy elsewhere in the workflow disagreeing with the stamp', () => {
    // The real workflow carries a second OPENCODE_VERSION in the
    // real-agent-e2e job — every copy must move with the stamp.
    const workflow = [
      'jobs:',
      '  real-agent-e2e:',
      '    env:',
      '      OPENCODE_VERSION: "1.18.19"', // drifted second copy
      '    steps: []',
      '  opencode-door:',
      '    env:',
      ...OPENCODE_NPM_ENV_OK.map((l) => `      ${l}`),
      '    steps: []',
      '',
    ].join('\n');
    withFixture({
      'docs/mcp/OPENCODE-CLI-PIN.md': `# pin\n${OPENCODE_PIN_STAMPS_NPM}\n`,
      '.github/workflows/heavy-tests.yml': workflow,
    }, (dir) => {
      const r = runOpencodePinGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('every copy in the workflow moves with the stamp');
    });
  });
});

// ── check-pin-doc-privacy.sh ─────────────────────────────────────────────────

const PIN_PRIVACY_GUARD = join(ROOT, 'scripts/check-pin-doc-privacy.sh');

function runPinPrivacyGuard(fixtureRoot: string): { status: number | null; out: string } {
  const r = spawnSync('bash', [PIN_PRIVACY_GUARD], {
    cwd: ROOT,
    encoding: 'utf-8',
    env: { ...process.env, GBRAIN_PIN_PRIVACY_GUARD_ROOT: fixtureRoot },
  });
  return { status: r.status, out: `${r.stdout}\n${r.stderr}` };
}

describe('check-pin-doc-privacy.sh', () => {
  test('ok: placeholder-disciplined pin doc (tmp paths, sha512 pins, example.com emails)', () => {
    withFixture({
      'docs/mcp/FAKE-CLI-PIN.md': [
        '# fake pin',
        '<!-- fake-pin: npm_integrity=sha512-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA== -->',
        'Config lands at `<tmp>/.config/fake/config.json`; auth at `~/.local/share/fake/auth.json`.',
        'Support: [email protected]; probe url https://fake.invalid/mcp.',
      ].join('\n'),
    }, (dir) => {
      const r = runPinPrivacyGuard(dir);
      expect(r.out).toContain('check-pin-doc-privacy: ok');
      expect(r.status).toBe(0);
    });
  });

  test('SKIP-graceful when no pin docs exist', () => {
    withFixture({ 'docs/mcp/OTHER.md': '# not a pin doc\n' }, (dir) => {
      const r = runPinPrivacyGuard(dir);
      expect(r.out).toContain('SKIP');
      expect(r.status).toBe(0);
    });
  });

  test('FAIL: operator home path in a verbatim transcript', () => {
    withFixture({
      'docs/mcp/FAKE-CLI-PIN.md': 'observed: wrote /Users/alicesmith/.config/fake/config.json\n',
    }, (dir) => {
      const r = runPinPrivacyGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('operator home path');
    });
  });

  test('FAIL: key-shaped material outside a sha512 integrity line', () => {
    withFixture({
      'docs/mcp/FAKE-CLI-PIN.md': `observed header: Bearer sk-${'a'.repeat(24)}\n`,
    }, (dir) => {
      const r = runPinPrivacyGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('key-shaped material');
    });
  });

  test('FAIL: a real-looking email address; example.com/invalid domains stay fine', () => {
    withFixture({
      'docs/mcp/FAKE-CLI-PIN.md': 'signed in as [email protected]\n',
    }, (dir) => {
      const r = runPinPrivacyGuard(dir);
      expect(r.status).toBe(1);
      expect(r.out).toContain('email');
    });
  });
});