Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

14.0 KB
Raw Blame
import test from 'node:test';
import assert from 'node:assert';
import { runInSandbox, listPatches } from '../dist/sandbox.js';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { tmpdir } from 'node:os';
import { mkdir, rm, writeFile, stat, readFile, readdir } from 'node:fs/promises';
import { execSync, spawn } from 'node:child_process';
import { createWorktree } from '@cobusgreyling/loop-worktree';
import { lockPaths, listLocks } from '@cobusgreyling/loop-worktree/lock';

const testDir = path.dirname(fileURLToPath(import.meta.url));
const sandboxDistUrl = pathToFileURL(path.join(testDir, '../dist/sandbox.js')).href;

/** Captures console.log lines produced while `fn` runs, restoring console.log afterward even if fn throws. */
async function captureLogs(fn) {
  const lines = [];
  const original = console.log;
  console.log = (...args) => { lines.push(args.join(' ')); };
  try {
    await fn();
  } finally {
    console.log = original;
  }
  return lines;
}

async function setupTestRepo() {
  const dir = path.join(tmpdir(), `sandbox-test-${Date.now()}-${Math.floor(Math.random()*1000)}`);
  await mkdir(dir, { recursive: true });
  execSync('git init -b main', { cwd: dir });
  execSync('git config user.name "Test"', { cwd: dir });
  execSync('git config user.email "[email protected]"', { cwd: dir });
  await writeFile(path.join(dir, 'README.md'), '# Test repo');
  execSync('git add README.md', { cwd: dir });
  execSync('git commit -m "init"', { cwd: dir });
  return dir;
}

