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, describe, beforeEach, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import path from 'node:path';
import { mkdir, writeFile, rm, readFile, access } from 'node:fs/promises';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import { runSync, formatReport, extractFrontmatter } from '../dist/sync.js';
const testDir = path.join(process.cwd(), '.test-tmp');
const exec = promisify(execFile);
const CLI = path.resolve('dist/cli.js');
async function setupTestDir() {
await mkdir(testDir, { recursive: true });
await writeFile(
path.join(testDir, 'STATE.md'),
`# Loop State
Last run: 2026-06-22
## High Priority
- No items
## Watch List
- No items
`,
);
await writeFile(
path.join(testDir, 'LOOP.md'),
`# Loop Configuration
## Patterns
- daily-triage
## State Files
- STATE.md
## Schedule
- Cadence: 1d
- Level: L1
`,
);
}
async function cleanupTestDir() {
await rm(testDir, { recursive: true, force: true });
}
const baseOpts = { autoFix: false, dryRun: false, verbose: false };
describe('runSync', () => {
beforeEach(setupTestDir);
afterEach(cleanupTestDir);
test('returns a valid DriftReport', async () => {
const report = await runSync({ targetDir: testDir, ...baseOpts });
assert.equal(typeof report.score, 'number');
assert.ok(['healthy', 'warning', 'critical'].includes(report.level));
assert.ok(Array.isArray(report.issues));
assert.ok(Array.isArray(report.suggestions));
assert.ok(report.timestamp);
});
test('detects missing AGENTS.md', async () => {
const report = await runSync({ targetDir: testDir, ...baseOpts });
const agentsIssue = report.issues.find((i) => i.file === 'AGENTS.md');
assert.ok(agentsIssue);
assert.match(agentsIssue.message, /missing/i);
});
test('calculates score in range', async () => {
const report = await runSync({ targetDir: testDir, ...baseOpts });
assert.ok(report.score >= 0);
assert.ok(report.score <= 100);
});
test('provides suggestions', async () => {
const report = await runSync({ targetDir: testDir, ...baseOpts });
assert.ok(report.suggestions.length > 0);
});
});
describe('runSync auto-fix', () => {
const fixDir = path.join(process.cwd(), '.test-tmp-autofix');
beforeEach(() => mkdir(fixDir, { recursive: true }));
afterEach(() => rm(fixDir, { recursive: true, force: true }));
test('scaffolds STATE.md, gate.yaml, loop-budget.md, and loop-run-log.md when missing', async () => {
const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: false, verbose: false });
for (const file of ['STATE.md', 'gate.yaml', 'loop-budget.md', 'loop-run-log.md']) {
const content = await readFile(path.join(fixDir, file), 'utf8');
assert.ok(content.length > 0, `${file} should have been scaffolded with content`);
const issue = report.issues.find((i) => i.file === file);
assert.equal(issue.severity, 'info');
assert.match(issue.message, /scaffolded/i);
}
// loop-run-log.md must keep the marker append-run-log.mjs depends on.
const runLog = await readFile(path.join(fixDir, 'loop-run-log.md'), 'utf8');
assert.match(runLog, /<!-- Loop appends below this line -->/);
// A bare pattern like ".env" only matches a path exactly equal to
// ".env" under minimatch (tools/loop-gate's matcher) -- it silently
// misses "services/api/.env". Every denylist entry must be
// **/-anchored (or already contain its own ** segment) so the
// scaffolded policy actually catches a nested match too.
const gateYaml = await readFile(path.join(fixDir, 'gate.yaml'), 'utf8');
const denylistBlock = gateYaml.match(/denylist:\n((?:\s+-\s+.+\n)+)/)?.[1] ?? '';
const entries = [...denylistBlock.matchAll(/-\s+"([^"]+)"/g)].map((m) => m[1]);
assert.ok(entries.length > 0, 'expected at least one denylist entry to check');
for (const entry of entries) {
assert.ok(
entry.startsWith('**/') || entry.includes('**'),
`denylist entry "${entry}" is not anchored and would miss a nested match`,
);
}
});
test('does not fabricate LOOP.md or AGENTS.md -- still reported as missing', async () => {
const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: false, verbose: false });
assert.equal(await fileExists(path.join(fixDir, 'LOOP.md')), false);
assert.equal(await fileExists(path.join(fixDir, 'AGENTS.md')), false);
const loopIssue = report.issues.find((i) => i.file === 'LOOP.md');
assert.equal(loopIssue.severity, 'error');
assert.match(loopIssue.suggestion, /loop-init/);
});
test('--dry-run with --auto-fix reports without writing anything', async () => {
const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: true, verbose: false });
assert.equal(await fileExists(path.join(fixDir, 'STATE.md')), false);
const issue = report.issues.find((i) => i.file === 'STATE.md');
assert.match(issue.message, /would scaffold/i);
assert.match(issue.message, /dry-run/i);
});
test('appends a STATE.md reference to LOOP.md when missing', async () => {
await writeFile(path.join(fixDir, 'STATE.md'), '# Loop State\n');
await writeFile(
path.join(fixDir, 'LOOP.md'),
`# Loop Configuration\n\n## Patterns\n- daily-triage\n`,
);
const report = await runSync({ targetDir: fixDir, autoFix: true, dryRun: false, verbose: false });
const loopContent = await readFile(path.join(fixDir, 'LOOP.md'), 'utf8');
assert.match(loopContent, /Update STATE\.md after each run\./);
const issue = report.issues.find((i) => i.file === 'LOOP.md' && i.type === 'inconsistent');
assert.equal(issue.severity, 'info');
assert.match(issue.message, /appended a reference/i);
});
});
function fileExists(p) {
return access(p).then(() => true, () => false);
}
describe('formatReport', () => {
test('formats healthy report', () => {
const formatted = formatReport({
score: 85,
level: 'healthy',
issues: [],
suggestions: ['Run loop-init'],
timestamp: new Date().toISOString(),
});
assert.match(formatted, /Loop Sync Report/);
assert.match(formatted, /85\/100/);
});
test('shows issues when present', () => {
const formatted = formatReport({
score: 60,
level: 'warning',
issues: [
{
type: 'missing',
file: 'AGENTS.md',
message: 'AGENTS.md is missing',
severity: 'error',
},
],
suggestions: [],
timestamp: new Date().toISOString(),
});
assert.match(formatted, /AGENTS\.md/);
assert.match(formatted, /missing/i);
});
});
describe('extractFrontmatter', () => {
test('parses LF frontmatter', () => {
const { frontmatter, body } = extractFrontmatter(
'---\nkey: value\n---\nbody text\n',
);
assert.deepEqual(frontmatter, { key: 'value' });
assert.equal(body, 'body text\n');
});
test('parses CRLF frontmatter without trailing carriage returns', () => {
const { frontmatter, body } = extractFrontmatter(
'---\r\nkey: value\r\nother: thing\r\n---\r\nbody text\r\n',
);
assert.deepEqual(frontmatter, { key: 'value', other: 'thing' });
assert.ok(!Object.values(frontmatter).some((v) => v.endsWith('\r')));
assert.ok(!Object.keys(frontmatter).some((k) => k.endsWith('\r')));
assert.equal(body, 'body text\r\n');
});
test('rejects opening fence without newline (---hello)', () => {
const { frontmatter } = extractFrontmatter('---hello\nkey: value\n---\n');
assert.deepEqual(frontmatter, {});
});
test('rejects closing fence without preceding newline', () => {
const { frontmatter } = extractFrontmatter('---\nkey: value\n---oops\n');
assert.deepEqual(frontmatter, {});
});
});
describe('cli', () => {
beforeEach(setupTestDir);
afterEach(cleanupTestDir);
test('emits JSON when --json is provided', async () => {
let stdout;
try {
({ stdout } = await exec('node', [CLI, testDir, '--json']));
} catch (err) {
stdout = err.stdout;
assert.equal(err.code, 1);
}
const report = JSON.parse(stdout);
assert.equal(typeof report.score, 'number');
assert.ok(['healthy', 'warning', 'critical'].includes(report.level));
assert.ok(Array.isArray(report.issues));
assert.ok(Array.isArray(report.suggestions));
});
});