Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Tests for the shared rules-block writer (plan K1, t_ba41a78a / t_1e952e43).
*
* One writer owns every byte written into a vault-root agent rules file
* through marker fences: the installer writes the `usage` block, the
* lessons lane promotes into the `lessons` block. The suite pins the
* writer invariants that make the two producers safe to share one file:
* operator bytes outside the block are preserved, re-apply is a byte
* no-op, line endings survive, the exclusive-create backup is taken once,
* hand-edited blocks refuse, and every malformed-marker shape is a named
* refusal that wraps the editor's own error.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
existsSync,
lstatSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
symlinkSync,
utimesSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
DEFAULT_BEGIN_MARKER,
DEFAULT_END_MARKER,
ManagedBlockError,
} from "../../../src/core/install/managed-block.ts";
import { fileMatchesExpected } from "../../../src/core/fs-atomic.ts";
import {
RulesBlockError,
RULES_BLOCK_ERROR_KIND,
RULES_BLOCK_ID,
RULES_BLOCK_MARKERS,
RULES_BLOCK_STATE,
readRulesBlock,
removeRulesBlock,
renderRulesBlock,
rulesBlockDrift,
writeRulesBlock,
} from "../../../src/core/install/rules-block.ts";
let tmp: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "osb-rules-block-"));
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
const OPERATOR = "# my project\n\nSome operator notes that must survive.\n";
const USAGE_BODY = [
"## Open Second Brain",
"",
"Use the marker_writeback guardrail: record memory as atomic facts",
"in the same turn they are learned.",
].join("\n");
const LESSONS_BODY = ["- prefer small commits", "- measure before tuning"].join("\n");
/** Set a file's mtime to an exact millisecond, for the drift refusals. */
function setMtime(path: string, atMs: number): void {
utimesSync(path, new Date(atMs), new Date(atMs));
}
/** The `.bak.` backup siblings of `name` currently in the directory. */
function backupsOf(name: string): string[] {
return readdirSync(tmp)
.filter((entry) => entry.startsWith(`${name}.bak.`))
.toSorted();
}
describe("rules-block markers and renderRulesBlock", () => {
test("the usage entry re-exports the settled default marker spellings", () => {
expect(RULES_BLOCK_MARKERS.usage.begin).toBe(DEFAULT_BEGIN_MARKER);
expect(RULES_BLOCK_MARKERS.usage.end).toBe(DEFAULT_END_MARKER);
});
test("the lessons entry is a distinct HTML-comment pair", () => {
expect(RULES_BLOCK_MARKERS.lessons.begin).toBe("<!-- >>> open-second-brain lessons >>> -->");
expect(RULES_BLOCK_MARKERS.lessons.end).toBe("<!-- >>> open-second-brain lessons <<< -->");
});
test("renderRulesBlock renders the fenced document for a new file", () => {
const usage = renderRulesBlock(RULES_BLOCK_ID.usage, USAGE_BODY);
expect(usage.beginMarker).toBe(DEFAULT_BEGIN_MARKER);
expect(usage.endMarker).toBe(DEFAULT_END_MARKER);
expect(usage.document).toBe(`${DEFAULT_BEGIN_MARKER}\n${USAGE_BODY}\n${DEFAULT_END_MARKER}\n`);
const lessons = renderRulesBlock(RULES_BLOCK_ID.lessons, LESSONS_BODY);
expect(lessons.document).toBe(
`${RULES_BLOCK_MARKERS.lessons.begin}\n${LESSONS_BODY}\n${RULES_BLOCK_MARKERS.lessons.end}\n`,
);
});
});
describe("writeRulesBlock", () => {
test("creates an absent file with just the block", () => {
const file = join(tmp, "AGENTS.md");
const result = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(result.changed).toBe(true);
expect(result.backupPath).toBeNull();
expect(readFileSync(file, "utf8")).toBe(
renderRulesBlock(RULES_BLOCK_ID.usage, USAGE_BODY).document,
);
});
test("preserves every operator byte outside the block", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
const out = readFileSync(file, "utf8");
expect(out.startsWith(OPERATOR)).toBe(true);
expect(out).toContain(USAGE_BODY);
});
test("a re-apply is a byte no-op reporting changed false", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
const once = readFileSync(file, "utf8");
const second = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(second.changed).toBe(false);
expect(second.backupPath).toBeNull();
expect(readFileSync(file, "utf8")).toBe(once);
});
test("detects and preserves CRLF line endings", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, "# title\r\noperator line\r\n");
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
const out = readFileSync(file, "utf8");
expect(out.includes("\r\n")).toBe(true);
expect(out.startsWith("# title\r\noperator line\r\n")).toBe(true);
// The markers themselves are CRLF-terminated lines now.
expect(out.includes(`${DEFAULT_BEGIN_MARKER}\r\n`)).toBe(true);
// A re-apply on the CRLF file is still a byte no-op.
const second = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(second.changed).toBe(false);
});
test("writes both blocks into one file without the pairs fighting", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
writeRulesBlock(file, RULES_BLOCK_ID.lessons, LESSONS_BODY);
const out = readFileSync(file, "utf8");
expect(out).toContain(DEFAULT_BEGIN_MARKER);
expect(out).toContain(RULES_BLOCK_MARKERS.lessons.begin);
expect(readRulesBlock(file, RULES_BLOCK_ID.usage)).toBe(USAGE_BODY);
expect(readRulesBlock(file, RULES_BLOCK_ID.lessons)).toBe(LESSONS_BODY);
});
test("takes exactly one exclusive-create backup before the first write and none on a no-op", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
const first = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(first.backupPath).not.toBeNull();
expect(backupsOf("AGENTS.md").length).toBe(1);
expect(readFileSync(first.backupPath as string, "utf8")).toBe(OPERATOR);
// The backup was created exclusively: a real file, not a leftover temp.
expect(lstatSync(first.backupPath as string).isFile()).toBe(true);
const second = writeRulesBlock(file, RULES_BLOCK_ID.lessons, LESSONS_BODY);
// A different block id still changes the file, so it backs up once more.
expect(second.changed).toBe(true);
expect(second.backupPath).not.toBeNull();
expect(backupsOf("AGENTS.md").length).toBe(2);
const third = writeRulesBlock(file, RULES_BLOCK_ID.lessons, LESSONS_BODY);
expect(third.changed).toBe(false);
expect(third.backupPath).toBeNull();
expect(backupsOf("AGENTS.md").length).toBe(2);
});
test("an absent file takes no backup", () => {
const file = join(tmp, "AGENTS.md");
const result = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(result.backupPath).toBeNull();
expect(backupsOf("AGENTS.md").length).toBe(0);
});
test("refuses a hand-edited block on a file newer than installedAtMs", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
const installedAtMs = 1_700_000_000_000;
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs });
// Hand-edit inside the fence, then stamp the file newer than the install.
const edited = readFileSync(file, "utf8").replace("atomic facts", "my own wording");
writeFileSync(file, edited);
setMtime(file, installedAtMs + 60_000);
let thrown: unknown = null;
try {
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs });
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(RulesBlockError);
const err = thrown as Error & { kind?: string };
expect(err.kind).toBe(RULES_BLOCK_ERROR_KIND.userModifiedBlock);
// The refusal is by name: the message names the file and the remedy.
expect(err.message).toContain("AGENTS.md");
expect(err.message).toContain("--force");
// Nothing was written.
expect(readFileSync(file, "utf8")).toBe(edited);
expect(backupsOf("AGENTS.md").length).toBe(1);
});
test("force rewrites a hand-edited block and the backup holds the prior bytes", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
const installedAtMs = 1_700_000_000_000;
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs });
const edited = readFileSync(file, "utf8").replace("atomic facts", "my own wording");
writeFileSync(file, edited);
setMtime(file, installedAtMs + 60_000);
const result = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, {
installedAtMs,
force: true,
});
expect(result.changed).toBe(true);
expect(result.backupPath).not.toBeNull();
expect(readFileSync(result.backupPath as string, "utf8")).toBe(edited);
expect(readRulesBlock(file, RULES_BLOCK_ID.usage)).toBe(USAGE_BODY);
});
test("a diverged block on a file older than installedAtMs is a canonical update, not a refusal", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
const installedAtMs = 1_700_000_000_000;
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs });
// The canonical body changed in a newer release; the operator has not
// touched the file since, so the stale mtime proves the divergence is
// ours to fix, not theirs to authorize.
setMtime(file, installedAtMs - 60_000);
const stale = readFileSync(file, "utf8").replace("atomic facts", "old canonical wording");
writeFileSync(file, stale);
setMtime(file, installedAtMs - 60_000);
const result = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs });
expect(result.changed).toBe(true);
expect(readRulesBlock(file, RULES_BLOCK_ID.usage)).toBe(USAGE_BODY);
});
test("refuses through a symbolic link, by name", () => {
const real = join(tmp, "real-agents.md");
writeFileSync(real, OPERATOR);
const link = join(tmp, "AGENTS.md");
symlinkSync(real, link);
let thrown: unknown = null;
try {
writeRulesBlock(link, RULES_BLOCK_ID.usage, USAGE_BODY);
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(RulesBlockError);
expect((thrown as Error & { kind?: string }).kind).toBe(RULES_BLOCK_ERROR_KIND.symlink);
expect(readFileSync(real, "utf8")).toBe(OPERATOR);
});
test("an install anchor stamped into the future is untrusted: the diverged block refuses", () => {
// A future-stamped anchor would make every later operator hand-edit
// read as a canonical move under an untouched file. It must count as
// no record, which refuses every diverged block (fail closed).
const file = join(tmp, "AGENTS.md");
const futureAnchor = Date.now() + 10 * 60_000; // far past the skew allowance
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs: futureAnchor });
const edited = readFileSync(file, "utf8").replace("atomic facts", "my own wording");
writeFileSync(file, edited);
// The file is OLDER than the (future) anchor, which is exactly the
// shape that used to slip through the gate.
setMtime(file, Date.now() - 60_000);
let thrown: unknown = null;
try {
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs: futureAnchor });
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(RulesBlockError);
const err = thrown as Error & { kind?: string };
expect(err.kind).toBe(RULES_BLOCK_ERROR_KIND.userModifiedBlock);
expect(err.message).toContain("future");
expect(err.message).toContain("--force");
expect(readFileSync(file, "utf8")).toBe(edited);
});
test("a stat failure at the hand-edit gate refuses the write, fail closed", () => {
// The gate re-stats the file after the read; a mid-flight move makes
// that stat fail. "Not touched" would overwrite a diverged block
// without --force, so the failure must refuse instead.
const file = join(tmp, "AGENTS.md");
const installedAtMs = 1_700_000_000_000;
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs });
const edited = readFileSync(file, "utf8").replace("atomic facts", "my own wording");
writeFileSync(file, edited);
setMtime(file, installedAtMs - 60_000); // older than the anchor
let thrown: unknown = null;
try {
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, {
installedAtMs,
seams: { fileMtimeMs: () => null },
});
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(RulesBlockError);
const err = thrown as Error & { kind?: string };
expect(err.kind).toBe(RULES_BLOCK_ERROR_KIND.userModifiedBlock);
expect(err.message).toContain("--force");
// Nothing was written and no backup was taken (the fixture write was
// a create, which takes none).
expect(readFileSync(file, "utf8")).toBe(edited);
expect(backupsOf("AGENTS.md").length).toBe(0);
});
test("current bytes that moved during the write refuse by name, touching nothing", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
let thrown: unknown = null;
try {
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, {
seams: { currentBytesMatch: () => false },
});
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(RulesBlockError);
const err = thrown as Error & { kind?: string };
expect(err.kind).toBe(RULES_BLOCK_ERROR_KIND.concurrentModification);
expect(err.message).toContain("--force");
// The refused run left the operator bytes alone and took no backup.
expect(readFileSync(file, "utf8")).toBe(OPERATOR);
expect(backupsOf("AGENTS.md").length).toBe(0);
});
test("force deliberately writes over the moved bytes", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
const result = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, {
force: true,
seams: { currentBytesMatch: () => false },
});
expect(result.changed).toBe(true);
expect(readRulesBlock(file, RULES_BLOCK_ID.usage)).toBe(USAGE_BODY);
});
test("bytes that change between the pre-check and the rename refuse through the writer's re-check", () => {
// Review MG-2: the seam above models drift the PRE-check sees. This
// test stages the other window - the pre-check passes on bytes that
// are still current, and the concurrent edit lands while the write is
// in flight. Only the writer's own re-check (the `expectBefore`
// forwarding into the atomic writer) can refuse it; if that
// forwarding regressed, this write would silently clobber the
// concurrent edit with the whole suite otherwise green.
const file = join(tmp, "AGENTS.md");
const concurrent = `${OPERATOR}A line a concurrent editor added while the write ran.\n`;
let preChecks = 0;
let thrown: unknown = null;
try {
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, {
seams: {
currentBytesMatch: (target, expected) => {
preChecks += 1;
if (preChecks === 1) {
// The pre-check passes - and the edit lands immediately
// after it, inside the window the rename-time re-check
// covers.
writeFileSync(target, concurrent);
return true;
}
return fileMatchesExpected(target, expected);
},
},
});
} catch (err) {
thrown = err;
}
expect(preChecks).toBe(1);
expect(thrown).toBeInstanceOf(RulesBlockError);
const err = thrown as Error & { kind?: string };
expect(err.kind).toBe(RULES_BLOCK_ERROR_KIND.concurrentModification);
// The concurrent editor's bytes are intact: the refused write did not
// clobber them, and an absent-file create takes no backup.
expect(readFileSync(file, "utf8")).toBe(concurrent);
expect(backupsOf("AGENTS.md").length).toBe(0);
});
test("bytes that change between the pre-check and the rename refuse an UPDATE the same way", () => {
// The same window over the update arm of the same call site, where
// the writer's expectation is the read bytes rather than absence.
// The trusted install anchor keeps the hand-edit gate out of the way
// so the drift pre-check is the layer under test.
const file = join(tmp, "AGENTS.md");
const installedAtMs = 1_700_000_000_000;
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs });
setMtime(file, installedAtMs);
const withBlock = readFileSync(file, "utf8");
const concurrent = `${withBlock}A concurrent edit landed mid-write.\n`;
let preChecks = 0;
let thrown: unknown = null;
try {
writeRulesBlock(file, RULES_BLOCK_ID.usage, `${USAGE_BODY}\nAn updated line.\n`, {
installedAtMs,
seams: {
currentBytesMatch: (target, expected) => {
preChecks += 1;
if (preChecks === 1) {
writeFileSync(target, concurrent);
return true;
}
return fileMatchesExpected(target, expected);
},
},
});
} catch (err) {
thrown = err;
}
expect(preChecks).toBe(1);
expect(thrown).toBeInstanceOf(RulesBlockError);
expect((thrown as Error & { kind?: string }).kind).toBe(
RULES_BLOCK_ERROR_KIND.concurrentModification,
);
expect(readFileSync(file, "utf8")).toBe(concurrent);
});
test("refuses multiple begin markers of the block's own spelling, wrapping ManagedBlockError", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(
file,
`${DEFAULT_BEGIN_MARKER}\nfirst\n${DEFAULT_BEGIN_MARKER}\nsecond\n${DEFAULT_END_MARKER}\n`,
);
let thrown: unknown = null;
try {
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(RulesBlockError);
const err = thrown as Error & { kind?: string; cause?: unknown };
expect(err.kind).toBe(RULES_BLOCK_ERROR_KIND.markers);
expect(err.cause).toBeInstanceOf(ManagedBlockError);
});
test("refuses a begin marker without an end marker", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, `${DEFAULT_BEGIN_MARKER}\nnever closed\n`);
expect(() => writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY)).toThrow(RulesBlockError);
});
test("refuses an end marker without a begin marker", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, `${DEFAULT_END_MARKER}\n`);
expect(() => writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY)).toThrow(RulesBlockError);
});
test("refuses a reversed pair", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, `${DEFAULT_END_MARKER}\nbody\n${DEFAULT_BEGIN_MARKER}\n`);
expect(() => writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY)).toThrow(RulesBlockError);
});
test("a foreign spelling's stray markers never block a write of this block", () => {
// The lessons pair present with a broken shape is not the usage
// block's problem: one marker pair per spelling, validated per id.
const file = join(tmp, "AGENTS.md");
writeFileSync(
file,
`${RULES_BLOCK_MARKERS.lessons.begin}\n${RULES_BLOCK_MARKERS.lessons.begin}\n`,
);
const result = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(result.changed).toBe(true);
});
describe("dryRun writes nothing on every path", () => {
test("dryRun on an absent file", () => {
const file = join(tmp, "AGENTS.md");
const result = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { dryRun: true });
expect(result.changed).toBe(true);
expect(result.backupPath).toBeNull();
expect(existsSync(file)).toBe(false);
});
test("dryRun on a file with operator content", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
const result = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { dryRun: true });
expect(result.changed).toBe(true);
expect(result.backupPath).toBeNull();
expect(readFileSync(file, "utf8")).toBe(OPERATOR);
expect(backupsOf("AGENTS.md").length).toBe(0);
});
test("dryRun on a current file reports no change", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
const before = readFileSync(file, "utf8");
const result = writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { dryRun: true });
expect(result.changed).toBe(false);
expect(readFileSync(file, "utf8")).toBe(before);
});
test("dryRun still refuses a hand-edited block", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
const installedAtMs = 1_700_000_000_000;
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs });
const edited = readFileSync(file, "utf8").replace("atomic facts", "my own wording");
writeFileSync(file, edited);
setMtime(file, installedAtMs + 60_000);
expect(() =>
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY, { installedAtMs, dryRun: true }),
).toThrow(RulesBlockError);
expect(readFileSync(file, "utf8")).toBe(edited);
});
});
});
describe("readRulesBlock", () => {
test("returns the extracted body when the pair exists", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(readRulesBlock(file, RULES_BLOCK_ID.usage)).toBe(USAGE_BODY);
});
test("returns null when the file exists but carries no pair of that spelling", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
expect(readRulesBlock(file, RULES_BLOCK_ID.usage)).toBeNull();
expect(readRulesBlock(file, RULES_BLOCK_ID.lessons)).toBeNull();
});
test("returns null for an absent file", () => {
expect(readRulesBlock(join(tmp, "AGENTS.md"), RULES_BLOCK_ID.usage)).toBeNull();
});
test("returns null when only a DIFFERENT block id's pair exists", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.lessons, LESSONS_BODY);
expect(readRulesBlock(file, RULES_BLOCK_ID.usage)).toBeNull();
expect(readRulesBlock(file, RULES_BLOCK_ID.lessons)).toBe(LESSONS_BODY);
});
test("refuses malformed pairs of its own spelling by name", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(
file,
`${DEFAULT_BEGIN_MARKER}\na\n${DEFAULT_BEGIN_MARKER}\nb\n${DEFAULT_END_MARKER}\n`,
);
let thrown: unknown = null;
try {
readRulesBlock(file, RULES_BLOCK_ID.usage);
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(RulesBlockError);
expect((thrown as Error & { kind?: string }).kind).toBe(RULES_BLOCK_ERROR_KIND.markers);
});
test("refuses a symbolic link, by name", () => {
const real = join(tmp, "real-agents.md");
writeFileSync(real, OPERATOR);
const link = join(tmp, "AGENTS.md");
symlinkSync(real, link);
expect(() => readRulesBlock(link, RULES_BLOCK_ID.usage)).toThrow(RulesBlockError);
});
});
describe("rulesBlockDrift", () => {
test("absent when the file or the pair is missing", () => {
const absent = rulesBlockDrift(join(tmp, "AGENTS.md"), RULES_BLOCK_ID.usage, USAGE_BODY);
expect(absent.state).toBe(RULES_BLOCK_STATE.absent);
expect(absent.extracted).toBeNull();
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
const noPair = rulesBlockDrift(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(noPair.state).toBe(RULES_BLOCK_STATE.absent);
expect(noPair.extracted).toBeNull();
});
test("current when the extracted body matches the canonical body", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
const drift = rulesBlockDrift(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(drift.state).toBe(RULES_BLOCK_STATE.current);
expect(drift.extracted).toBe(USAGE_BODY);
});
test("drifted when the extracted body diverges from the canonical body", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
const drift = rulesBlockDrift(file, RULES_BLOCK_ID.usage, `${USAGE_BODY}\nA new clause.\n`);
expect(drift.state).toBe(RULES_BLOCK_STATE.drifted);
expect(drift.extracted).toBe(USAGE_BODY);
});
test("reads are read-only: drift never writes", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
rulesBlockDrift(file, RULES_BLOCK_ID.usage, USAGE_BODY);
expect(readFileSync(file, "utf8")).toBe(OPERATOR);
expect(backupsOf("AGENTS.md").length).toBe(0);
});
});
describe("removeRulesBlock", () => {
test("removes only the pair it owns and preserves the other block and operator bytes", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
writeRulesBlock(file, RULES_BLOCK_ID.lessons, LESSONS_BODY);
const result = removeRulesBlock(file, RULES_BLOCK_ID.usage);
expect(result.removed).toBe(true);
const out = readFileSync(file, "utf8");
expect(out).not.toContain(DEFAULT_BEGIN_MARKER);
expect(out).not.toContain(DEFAULT_END_MARKER);
expect(out).not.toContain(USAGE_BODY);
expect(out).toContain(LESSONS_BODY);
expect(out).toContain(RULES_BLOCK_MARKERS.lessons.begin);
expect(out.startsWith(OPERATOR)).toBe(true);
// Never an empty fence where the lessons block lives.
expect(readRulesBlock(file, RULES_BLOCK_ID.lessons)).toBe(LESSONS_BODY);
});
test("collapses its own padding so cycles do not grow vertical whitespace", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
removeRulesBlock(file, RULES_BLOCK_ID.usage);
const out = readFileSync(file, "utf8");
expect(out).toBe(OPERATOR);
});
test("is a named skip when no pair of that spelling exists", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
const result = removeRulesBlock(file, RULES_BLOCK_ID.usage);
expect(result.removed).toBe(false);
expect(readFileSync(file, "utf8")).toBe(OPERATOR);
});
test("is a named skip on an absent file", () => {
const result = removeRulesBlock(join(tmp, "AGENTS.md"), RULES_BLOCK_ID.usage);
expect(result.removed).toBe(false);
});
test("dryRun removes nothing", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
const before = readFileSync(file, "utf8");
const result = removeRulesBlock(file, RULES_BLOCK_ID.usage, { dryRun: true });
expect(result.removed).toBe(true);
expect(readFileSync(file, "utf8")).toBe(before);
});
test("refuses through a symbolic link, by name", () => {
const real = join(tmp, "real-agents.md");
writeFileSync(real, OPERATOR);
const link = join(tmp, "AGENTS.md");
symlinkSync(real, link);
expect(() => removeRulesBlock(link, RULES_BLOCK_ID.usage)).toThrow(RulesBlockError);
});
test("current bytes that moved during the removal refuse by name, touching nothing", () => {
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
let thrown: unknown = null;
try {
removeRulesBlock(file, RULES_BLOCK_ID.usage, {
seams: { currentBytesMatch: () => false },
});
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(RulesBlockError);
expect((thrown as Error & { kind?: string }).kind).toBe(
RULES_BLOCK_ERROR_KIND.concurrentModification,
);
// The removal was refused before any rewrite.
expect(readRulesBlock(file, RULES_BLOCK_ID.usage)).toBe(USAGE_BODY);
});
test("bytes that change between the pre-check and the rename refuse the removal through the writer's re-check", () => {
// The removal twin of the MG-2 pin: the pre-check sees current bytes,
// the concurrent edit lands while the rewrite is in flight, and only
// the forwarded `expectBefore` re-check stands between the rename and
// the concurrent editor's bytes. Removing the forwarding would let
// this removal clobber them with every other test still green.
const file = join(tmp, "AGENTS.md");
writeFileSync(file, OPERATOR);
writeRulesBlock(file, RULES_BLOCK_ID.usage, USAGE_BODY);
const withBlock = readFileSync(file, "utf8");
const concurrent = `${withBlock}A concurrent edit landed mid-removal.\n`;
let preChecks = 0;
let thrown: unknown = null;
try {
removeRulesBlock(file, RULES_BLOCK_ID.usage, {
seams: {
currentBytesMatch: (target, expected) => {
preChecks += 1;
if (preChecks === 1) {
writeFileSync(target, concurrent);
return true;
}
return fileMatchesExpected(target, expected);
},
},
});
} catch (err) {
thrown = err;
}
expect(preChecks).toBe(1);
expect(thrown).toBeInstanceOf(RulesBlockError);
expect((thrown as Error & { kind?: string }).kind).toBe(
RULES_BLOCK_ERROR_KIND.concurrentModification,
);
// The concurrent edit survives and the block was not removed.
expect(readFileSync(file, "utf8")).toBe(concurrent);
expect(readRulesBlock(file, RULES_BLOCK_ID.usage)).toBe(USAGE_BODY);
});
});