test('sandbox run captures patch and cleans up', async () => {
  const root = await setupTestRepo();
  const scriptPath = path.join(root, 'test-script.js');
  await writeFile(scriptPath, 'require("fs").writeFileSync("new-file.txt", "hello sandbox");');
  try {
    const result = await runInSandbox(root, 'node', [scriptPath]);
    
    assert.ok(result.hasChanges);
    assert.ok(result.patchFile);
    assert.equal(result.exitCode, 0);

    const patchStat = await stat(result.patchFile);
    assert.ok(patchStat.size > 0);

    await assert.rejects(stat(path.join(root, 'new-file.txt')));

    const patches = await listPatches(root);
    assert.equal(patches.length, 1);
    assert.equal(patches[0].patchPath, result.patchFile);

  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});

test('cleanup is scoped and leaves other active worktrees alone', async () => {
  const root = await setupTestRepo();
  try {
    // Pre-create an active worktree via loop-worktree API
    const other = await createWorktree({ root, runId: 'other-run', pattern: 'test', base: 'main' });
    const otherPathAbs = path.join(root, other.path);
    await stat(otherPathAbs); // verifies it exists
    
    // Run sandbox
    const result = await runInSandbox(root, 'node', ['-e', 'require("fs").writeFileSync("foo.txt", "bar");']);
    assert.ok(result.hasChanges);
    
    // Verify the other worktree STILL exists
    await stat(otherPathAbs);
  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});

test('extract failure prevents cleanup to avoid data loss', async () => {
  const root = await setupTestRepo();
  try {
    // Sabotage git by deleting the worktree's metadata inside the parent repo.
    // This makes git add -A fail because the worktree is completely broken.
    const result = await runInSandbox(root, 'node', [
      '-e', 
      'const fs = require("fs"); const gitdir = fs.readFileSync(".git", "utf8").trim().replace("gitdir: ", ""); fs.rmSync(gitdir, {recursive: true, force: true});'
    ]);
    
    assert.equal(result.hasChanges, false);
    
    // The worktree branch and directory should still be on disk
    const statObj = await stat(path.join(root, '.loop-worktrees', result.runId));
    assert.ok(statObj.isDirectory(), 'worktree should remain on disk');
    
  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});

test('binary patch captures exactly without utf8 corruption', async () => {
  const root = await setupTestRepo();
  try {
    // Write a binary sequence
    const scriptPath = path.join(root, 'binary-script.js');
    await writeFile(scriptPath, 'require("fs").writeFileSync("binary.bin", Buffer.from([0x00, 0xFF, 0xFE, 0xFD]));');
    
    const result = await runInSandbox(root, 'node', [scriptPath]);
    assert.ok(result.hasChanges);
    
    const patchContent = await readFile(result.patchFile);
    assert.ok(patchContent.toString('ascii').includes('GIT binary patch'));
    
    // Apply the patch to the main repo
    execSync(`git apply ${result.patchFile}`, { cwd: root });
    
    // Verify exact bytes
    const appliedContent = await readFile(path.join(root, 'binary.bin'));
    assert.equal(appliedContent[0], 0x00);
    assert.equal(appliedContent[1], 0xFF);
    assert.equal(appliedContent[2], 0xFE);
    assert.equal(appliedContent[3], 0xFD);
  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});

test('lockPaths option holds and releases a loop-worktree lock around the run', async () => {
  const root = await setupTestRepo();
  try {
    let result;
    const logs = await captureLogs(async () => {
      result = await runInSandbox(root, 'node', ['-e', 'require("fs").writeFileSync("locked.txt", "x");'], {
        lockPaths: ['src/**'],
        lockOwner: 'lock-test-owner',
      });
    });
    assert.ok(result.hasChanges);

    // The lock must be released once the run completes -- otherwise it would
    // strand future loops out of src/** indefinitely with no TTL set.
    const locks = await listLocks(root);
    assert.equal(locks.length, 0);

    // A lock was actually acquired and released here, so the release message
    // must be printed -- this is the positive case for the "don't claim a
    // release that didn't happen" fix below.
    assert.ok(
      logs.some((l) => l.includes('Released lock held by "lock-test-owner"')),
      `expected a release message when a lock actually was released, got: ${JSON.stringify(logs)}`,
    );
  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});

test('lockPaths option refuses to run when another owner holds an overlapping lock', async () => {
  const root = await setupTestRepo();
  try {
    await lockPaths({ root, owner: 'other-loop', paths: ['src/**'] });

    const logs = await captureLogs(async () => {
      await assert.rejects(
        runInSandbox(root, 'node', ['-e', 'require("fs").writeFileSync("should-not-run.txt", "x");'], {
          lockPaths: ['src/nested/**'],
          lockOwner: 'sandbox-test-owner',
        }),
        /locked by owner "other-loop"/,
      );
    });

    // Blocked before the worktree was ever created -- nothing to clean up.
    const worktreeList = execSync('git worktree list --porcelain', { cwd: root, encoding: 'utf8' });
    assert.equal(worktreeList.match(/^worktree /gm)?.length, 1, 'only the main worktree should exist');
    // The other loop's lock is untouched by the rejected attempt.
    const locks = await listLocks(root);
    assert.equal(locks.length, 1);
    assert.equal(locks[0].owner, 'other-loop');

    // lockPaths() never acquired anything for "sandbox-test-owner" here (it
    // threw before writing a lock file), so cleanup() must not claim it
    // released a lock that was never held.
    assert.ok(
      !logs.some((l) => /Releasing lock|Released lock/.test(l)),
      `must not print a lock-release message when no lock was ever acquired, got: ${JSON.stringify(logs)}`,
    );
  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});

test('lockPaths option holds the lock while the run is still in progress, not just after', async () => {
  const root = await setupTestRepo();
  try {
    const startedMarker = path.join(root, 'started.txt');
    const goMarker = path.join(root, 'go.txt');

    const runPromise = runInSandbox(root, 'node', [
      '-e',
      `require("fs").writeFileSync(${JSON.stringify(startedMarker)}, "x");` +
        `const iv = setInterval(() => { if (require("fs").existsSync(${JSON.stringify(goMarker)})) { clearInterval(iv); process.exit(0); } }, 50);`,
    ], { lockPaths: ['src/**'], lockOwner: 'midrun-owner' });

    while (!(await stat(startedMarker).catch(() => null))) {
      await new Promise((resolve) => setTimeout(resolve, 50));
    }

    // The lock must be visible while the sandboxed command is still running,
    // not only after runInSandbox() resolves.
    const locksMidRun = await listLocks(root);
    assert.equal(locksMidRun.length, 1);
    assert.equal(locksMidRun[0].owner, 'midrun-owner');

    await writeFile(goMarker, 'go');
    await runPromise;

    const locksAfter = await listLocks(root);
    assert.equal(locksAfter.length, 0);
  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});

test('lock is released even when patch extraction fails and the worktree is left behind', async () => {
  const root = await setupTestRepo();
  try {
    const result = await runInSandbox(root, 'node', [
      '-e',
      'const fs = require("fs"); const gitdir = fs.readFileSync(".git", "utf8").trim().replace("gitdir: ", ""); fs.rmSync(gitdir, {recursive: true, force: true});',
    ], { lockPaths: ['src/**'], lockOwner: 'extract-fail-owner' });

    assert.equal(result.hasChanges, false);

    // The worktree is deliberately left on disk for manual recovery when
    // extraction fails...
    const statObj = await stat(path.join(root, '.loop-worktrees', result.runId));
    assert.ok(statObj.isDirectory(), 'worktree should remain on disk');

    // ...but lock release has nothing to do with whether patch extraction
    // succeeded, so it must still happen.
    const locks = await listLocks(root);
    assert.equal(locks.length, 0);
  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});

test('a second SIGINT while cleanup is in flight does not exit before the lock is released', async () => {
  const root = await setupTestRepo();
  try {
    // Same self-emitting-SIGINT approach as the test above, but fires SIGINT
    // twice in quick succession. The bug this guards against: the first cut
    // re-ran cleanup() on every signal and let a boolean guard turn repeat
    // calls into instant no-ops, so the *second* signal's
    // `.finally(() => process.exit(1))` could fire before the *first*
    // signal's cleanup (lock release, worktree removal) ever finished.
    const child = spawn(process.execPath, ['--input-type=module', '-e', `
      const mod = await import(${JSON.stringify(sandboxDistUrl)});
      mod.runInSandbox(${JSON.stringify(root)}, 'node', ['-e', 'setInterval(() => {}, 1000)'], {
        lockPaths: ['src/**'],
        lockOwner: 'double-sigint-owner',
      }).catch(() => {});
      setTimeout(() => process.emit('SIGINT'), 1000);
      setTimeout(() => process.emit('SIGINT'), 1030);
    `], { stdio: 'ignore' });

    const exited = await new Promise((resolve, reject) => {
      const timer = setTimeout(() => resolve(false), 10_000);
      child.on('exit', () => { clearTimeout(timer); resolve(true); });
      child.on('error', (err) => { clearTimeout(timer); reject(err); });
    });
    if (!exited) {
      child.kill('SIGKILL');
      assert.fail('child did not exit after a double synthetic SIGINT within 10s -- the lock is likely stranded');
    }

    const locks = await listLocks(root);
    assert.equal(locks.length, 0, 'a second SIGINT during cleanup must not exit before the lock is released');

    // The lock release itself is a fast fs.unlink and tends to finish inside
    // the race window regardless of this bug -- the sharper signal is
    // whether the *slower* worktree teardown (spawns `git worktree remove`)
    // also got to finish. Under the old guard-based cleanup, the second
    // signal's process.exit() could cut that off mid-flight and leave a
    // `sandbox-*` directory behind under .loop-worktrees (confirmed by
    // reproducing this against the pre-fix code before writing this test).
    const worktreeEntries = await readdir(path.join(root, '.loop-worktrees')).catch(() => []);
    assert.ok(
      !worktreeEntries.some((name) => name.startsWith('sandbox-')),
      `worktree cleanup must finish even under a double signal, found: ${worktreeEntries.join(', ')}`,
    );
  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});

test('SIGINT mid-run releases the lock instead of stranding it', async () => {
  const root = await setupTestRepo();
  try {
    // Run in a dedicated child process and self-trigger SIGINT via
    // process.emit from inside it -- real OS signal delivery to a spawned
    // process is unreliable to script from a test (especially on Windows),
    // but process.emit('SIGINT') exercises the exact same registered
    // listener a real signal would, without that flakiness. The sandboxed
    // "user command" (setInterval) never exits on its own, so this also
    // covers cleanup() running while the child it's meant to clean up after
    // is still alive.
    const child = spawn(process.execPath, ['--input-type=module', '-e', `
      const mod = await import(${JSON.stringify(sandboxDistUrl)});
      mod.runInSandbox(${JSON.stringify(root)}, 'node', ['-e', 'setInterval(() => {}, 1000)'], {
        lockPaths: ['src/**'],
        lockOwner: 'sigint-test-owner',
      }).catch(() => {});
      setTimeout(() => process.emit('SIGINT'), 1000);
    `], { stdio: 'ignore' });

    const exited = await new Promise((resolve, reject) => {
      const timer = setTimeout(() => resolve(false), 10_000);
      child.on('exit', () => { clearTimeout(timer); resolve(true); });
      child.on('error', (err) => { clearTimeout(timer); reject(err); });
    });
    if (!exited) {
      child.kill('SIGKILL');
      assert.fail('child did not exit after synthetic SIGINT within 10s -- the lock is likely stranded');
    }

    const locks = await listLocks(root);
    assert.equal(locks.length, 0, 'lock must be released after SIGINT, not left stranded with no TTL');
  } finally {
    await rm(root, { recursive: true, force: true }).catch(() => {});
  }
});