Merge remote-tracking branch 'origin/main' into garrytan/codex-review-default-on

test/dev-setup-render-isolation.test.ts

@@ -0,0 +1,91 @@
+import { describe, test, expect } from 'bun:test';
+import * as path from 'path';
+import * as fs from 'fs';
+
+// Static tripwires for the B2 render-isolation wiring. These fail CI if a
+// refactor drops a load-bearing line, re-introducing the "dev-setup dirties
+// tracked SKILL.md" drift (or worse, leaks the skip-guard into real installs).
+const ROOT = path.resolve(import.meta.dir, '..');
+const read = (rel: string) => fs.readFileSync(path.join(ROOT, rel), 'utf-8');
+
+describe('dev-setup: worktree stays canonical', () => {
+  const devSetup = read('bin/dev-setup');
+
+  test('passes GSTACK_SKIP_GBRAIN_REGEN inline on the nested setup call', () => {
+    expect(devSetup).toContain('GSTACK_SKIP_GBRAIN_REGEN=1 "$GSTACK_LINK/setup"');
+  });
+
+  test('never exports GSTACK_SKIP_GBRAIN_REGEN (would leak into other setup paths)', () => {
+    expect(devSetup).not.toMatch(/export\s+GSTACK_SKIP_GBRAIN_REGEN/);
+  });
+
+  test('renders the :user variant into an out-dir, not in place', () => {
+    expect(devSetup).toContain('--out-dir');
+    expect(devSetup).toContain('.claude/gstack-rendered');
+  });
+
+  test('gates the render on gstack-gbrain-detect --is-ok', () => {
+    expect(devSetup).toContain('--is-ok');
+  });
+});
+
+describe('setup: honors GSTACK_SKIP_GBRAIN_REGEN', () => {
+  const setup = read('setup');
+
+  test('skips the in-place :user regen when the guard is set', () => {
+    expect(setup).toContain('${GSTACK_SKIP_GBRAIN_REGEN:-}');
+    // The guard must wrap the in-place render, not the detection persist.
+    const idx = setup.indexOf('GSTACK_SKIP_GBRAIN_REGEN');
+    const after = setup.slice(idx, idx + 600);
+    expect(after).toContain('leaving tracked SKILL.md canonical');
+  });
+
+  test('uses a PID-unique detection tmp (no concurrent clobber)', () => {
+    expect(setup).toContain('$DETECTION_FILE.$$.tmp');
+  });
+
+  test('gates detection on the shared --is-ok check', () => {
+    expect(setup).toContain('"$DETECT_BIN" --is-ok');
+  });
+});
+
+describe('gen-skill-docs: section rewrite is gated on --out-dir', () => {
+  const gen = read('scripts/gen-skill-docs.ts');
+
+  test('rewriteSectionBase is a no-op without --out-dir', () => {
+    expect(gen).toContain('function rewriteSectionBase');
+    const idx = gen.indexOf('function rewriteSectionBase');
+    const body = gen.slice(idx, idx + 400);
+    expect(body).toContain('if (!OUT_DIR) return content');
+    expect(body).toContain('sections'); // surgical: regex targets only /sections/ paths
+  });
+});
+
+describe('dev-teardown: removes the untracked render', () => {
+  const teardown = read('bin/dev-teardown');
+
+  test('rm -rf the gstack-rendered dir', () => {
+    expect(teardown).toContain('gstack-rendered');
+    expect(teardown).toMatch(/rm -rf .*RENDER_DIR/);
+  });
+});
+
+describe('.gitignore: render dir is declared untracked', () => {
+  test('.claude/gstack-rendered/ is ignored', () => {
+    expect(read('.gitignore')).toContain('.claude/gstack-rendered/');
+  });
+});
+
+describe('dev-skill: refreshes the render on template change', () => {
+  const devSkill = read('scripts/dev-skill.ts');
+
+  test('re-renders the :user variant into the workspace render dir', () => {
+    expect(devSkill).toContain('gstack-rendered');
+    expect(devSkill).toContain('--out-dir');
+    expect(devSkill).toContain('--respect-detection');
+  });
+
+  test('only refreshes when the render dir already exists (never creates it during plain dev)', () => {
+    expect(devSkill).toContain('fs.existsSync(RENDER_DIR)');
+  });
+});

test/gbrain-detect-shape.test.ts

@@ -16,7 +16,7 @@
  */
 
 import { describe, it, expect } from "bun:test";
-import { execFileSync } from "child_process";
+import { execFileSync, spawnSync } from "child_process";
 import {
   mkdtempSync,
   mkdirSync,
@@ -47,6 +47,16 @@ function runDetect(env: Partial<NodeJS.ProcessEnv>): string {
   });
 }
 
