agentic-workflow-manager 9.18.0 → 9.20.0

package/dist/tests/core/changes/record-io.test.js

@@ -0,0 +1,307 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const helpers_1 = require("./helpers");
+const record_io_1 = require("../../../src/core/changes/record-io");
+const types_1 = require("../../../src/core/changes/types");
+// HOME and AWM_HOME point at a throwaway home for the whole file (makeRepo); every scratch directory lives inside it.
+let repo;
+let n = 0;
+beforeAll(() => { repo = (0, helpers_1.makeRepo)(); });
+afterAll(() => repo.cleanup());
+const scratch = () => fs_1.default.mkdtempSync(path_1.default.join(repo.home, `rio${n++}-`));
+function intercept(name, match, replace) {
+    const real = fs_1.default[name];
+    jest.spyOn(fs_1.default, name).mockImplementation(((...args) => (match(args) ? replace(real, args) : real(...args))));
+}
+afterEach(() => jest.restoreAllMocks());
+describe('errorCode', () => {
+    test.each([['an errno error', Object.assign(new Error('x'), { code: 'ENOENT' }), 'ENOENT'], ['an error without a code', new Error('x'), 'unknown'], ['a non-error', 'boom', 'unknown'], ['null', null, 'unknown'], ['a numeric code', { code: 5 }, 'unknown']])('%s', (_n, e, expected) => {
+        expect((0, record_io_1.errorCode)(e)).toBe(expected);
+    });
+});
+describe('inspectRecordDir', () => {
+    test('is absent when docs does not exist', () => {
+        expect((0, record_io_1.inspectRecordDir)(scratch())).toEqual({ kind: 'absent' });
+    });
+    test('is absent when docs exists without changes', () => {
+        const root = scratch();
+        fs_1.default.mkdirSync(path_1.default.join(root, 'docs'));
+        expect((0, record_io_1.inspectRecordDir)(root)).toEqual({ kind: 'absent' });
+    });
+    test('is ok with the directory when both exist', () => {
+        const root = scratch();
+        fs_1.default.mkdirSync(path_1.default.join(root, 'docs', 'changes'), { recursive: true });
+        expect((0, record_io_1.inspectRecordDir)(root)).toEqual({ kind: 'ok', dir: path_1.default.join(root, 'docs', 'changes') });
+    });
+    (0, helpers_1.posixOnly)('a symlinked docs is unsafe', () => {
+        const root = scratch();
+        const outside = scratch();
+        fs_1.default.symlinkSync(outside, path_1.default.join(root, 'docs'));
+        expect((0, record_io_1.inspectRecordDir)(root)).toEqual({ kind: 'unsafe' });
+    });
+    (0, helpers_1.posixOnly)('a symlinked changes is unsafe', () => {
+        const root = scratch();
+        const outside = scratch();
+        fs_1.default.mkdirSync(path_1.default.join(root, 'docs'));
+        fs_1.default.symlinkSync(outside, path_1.default.join(root, 'docs', 'changes'));
+        expect((0, record_io_1.inspectRecordDir)(root)).toEqual({ kind: 'unsafe' });
+    });
+    test('a file in place of changes is unsafe', () => {
+        const root = scratch();
+        fs_1.default.mkdirSync(path_1.default.join(root, 'docs'));
+        fs_1.default.writeFileSync(path_1.default.join(root, 'docs', 'changes'), 'x');
+        expect((0, record_io_1.inspectRecordDir)(root)).toEqual({ kind: 'unsafe' });
+    });
+    test('an unreadable path is an error, not absence', () => {
+        const root = scratch();
+        intercept('lstatSync', (a) => path_1.default.basename(String(a[0])) === 'docs', () => { throw Object.assign(new Error('denied'), { code: 'EACCES' }); });
+        expect((0, record_io_1.inspectRecordDir)(root)).toEqual({ kind: 'error' });
+    });
+});
+describe('createRecordDir', () => {
+    test('creates docs and changes', () => {
+        const root = scratch();
+        expect((0, record_io_1.createRecordDir)(root)).toEqual({ kind: 'ok', dir: path_1.default.join(root, 'docs', 'changes') });
+        expect(fs_1.default.statSync(path_1.default.join(root, 'docs', 'changes')).isDirectory()).toBe(true);
+    });
+    test('accepts directories that already exist', () => {
+        const root = scratch();
+        fs_1.default.mkdirSync(path_1.default.join(root, 'docs', 'changes'), { recursive: true });
+        expect((0, record_io_1.createRecordDir)(root).kind).toBe('ok');
+    });
+    (0, helpers_1.posixOnly)('refuses an existing symlinked docs without creating anything through it', () => {
+        const root = scratch();
+        const outside = scratch();
+        fs_1.default.symlinkSync(outside, path_1.default.join(root, 'docs'));
+        expect((0, record_io_1.createRecordDir)(root)).toEqual({ kind: 'unsafe' });
+        expect(fs_1.default.readdirSync(outside)).toEqual([]);
+    });
+    (0, helpers_1.posixOnly)('checks docs right after creating it, before creating changes inside it', () => {
+        const root = scratch();
+        const outside = scratch();
+        intercept('mkdirSync', (a) => path_1.default.basename(String(a[0])) === 'docs', (_r, a) => { fs_1.default.symlinkSync(outside, String(a[0])); });
+        expect((0, record_io_1.createRecordDir)(root)).toEqual({ kind: 'unsafe' });
+        expect(fs_1.default.readdirSync(outside)).toEqual([]);
+    });
+    (0, helpers_1.posixOnly)('checks changes right after creating it', () => {
+        const root = scratch();
+        const outside = scratch();
+        intercept('mkdirSync', (a) => path_1.default.basename(String(a[0])) === 'changes', (_r, a) => { fs_1.default.symlinkSync(outside, String(a[0])); });
+        expect((0, record_io_1.createRecordDir)(root)).toEqual({ kind: 'unsafe' });
+        expect(fs_1.default.readdirSync(outside)).toEqual([]);
+    });
+    test('a mkdir failure other than "exists" is an error', () => {
+        const root = scratch();
+        intercept('mkdirSync', () => true, () => { throw Object.assign(new Error('denied'), { code: 'EACCES' }); });
+        expect((0, record_io_1.createRecordDir)(root)).toEqual({ kind: 'error' });
+    });
+    test('a file in place of docs is unsafe', () => {
+        const root = scratch();
+        fs_1.default.writeFileSync(path_1.default.join(root, 'docs'), 'x');
+        expect((0, record_io_1.createRecordDir)(root)).toEqual({ kind: 'unsafe' });
+    });
+});
+describe('recordsWithSlug', () => {
+    test('lists the records with that slug under any date, and only them', () => {
+        const dir = scratch();
+        for (const f of ['2026-10-17-a.md', '2026-11-01-a.md', '2026-10-17-ab.md', '2026-10-17-b-a.md', 'a.md', '2026-10-17-A.md', '2026-10-17-a.md.bak'])
+            fs_1.default.writeFileSync(path_1.default.join(dir, f), 'x');
+        expect((0, record_io_1.recordsWithSlug)(dir, 'a').sort()).toEqual(['2026-10-17-a.md', '2026-11-01-a.md']);
+    });
+    test('a directory entry named like a record counts', () => {
+        const dir = scratch();
+        fs_1.default.mkdirSync(path_1.default.join(dir, '2026-10-17-a.md'));
+        expect((0, record_io_1.recordsWithSlug)(dir, 'a')).toEqual(['2026-10-17-a.md']);
+    });
+    test('an unreadable directory is null, never an empty list', () => {
+        expect((0, record_io_1.recordsWithSlug)(path_1.default.join(scratch(), 'missing'), 'a')).toBeNull();
+    });
+});
+describe('readRecord', () => {
+    const write = (content) => { const f = path_1.default.join(scratch(), '2026-10-17-x.md'); fs_1.default.writeFileSync(f, content); return f; };
+    test('reads the text and a snapshot of the file', () => {
+        const f = write('---\nx: 1\n---\n');
+        const r = (0, record_io_1.readRecord)(f, '2026-10-17-x.md');
+        expect(r).toMatchObject({ ok: true, text: '---\nx: 1\n---\n' });
+        expect(r.ok && r.snapshot.size).toBe(13);
+    });
+    test('keeps a leading BOM as U+FEFF instead of dropping it', () => {
+        const r = (0, record_io_1.readRecord)(write(Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from('---\n')])), 'n.md');
+        expect(r.ok && r.text.charCodeAt(0)).toBe(0xfeff);
+    });
+    test('refuses invalid UTF-8 as record-invalid', () => {
+        expect((0, record_io_1.readRecord)(write(Buffer.from([0xff, 0xfe, 0x0a])), 'n.md')).toMatchObject({ ok: false, code: 'record-invalid' });
+    });
+    test('refuses a record over the size limit as record-invalid, flagged tooLarge', () => {
+        expect((0, record_io_1.readRecord)(write('x'.repeat(types_1.MAX_RECORD_BYTES + 1)), 'n.md')).toMatchObject({ ok: false, code: 'record-invalid', tooLarge: true });
+    });
+    test('only the size refusal is flagged tooLarge', () => {
+        expect((0, record_io_1.readRecord)(write(Buffer.from([0xff, 0xfe, 0x0a])), 'n.md')).not.toHaveProperty('tooLarge');
+        expect((0, record_io_1.readRecord)(scratch(), 'n.md')).not.toHaveProperty('tooLarge');
+    });
+    test('accepts a record of exactly the size limit', () => {
+        expect((0, record_io_1.readRecord)(write('x'.repeat(types_1.MAX_RECORD_BYTES)), 'n.md').ok).toBe(true);
+    });
+    test('refuses a directory as record-invalid', () => {
+        expect((0, record_io_1.readRecord)(scratch(), 'n.md')).toMatchObject({ ok: false, code: 'record-invalid' });
+    });
+    (0, helpers_1.posixOnly)('refuses a symlink as unsafe-path', () => {
+        const real = write('x');
+        const link = path_1.default.join(scratch(), 'l.md');
+        fs_1.default.symlinkSync(real, link);
+        expect((0, record_io_1.readRecord)(link, 'l.md')).toMatchObject({ ok: false, code: 'unsafe-path' });
+    });
+    test('a missing file is io-failed', () => {
+        expect((0, record_io_1.readRecord)(path_1.default.join(scratch(), 'gone.md'), 'gone.md')).toMatchObject({ ok: false, code: 'io-failed' });
+    });
+    test('the message escapes a hostile file name and stays on one line within 300 units', () => {
+        const r = (0, record_io_1.readRecord)(path_1.default.join(scratch(), 'gone.md'), 'a\n\u001b[31m'.repeat(60));
+        expect(r.ok).toBe(false);
+        const message = r.ok ? '' : r.message;
+        expect(message).not.toMatch(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/);
+        expect(message.length).toBeLessThanOrEqual(300);
+    });
+});
+describe('unchangedSince', () => {
+    function snapshotOf(content) {
+        const file = path_1.default.join(scratch(), 'r.md');
+        fs_1.default.writeFileSync(file, content);
+        return { file, snap: snap(file) };
+    }
+    function snap(file) {
+        const r = (0, record_io_1.readRecord)(file, 'r.md');
+        return r.ok ? r.snapshot : null;
+    }
+    test('is true for a file nobody touched', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        expect((0, record_io_1.unchangedSince)(file, s)).toBe(true);
+    });
+    test('is false when the size changed', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        fs_1.default.appendFileSync(file, 'd');
+        expect((0, record_io_1.unchangedSince)(file, s)).toBe(false);
+    });
+    test('is false when only the modification time changed', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        const later = new Date(Date.now() + 60_000);
+        fs_1.default.utimesSync(file, later, later);
+        expect((0, record_io_1.unchangedSince)(file, s)).toBe(false);
+    });
+    test('is false when the size differs, whatever the modification time says', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        expect((0, record_io_1.unchangedSince)(file, { ...s, size: s.size + 1 })).toBe(false);
+    });
+    test('is false when the modification time differs, whatever the size says', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        expect((0, record_io_1.unchangedSince)(file, { ...s, mtimeMs: s.mtimeMs + 1 })).toBe(false);
+    });
+    test('is false for a directory, even with a snapshot that matches it exactly', () => {
+        const dir = scratch();
+        const stat = fs_1.default.lstatSync(dir);
+        expect((0, record_io_1.unchangedSince)(dir, { size: stat.size, mtimeMs: stat.mtimeMs, ino: stat.ino })).toBe(false);
+    });
+    (0, helpers_1.posixOnly)('is false for a symlink, even with a snapshot that matches it exactly', () => {
+        const dir = scratch();
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'real.md'), 'abc');
+        fs_1.default.symlinkSync(path_1.default.join(dir, 'real.md'), path_1.default.join(dir, 'l.md'));
+        const stat = fs_1.default.lstatSync(path_1.default.join(dir, 'l.md'));
+        expect((0, record_io_1.unchangedSince)(path_1.default.join(dir, 'l.md'), { size: stat.size, mtimeMs: stat.mtimeMs, ino: stat.ino })).toBe(false);
+    });
+    test('is false when the file is gone', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        fs_1.default.rmSync(file);
+        expect((0, record_io_1.unchangedSince)(file, s)).toBe(false);
+    });
+    (0, helpers_1.posixOnly)('is false when the inode differs (same size and time, another file)', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        expect(s.ino).not.toBe(0);
+        expect((0, record_io_1.unchangedSince)(file, { ...s, ino: s.ino + 1 })).toBe(false);
+    });
+    test('compares inodes only when the file reports one: an inode of 0 on the file side is ignored', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        expect(s.ino).not.toBe(0);
+        intercept('lstatSync', (a) => a[0] === file, (real, a) => Object.assign(Object.create(Object.getPrototypeOf(real(...a))), real(...a), { ino: 0 }));
+        expect((0, record_io_1.unchangedSince)(file, s)).toBe(true);
+    });
+    test('compares inodes only when both sides carry one', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        expect((0, record_io_1.unchangedSince)(file, { ...s, ino: 0 })).toBe(true);
+    });
+    (0, helpers_1.posixOnly)('is false when a symlink took its place', () => {
+        const { file, snap: s } = snapshotOf('abc');
+        const other = path_1.default.join(scratch(), 'o.md');
+        fs_1.default.writeFileSync(other, 'abc');
+        fs_1.default.rmSync(file);
+        fs_1.default.symlinkSync(other, file);
+        expect((0, record_io_1.unchangedSince)(file, s)).toBe(false);
+    });
+});
+describe('createExclusive', () => {
+    test('creates the file with the content', () => {
+        const f = path_1.default.join(scratch(), 'a.md');
+        expect((0, record_io_1.createExclusive)(f, 'hello')).toBe('ok');
+        expect(fs_1.default.readFileSync(f, 'utf8')).toBe('hello');
+    });
+    test('never replaces an existing file', () => {
+        const f = path_1.default.join(scratch(), 'a.md');
+        fs_1.default.writeFileSync(f, 'old');
+        expect((0, record_io_1.createExclusive)(f, 'new')).toBe('exists');
+        expect(fs_1.default.readFileSync(f, 'utf8')).toBe('old');
+    });
+    (0, helpers_1.posixOnly)('never writes through a symlink at the target', () => {
+        const dir = scratch();
+        const outside = path_1.default.join(dir, 'outside.md');
+        fs_1.default.writeFileSync(outside, 'precious');
+        fs_1.default.symlinkSync(outside, path_1.default.join(dir, 'a.md'));
+        expect((0, record_io_1.createExclusive)(path_1.default.join(dir, 'a.md'), 'new')).toBe('exists');
+        expect(fs_1.default.readFileSync(outside, 'utf8')).toBe('precious');
+    });
+    test('a failed write leaves no partial file', () => {
+        const f = path_1.default.join(scratch(), 'a.md');
+        intercept('writeFileSync', (a) => typeof a[0] === 'number', () => { throw Object.assign(new Error('full'), { code: 'ENOSPC' }); });
+        expect((0, record_io_1.createExclusive)(f, 'x')).toBe('error');
+        expect(fs_1.default.existsSync(f)).toBe(false);
+    });
+    test('a missing directory is an error', () => {
+        expect((0, record_io_1.createExclusive)(path_1.default.join(scratch(), 'no', 'a.md'), 'x')).toBe('error');
+    });
+});
+describe('replaceRecord', () => {
+    test('replaces the content', () => {
+        const f = path_1.default.join(scratch(), 'a.md');
+        fs_1.default.writeFileSync(f, 'old');
+        expect((0, record_io_1.replaceRecord)(f, 'new')).toEqual({ ok: true });
+        expect(fs_1.default.readFileSync(f, 'utf8')).toBe('new');
+    });
+    (0, helpers_1.posixOnly)('keeps the mode of the file', () => {
+        const f = path_1.default.join(scratch(), 'a.md');
+        fs_1.default.writeFileSync(f, 'old');
+        fs_1.default.chmodSync(f, 0o640);
+        (0, record_io_1.replaceRecord)(f, 'new');
+        expect(fs_1.default.statSync(f).mode & 0o777).toBe(0o640);
+    });
+    (0, helpers_1.posixOnly)('does not replace a symlink', () => {
+        const dir = scratch();
+        const real = path_1.default.join(dir, 'real.md');
+        fs_1.default.writeFileSync(real, 'precious');
+        fs_1.default.symlinkSync(real, path_1.default.join(dir, 'l.md'));
+        expect((0, record_io_1.replaceRecord)(path_1.default.join(dir, 'l.md'), 'new')).toMatchObject({ ok: false });
+        expect(fs_1.default.readFileSync(real, 'utf8')).toBe('precious');
+        expect(fs_1.default.lstatSync(path_1.default.join(dir, 'l.md')).isSymbolicLink()).toBe(true);
+    });
+    test('a failed rename keeps the old content, reports its code and leaves no temporary file', () => {
+        const dir = scratch();
+        const f = path_1.default.join(dir, 'a.md');
+        fs_1.default.writeFileSync(f, 'old');
+        intercept('renameSync', () => true, () => { throw Object.assign(new Error('nope'), { code: 'EPERM' }); });
+        expect((0, record_io_1.replaceRecord)(f, 'new')).toEqual({ ok: false, code: 'EPERM' });
+        jest.restoreAllMocks();
+        expect(fs_1.default.readFileSync(f, 'utf8')).toBe('old');
+        expect(fs_1.default.readdirSync(dir)).toEqual(['a.md']);
+    });
+});