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.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import path from 'node:path';
import {
lockPaths,
unlockOwner,
listLocks,
sweepExpiredLocks,
pathsOverlap,
isExpired,
} from '@cobusgreyling/loop-worktree/lock';
async function freshDir() {
return mkdtemp(path.join(tmpdir(), 'loop-worktree-lock-'));
}
test('pathsOverlap: exact match, glob prefix, and distinct files', () => {
assert.equal(pathsOverlap('package.json', 'package.json'), true);
assert.equal(pathsOverlap('src/**', 'src/foo.ts'), true);
assert.equal(pathsOverlap('src/foo.ts', 'src/**'), true);
assert.equal(pathsOverlap('package.json', 'package-lock.json'), false);
});
test('pathsOverlap respects path-segment boundaries, not raw string prefixes', () => {
// A shared literal character prefix across segments must not count as overlap.
assert.equal(pathsOverlap('docs/api', 'docs/apidocs.md'), false);
assert.equal(pathsOverlap('src/foo', 'src/foobar.ts'), false);
// But a wildcard segment still covers a deeper, more specific path.
assert.equal(pathsOverlap('src/**', 'src/nested/foo.ts'), true);
});
test('lockPaths acquires a lock with no TTL by default', async () => {
const dir = await freshDir();
const entry = await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] });
assert.equal(entry.owner, 'ci-sweeper');
assert.deepEqual(entry.paths, ['package.json']);
assert.equal(entry.expiresAt, undefined);
assert.equal(isExpired(entry), false);
});
test('lockPaths sets expiresAt from --ttl', async () => {
const dir = await freshDir();
const entry = await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'], ttl: '30m' });
assert.ok(entry.expiresAt);
assert.ok(Date.parse(entry.expiresAt) > Date.now());
});
test('lockPaths rejects an overlapping path already locked by another owner', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'dependency-sweeper', paths: ['package.json', 'package-lock.json'] });
await assert.rejects(
() => lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] }),
/locked by owner "dependency-sweeper"/,
);
});
test('lockPaths allows non-overlapping paths from a different owner', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'dependency-sweeper', paths: ['package.json'] });
const entry = await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['tests/**'] });
assert.equal(entry.owner, 'ci-sweeper');
});
test('lockPaths lets the same owner re-lock (replace, not stack)', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] });
const second = await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['tests/**'] });
assert.deepEqual(second.paths, ['tests/**']);
const locks = await listLocks(dir);
assert.equal(locks.length, 1);
});
test('an expired lock no longer blocks a new lock on the same paths', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'dependency-sweeper', paths: ['package.json'], ttl: '30m' });
// Force the just-written lock into the past instead of waiting 30 minutes.
const { writeFile, readFile } = await import('node:fs/promises');
const file = path.join(dir, '.loop-worktrees', 'locks', 'dependency-sweeper.json');
const stale = JSON.parse(await readFile(file, 'utf8'));
stale.expiresAt = new Date(Date.now() - 1000).toISOString();
await writeFile(file, JSON.stringify(stale));
const entry = await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] });
assert.equal(entry.owner, 'ci-sweeper');
});
test('lockPaths rejects an owner name that would escape the locks directory', async () => {
const dir = await freshDir();
await assert.rejects(
() => lockPaths({ root: dir, owner: '../../escaped', paths: ['package.json'] }),
/Invalid --owner/,
);
});
test('unlockOwner rejects an invalid owner name the same way', async () => {
const dir = await freshDir();
await assert.rejects(() => unlockOwner(dir, '../../escaped'), /Invalid --owner/);
});
test('a corrupt lock file surfaces a clear error instead of crashing every owner', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] });
const { writeFile } = await import('node:fs/promises');
await writeFile(path.join(dir, '.loop-worktrees', 'locks', 'dependency-sweeper.json'), '{not valid json');
await assert.rejects(() => listLocks(dir), /Corrupt lock file/);
await assert.rejects(
() => lockPaths({ root: dir, owner: 'pr-babysitter', paths: ['tests/**'] }),
/Corrupt lock file/,
);
});
test('concurrent lockPaths calls on overlapping paths: exactly one wins', async () => {
const dir = await freshDir();
const owners = ['ci-sweeper', 'dependency-sweeper', 'pr-babysitter'];
const results = await Promise.allSettled(
owners.map((owner) => lockPaths({ root: dir, owner, paths: ['package.json'] })),
);
const fulfilled = results.filter((r) => r.status === 'fulfilled');
assert.equal(fulfilled.length, 1, 'exactly one racing lock call should succeed');
const locks = await listLocks(dir);
assert.equal(locks.length, 1);
});
test('unlockOwner releases a lock; is a no-op if none held', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] });
assert.equal(await unlockOwner(dir, 'ci-sweeper'), true);
assert.equal((await listLocks(dir)).length, 0);
assert.equal(await unlockOwner(dir, 'ci-sweeper'), false);
});
test('sweepExpiredLocks reports but does not delete without --force', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'], ttl: '30m' });
const { writeFile, readFile } = await import('node:fs/promises');
const file = path.join(dir, '.loop-worktrees', 'locks', 'ci-sweeper.json');
const stale = JSON.parse(await readFile(file, 'utf8'));
stale.expiresAt = new Date(Date.now() - 1000).toISOString();
await writeFile(file, JSON.stringify(stale));
const result = await sweepExpiredLocks(dir);
assert.equal(result.expired.length, 1);
assert.equal(result.removed.length, 0);
assert.equal((await listLocks(dir)).length, 1);
});
test('sweepExpiredLocks removes with --force, leaves active locks untouched', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'], ttl: '30m' });
await lockPaths({ root: dir, owner: 'dependency-sweeper', paths: ['tests/**'] });
const { writeFile, readFile } = await import('node:fs/promises');
const file = path.join(dir, '.loop-worktrees', 'locks', 'ci-sweeper.json');
const stale = JSON.parse(await readFile(file, 'utf8'));
stale.expiresAt = new Date(Date.now() - 1000).toISOString();
await writeFile(file, JSON.stringify(stale));
const result = await sweepExpiredLocks(dir, { force: true });
assert.deepEqual(result.removed, ['ci-sweeper']);
const remaining = await listLocks(dir);
assert.deepEqual(remaining.map((l) => l.owner), ['dependency-sweeper']);
});
test('lockPaths with --wait queues and acquires lock when released', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] });
// Start a wait in the background
const p = lockPaths({ root: dir, owner: 'dependency-sweeper', paths: ['package.json'], wait: '10s' });
// Ensure the wait intent is written
await new Promise(r => setTimeout(r, 50));
const { listWaits } = await import('@cobusgreyling/loop-worktree/lock');
const waits = await listWaits(dir);
assert.equal(waits.length, 1);
assert.equal(waits[0].owner, 'dependency-sweeper');
assert.deepEqual(waits[0].waitingOn, ['ci-sweeper']);
// Release the lock
await unlockOwner(dir, 'ci-sweeper');
// Background lock should now succeed
const entry = await p;
assert.equal(entry.owner, 'dependency-sweeper');
// Wait intent should be cleaned up
assert.equal((await listWaits(dir)).length, 0);
});
test('lockPaths with --wait times out', async () => {
const dir = await freshDir();
await lockPaths({ root: dir, owner: 'ci-sweeper', paths: ['package.json'] });
const start = Date.now();
await assert.rejects(
() => lockPaths({ root: dir, owner: 'dependency-sweeper', paths: ['package.json'], wait: '1s' }),
/Timed out waiting for lock on paths/
);
assert.ok(Date.now() - start >= 1000);
const { listWaits } = await import('@cobusgreyling/loop-worktree/lock');
assert.equal((await listWaits(dir)).length, 0);
});
test('lockPaths deadlock detection aborts cycle immediately', async () => {
const dir = await freshDir();
// A holds package.json
await lockPaths({ root: dir, owner: 'A', paths: ['package.json'] });
// B holds src/**
await lockPaths({ root: dir, owner: 'B', paths: ['src/**'] });
// A wants src/** and waits on B
const pA = lockPaths({ root: dir, owner: 'A', paths: ['src/**'], wait: '10s' });
await new Promise(r => setTimeout(r, 50));
// B wants package.json and waits on A - this should throw DeadlockError immediately
await assert.rejects(
() => lockPaths({ root: dir, owner: 'B', paths: ['package.json'], wait: '10s' }),
/Deadlock detected: B -> A -> B/
);
// A is still waiting, release B so A can finish
await unlockOwner(dir, 'B');
await pA;
});