Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import {
existsSync,
mkdirSync,
mkdtempSync,
readdirSync,
readFileSync,
rmSync,
utimesSync,
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import { atomicWriteFile, atomicWriteFileSync } from './atomic-yaml-write.ts';
let testDir: string;
let target: string;
beforeEach(() => {
testDir = mkdtempSync(join(tmpdir(), 'ok-atomic-write-'));
target = join(testDir, 'state.yml');
});
afterEach(() => {
if (existsSync(testDir)) rmSync(testDir, { recursive: true, force: true });
});
function orphanTmps(): string[] {
return readdirSync(testDir).filter((f) => f.startsWith('state.yml.tmp.'));
}
describe('atomicWriteFileSync — sequential', () => {
test('writes content atomically; target exists with correct bytes', () => {
atomicWriteFileSync(target, 'hello\n');
expect(existsSync(target)).toBe(true);
expect(readFileSync(target, 'utf-8')).toBe('hello\n');
});
test('overwrites existing file via rename(2)', () => {
atomicWriteFileSync(target, 'first\n');
atomicWriteFileSync(target, 'second\n');
expect(readFileSync(target, 'utf-8')).toBe('second\n');
});
test('leaves no orphan .tmp siblings on happy path', () => {
atomicWriteFileSync(target, 'x');
expect(orphanTmps()).toEqual([]);
});
});
describe('atomicWriteFileSync — failure cleanup', () => {
test('cleans tmp when rename fails because target is a non-empty dir', () => {
mkdirSync(target, { recursive: true });
writeFileSync(join(target, 'occupant'), 'x');
expect(() => atomicWriteFileSync(target, 'new content')).toThrow();
expect(orphanTmps()).toEqual([]);
});
test('cleans tmp when writeFileSync fails because parent dir is missing', () => {
const missing = join(testDir, 'no', 'such', 'dir', 'state.yml');
expect(() => atomicWriteFileSync(missing, 'x')).toThrow();
expect(orphanTmps()).toEqual([]);
});
});
describe('atomicWriteFile (async) — sequential', () => {
test('writes content atomically; target exists with correct bytes', async () => {
await atomicWriteFile(target, 'hello\n');
expect(existsSync(target)).toBe(true);
expect(readFileSync(target, 'utf-8')).toBe('hello\n');
});
test('leaves no orphan .tmp siblings on happy path', async () => {
await atomicWriteFile(target, 'x');
expect(orphanTmps()).toEqual([]);
});
});
describe('atomicWriteFile (async) — the check before the rename', () => {
test('runs after the temp file is written and before the target is replaced', async () => {
writeFileSync(target, 'before\n');
const seen: Array<{ target: string; tmps: number }> = [];
await atomicWriteFile(target, 'after\n', {
beforeRename: () => {
seen.push({ target: readFileSync(target, 'utf-8'), tmps: orphanTmps().length });
},
});
expect(seen).toEqual([{ target: 'before\n', tmps: 1 }]);
expect(readFileSync(target, 'utf-8')).toBe('after\n');
});
test('a check that throws leaves the target untouched and removes the temp file', async () => {
writeFileSync(target, 'outside\n');
await expect(
atomicWriteFile(target, 'ours\n', {
beforeRename: () => {
throw new Error('the target moved');
},
}),
).rejects.toThrow('the target moved');
expect(readFileSync(target, 'utf-8')).toBe('outside\n');
expect(orphanTmps()).toEqual([]);
});
});
describe('atomicWriteFile (async) — failure cleanup', () => {
test('cleans tmp when rename fails because target is a non-empty dir', async () => {
mkdirSync(target, { recursive: true });
writeFileSync(join(target, 'occupant'), 'x');
await expect(atomicWriteFile(target, 'new content')).rejects.toThrow();
expect(orphanTmps()).toEqual([]);
});
test('cleans tmp when writeFile fails because parent dir is missing', async () => {
const missing = join(testDir, 'no', 'such', 'dir', 'state.yml');
await expect(atomicWriteFile(missing, 'x')).rejects.toThrow();
expect(orphanTmps()).toEqual([]);
});
});
describe('atomicWriteFileSync — crash-orphan sweep', () => {
test('unlinks stale .tmp siblings of the target', () => {
const ancientTmp = join(testDir, 'state.yml.tmp.ancient-uuid');
writeFileSync(ancientTmp, 'crashed mid-write');
const ancient = new Date('2000-01-01T00:00:00Z');
utimesSync(ancientTmp, ancient, ancient);
atomicWriteFileSync(target, 'new');
expect(existsSync(ancientTmp)).toBe(false);
expect(readFileSync(target, 'utf-8')).toBe('new');
});
test('preserves recent .tmp siblings of the target (concurrent writers)', () => {
const freshTmp = join(testDir, 'state.yml.tmp.in-flight-uuid');
writeFileSync(freshTmp, 'concurrent writer');
atomicWriteFileSync(target, 'new');
expect(existsSync(freshTmp)).toBe(true);
expect(readFileSync(freshTmp, 'utf-8')).toBe('concurrent writer');
});
test('does not sweep stale .tmp siblings of unrelated targets', () => {
const unrelatedTmp = join(testDir, 'other.yml.tmp.ancient-uuid');
writeFileSync(unrelatedTmp, 'unrelated');
const ancient = new Date('2000-01-01T00:00:00Z');
utimesSync(unrelatedTmp, ancient, ancient);
atomicWriteFileSync(target, 'new');
expect(existsSync(unrelatedTmp)).toBe(true);
});
});
describe('atomicWriteFile (async) — crash-orphan sweep', () => {
test('unlinks stale .tmp siblings of the target', async () => {
const ancientTmp = join(testDir, 'state.yml.tmp.ancient-uuid');
writeFileSync(ancientTmp, 'crashed mid-write');
const ancient = new Date('2000-01-01T00:00:00Z');
utimesSync(ancientTmp, ancient, ancient);
await atomicWriteFile(target, 'new');
expect(existsSync(ancientTmp)).toBe(false);
expect(readFileSync(target, 'utf-8')).toBe('new');
});
test('preserves recent .tmp siblings of the target (concurrent writers)', async () => {
const freshTmp = join(testDir, 'state.yml.tmp.in-flight-uuid');
writeFileSync(freshTmp, 'concurrent writer');
await atomicWriteFile(target, 'new');
expect(existsSync(freshTmp)).toBe(true);
});
test('does not sweep stale .tmp siblings of unrelated targets', async () => {
const unrelatedTmp = join(testDir, 'other.yml.tmp.ancient-uuid');
writeFileSync(unrelatedTmp, 'unrelated');
const ancient = new Date('2000-01-01T00:00:00Z');
utimesSync(unrelatedTmp, ancient, ancient);
await atomicWriteFile(target, 'new');
expect(existsSync(unrelatedTmp)).toBe(true);
});
test('can skip the directory sweep while a finite-staleness lock is held', async () => {
const ancientTmp = join(testDir, 'state.yml.tmp.ancient-uuid');
writeFileSync(ancientTmp, 'crashed mid-write');
const ancient = new Date('2000-01-01T00:00:00Z');
utimesSync(ancientTmp, ancient, ancient);
await atomicWriteFile(target, 'new', { sweepStaleTmps: false });
expect(existsSync(ancientTmp)).toBe(true);
expect(readFileSync(target, 'utf-8')).toBe('new');
});
});