+/** Run detect with --is-ok and return its exit code (never throws). */
+function runIsOk(env: Partial<NodeJS.ProcessEnv>): number {
+  const r = spawnSync(BUN_BIN, ["run", DETECT_BIN, "--is-ok"], {
+    timeout: 15_000,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, ...env },
+  });
+  return r.status ?? 1;
+}
+
 interface DetectShape {
   gbrain_on_path: boolean;
   gbrain_version: string | null;
@@ -244,3 +254,66 @@ exit 0
     }
   });
 });
+
+describe("bin/gstack-gbrain-detect --is-ok — live gate", () => {
+  it("exits non-zero when gbrain is not on PATH (no-cli)", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "detect-isok-"));
+    try {
+      const code = runIsOk({
+        HOME: tmp,
+        PATH: "/usr/bin:/bin", // no gbrain
+        GSTACK_HOME: tmp,
+        GSTACK_DETECT_NO_CACHE: "1",
+      });
+      expect(code).not.toBe(0);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("exits 0 when a fake gbrain reports a healthy engine (ok)", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "detect-isok-"));
+    const bindir = join(tmp, "bin");
+    const home = join(tmp, "home");
+    const configDir = join(home, ".gbrain");
+    try {
+      mkdirSync(bindir, { recursive: true });
+      mkdirSync(configDir, { recursive: true });
+      writeFileSync(join(configDir, "config.json"), JSON.stringify({ engine: "pglite" }));
+      const fake = `#!/bin/sh
+case "$1 $2" in
+  "--version ")        echo "gbrain 0.33.1.0"; exit 0 ;;
+  "sources list")      echo '{"sources":[]}'; exit 0 ;;
+  "doctor "*)          echo '{"status":"ok","checks":[]}'; exit 0 ;;
+esac
+exit 0
+`;
+      const gbrainPath = join(bindir, "gbrain");
+      writeFileSync(gbrainPath, fake);
+      chmodSync(gbrainPath, 0o755);
+
+      const code = runIsOk({
+        HOME: home,
+        PATH: `${bindir}:/usr/bin:/bin`,
+        GSTACK_HOME: tmp,
+        GSTACK_DETECT_NO_CACHE: "1",
+      });
+      expect(code).toBe(0);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("exit code agrees with the JSON gbrain_local_status (no skew)", () => {
+    // Run both surfaces against the same env and assert they never disagree.
+    const tmp = mkdtempSync(join(tmpdir(), "detect-isok-"));
+    try {
+      const env = { HOME: tmp, PATH: "/usr/bin:/bin", GSTACK_HOME: tmp, GSTACK_DETECT_NO_CACHE: "1" };
+      const status = (JSON.parse(runDetect(env)) as DetectShape).gbrain_local_status;
+      const code = runIsOk(env);
+      expect(code === 0).toBe(status === "ok");
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

test/gbrain-refresh-install-render.test.ts

@@ -0,0 +1,60 @@
+import { describe, test, expect } from 'bun:test';
+import * as path from 'path';
+import * as fs from 'fs';
+
+// Static tripwires for the C (machine-wide) render in `gstack-config
+// gbrain-refresh`. The render mutates the shared global install, so the guards
+// that stop it from touching the wrong directory are load-bearing — these fail
+// CI if any guard is dropped.
+const ROOT = path.resolve(import.meta.dir, '..');
+const SRC = fs.readFileSync(path.join(ROOT, 'bin', 'gstack-config'), 'utf-8');
+
+// Pull out just the gbrain-refresh `ok)` branch so assertions can't be
+// satisfied by unrelated text elsewhere in the file.
+function okBranch(): string {
+  const start = SRC.indexOf('gbrain-refresh)');
+  const ok = SRC.indexOf('ok)', start);
+  const end = SRC.indexOf(';;', ok);
+  if (start < 0 || ok < 0 || end < 0) throw new Error('Could not locate gbrain-refresh ok) branch');
+  return SRC.slice(ok, end);
+}
+
+describe('gstack-config gbrain-refresh: machine-wide render guards', () => {
+  const branch = okBranch();
+
+  test('targets the global install', () => {
+    expect(branch).toContain('$HOME/.claude/skills/gstack');
+  });
+
+  test('refuses a symlinked install (would dirty a dev worktree)', () => {
+    expect(branch).toMatch(/\[ -L "\$INSTALL_DIR" \]/);
+  });
+
+  test('verifies it is a real gstack clone before mutating it', () => {
+    expect(branch).toContain('$INSTALL_DIR/VERSION');
+    expect(branch).toContain('$INSTALL_DIR/package.json');
+  });
+
+  test('requires bun on PATH', () => {
+    expect(branch).toContain('command -v bun');
+  });
+
+  test('renders the :user variant in place into the install', () => {
+    expect(branch).toContain('gen:skill-docs:user --host claude');
+  });
+
+  test('is self-documenting about the reset --hard / re-run cycle', () => {
+    expect(branch).toContain('reset --hard');
+    expect(branch).toContain('gbrain-refresh');
+  });
+});
+
+describe('CLAUDE.md: deploy section documents the re-run', () => {
+  test('notes re-running gbrain-refresh after reset --hard', () => {
+    const claudeMd = fs.readFileSync(path.join(ROOT, 'CLAUDE.md'), 'utf-8');
+    const idx = claudeMd.indexOf('## Deploying to the active skill');
+    expect(idx).toBeGreaterThan(-1);
+    const section = claudeMd.slice(idx, idx + 1200);
+    expect(section).toContain('gbrain-refresh');
+  });
+});

test/gen-skill-docs-out-dir.test.ts

@@ -0,0 +1,84 @@
+import { describe, test, expect } from 'bun:test';
+import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+
+const ROOT = path.resolve(import.meta.dir, '..');
+
+// Render the gbrain `:user` variant into a temp out-dir, forcing detection ON
+// via a crafted GSTACK_HOME so the test is deterministic regardless of whether
+// the dev machine actually has gbrain installed. Asserts the B2 contract:
+//   (a) the worktree SKILL.md is byte-unchanged (source stays canonical),
+//   (b) the out-dir SKILL.md gained the inline Brain Context Load block,
+//   (c) its section refs point at the out-dir, not ~/.claude/skills/gstack,
+//   (d) bin/ refs are left pointing at the global install,
+//   (e) the out-dir section file gained the Save Results to Brain block.
+describe('gen-skill-docs --out-dir (B2 render isolation)', () => {
+  function hashFile(p: string): string {
+    return createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+  }
+
+  test('renders :user to out-dir, rewrites section paths, leaves worktree canonical', () => {
+    const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-home-'));
+    const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-out-'));
+    const worktreeSkill = path.join(ROOT, 'ship', 'SKILL.md');
+    const beforeHash = hashFile(worktreeSkill);
+    try {
+      // Force gbrain detection ON for --respect-detection.
+      fs.writeFileSync(
+        path.join(tmpHome, 'gbrain-detection.json'),
+        JSON.stringify({ gbrain_local_status: 'ok', gbrain_version: '9.9.9' }),
+      );
+
+      const res = spawnSync(
+        'bun',
+        ['run', 'scripts/gen-skill-docs.ts', '--respect-detection', '--host', 'claude', '--out-dir', outDir],
+        { cwd: ROOT, encoding: 'utf-8', timeout: 120_000, env: { ...process.env, GSTACK_HOME: tmpHome } },
+      );
+      expect(res.status).toBe(0);
+
+      const outSkill = path.join(outDir, 'ship', 'SKILL.md');
+      const outSection = path.join(outDir, 'ship', 'sections', 'adversarial.md');
+      expect(fs.existsSync(outSkill)).toBe(true);
+      const skillContent = fs.readFileSync(outSkill, 'utf-8');
+
+      // (a) worktree byte-unchanged
+      expect(hashFile(worktreeSkill)).toBe(beforeHash);
+
+      // (b) inline block present in the rendered SKILL.md
+      expect(skillContent).toContain('Brain Context Load');
+
+      // (c) section refs repointed to the out-dir; none left pointing at the install
+      expect(skillContent).toContain(`${outDir}/ship/sections/`);
+      expect(skillContent).not.toContain('~/.claude/skills/gstack/ship/sections/');
+
+      // (d) bin refs are NOT rewritten — they still resolve to the global install
+      expect(skillContent).toContain('~/.claude/skills/gstack/bin/');
+
+      // (e) the SAVE block landed in the rendered section file
+      expect(fs.existsSync(outSection)).toBe(true);
+      expect(fs.readFileSync(outSection, 'utf-8')).toContain('Save Results to Brain');
+    } finally {
+      fs.rmSync(tmpHome, { recursive: true, force: true });
+      fs.rmSync(outDir, { recursive: true, force: true });
+    }
+  });
+
+  test('global extras (proactive-suggestions.json) are NOT written in out-dir mode', () => {
+    const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-out-'));
+    try {
+      const res = spawnSync(
+        'bun',
+        ['run', 'scripts/gen-skill-docs.ts', '--host', 'claude', '--out-dir', outDir],
+        { cwd: ROOT, encoding: 'utf-8', timeout: 120_000 },
+      );
+      expect(res.status).toBe(0);
+      // proactive-suggestions.json lives at a repo path; out-dir mode must skip it.
+      expect(fs.existsSync(path.join(outDir, 'scripts', 'proactive-suggestions.json'))).toBe(false);
+    } finally {
+      fs.rmSync(outDir, { recursive: true, force: true });
+    }
+  });
+});