Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

13.1 KB
Raw Blame
import { constants, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, unlinkSync, writeFileSync, chmodSync, fstatSync, statSync, renameSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, expect, it, vi } from 'vitest'
import { hookFileVersion, inspectHookFile, runHookPreparation } from './nativeHookFiles.js'

// Windows moved a just-published file's change time when its handle closed (measured on DESKTOP-0TFH0OJ, 2026-11-05), after the
// publication had read it: Kilo's, Pi's and Amp's plugins were written, then reported as failed, at every start.
it('leaves the change time out of a file\'s version on Windows alone', () => {
  const stat = { dev: 1n, ino: 2n, uid: 0n, mode: 0o644n, size: 5n, mtimeNs: 7n }
  const closed = (ctimeNs: bigint) => ({ ...stat, ctimeNs }) as never
  expect(hookFileVersion(closed(8n), 'win32')).toBe(hookFileVersion(closed(9n), 'win32'))
  expect(hookFileVersion(closed(8n), 'darwin')).not.toBe(hookFileVersion(closed(9n), 'darwin'))
  expect(hookFileVersion({ ...stat, mtimeNs: 70n, ctimeNs: 8n } as never, 'win32')).not.toBe(hookFileVersion(closed(8n), 'win32'))
})

const fault = vi.hoisted(() => ({ sync: false, write: false, windows: false, writableOpens: 0, onSync: undefined as ((fd: number) => void) | undefined, openAs: undefined as string | undefined, onStat: undefined as ((file: unknown, options: unknown) => void) | undefined }))
vi.mock('./windowsFiles.js', async original => {
  const actual = await original<typeof import('./windowsFiles.js')>()
  return { ...actual, unchangedFlushFlags: (mode: number) => actual.unchangedFlushFlags(mode, fault.windows ? 'win32' : undefined) }
})
vi.mock('node:fs', async original => {
  const fs = await original<typeof import('node:fs')>()
  return { ...fs,
    lstatSync: (...args: Parameters<typeof fs.lstatSync>) => { fault.onStat?.(...args); return fs.lstatSync(...args) },
    fsync: (fd: number, callback: (error: Error | null) => void) => {
      try { if (fault.sync) throw new Error('fixture sync unavailable'); fault.onSync?.(fd); fs.fsync(fd, callback) }
      catch (error) { queueMicrotask(() => callback(error as Error)) }
    },
    openSync: (...args: Parameters<typeof fs.openSync>) => {
      if (fault.windows && String(args[0]).endsWith('config.json') && typeof args[1] === 'number'
        && (args[1] & 3) === constants.O_RDWR) fault.writableOpens++
      return fs.openSync(fault.openAs ?? args[0], ...args.slice(1) as [number, number?])
    },
    writeFileSync: (...args: Parameters<typeof fs.writeFileSync>) => {
      if (fault.write && typeof args[0] === 'number') throw new Error('fixture disk full')
      return fs.writeFileSync(...args)
    },
  }
})
const roots: string[] = []
function prepared(file: string) {
  const observed = inspectHookFile(file)
  return { ...observed,
    replace: (next: string) => runHookPreparation([file], attempt => observed.replace(next, attempt)),
    remove: () => runHookPreparation([file], attempt => observed.remove(attempt)),
  }
}
function fixture() {
  const root = realpathSync(mkdtempSync(join(tmpdir(), 'native-hook-files-')))
  roots.push(root)
  return { root, file: join(root, 'config.json') }
}
afterEach(() => { fault.sync = false; fault.write = false; fault.windows = false; fault.writableOpens = 0; fault.onSync = undefined; fault.openAs = undefined; fault.onStat = undefined; vi.restoreAllMocks(); for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) })

it('publishes complete bytes durably, preserves private permissions and leaves no staging file', async () => {
  const { root, file } = fixture()
  writeFileSync(file, 'old', { mode: 0o600 })
  await prepared(file).replace('new')
  expect(readFileSync(file, 'utf8')).toBe('new')
  expect(readdirSync(root)).toEqual(['config.json'])
  expect(inspectHookFile(file).content).toBe('new')
  await prepared(file).replace('new')
})

it('never turns a peer edit during final proof capture into a confirmed output', async () => {
  const { file } = fixture()
  writeFileSync(file, 'prepared hooks')
  const confirmed = vi.fn()
  await expect(runHookPreparation([file], async attempt => {
    const expected = inspectHookFile(file)
    attempt.observe(file, () => {
      expected.verify()
      // The next leaf read occurs after checking the published observation.
      // A peer writes real bytes at that boundary, before proof capture.
      fault.onStat = path => {
        if (path !== file) return
        fault.onStat = undefined
        writeFileSync(file, 'peer hooks')
      }
    })
    return true
  }, { confirmed })).rejects.toThrow(/changed/)
  expect(confirmed).not.toHaveBeenCalled()
  expect(readFileSync(file, 'utf8')).toBe('peer hooks')
})

it('creates and syncs a missing directory chain', async () => {
  const { root } = fixture(), file = join(root, 'new', 'nested', 'hooks.json')
  await prepared(file).replace('prepared')
  expect(readFileSync(file, 'utf8')).toBe('prepared')
  await prepared(file).remove()
  expect(inspectHookFile(file).content).toBeNull()
  await prepared(file).remove()
})

it('preserves a relocated config home and its file alias', async () => {
  const { root } = fixture(), real = join(root, 'real'), link = join(root, 'link')
  mkdirSync(real); symlinkSync(real, link)
  const target = join(real, 'settings.json'), file = join(link, 'settings.json')
  writeFileSync(target, 'old')
  const alias = join(root, 'alias.json'); symlinkSync(file, alias)
  await prepared(alias).replace('new')
  expect(realpathSync(alias)).toBe(target)
  expect(readFileSync(target, 'utf8')).toBe('new')
})

it('retains an intervening peer edit instead of overwriting a stale snapshot', async () => {
  const { file } = fixture()
  writeFileSync(file, 'before')
  const old = prepared(file)
  writeFileSync(file, 'peer edit')
  await expect(old.replace('ours')).rejects.toThrow(/changed/)
  await expect(old.remove()).rejects.toThrow(/changed/)
  expect(readFileSync(file, 'utf8')).toBe('peer edit')
})

it('refuses a replaced config alias and leaves both destinations untouched', async () => {
  const { root, file } = fixture(), first = join(root, 'first'), second = join(root, 'second')
  writeFileSync(first, 'one'); writeFileSync(second, 'two'); symlinkSync(first, file)
  const old = prepared(file)
  unlinkSync(file); symlinkSync(second, file)
  await expect(old.replace('ours')).rejects.toThrow(/changed/)
  expect(readFileSync(first, 'utf8')).toBe('one')
  expect(readFileSync(second, 'utf8')).toBe('two')
})

it('refuses directories, dangling aliases, oversized settings and read-only files', async () => {
  const { root, file } = fixture()
  expect(() => inspectHookFile(root)).toThrow()
  symlinkSync(join(root, 'absent'), file)
  expect(() => inspectHookFile(file)).toThrow()
  unlinkSync(file); writeFileSync(file, 'x'.repeat(1024 * 1024 + 1))
  expect(() => inspectHookFile(file)).toThrow(/bounded/)
  writeFileSync(file, 'foreign'); chmodSync(file, 0o444)
  await expect(prepared(file).replace('ours')).rejects.toThrow(/read-only/)
  expect(readFileSync(file, 'utf8')).toBe('foreign')
})

it('does not truncate the prior file or leave staging files after a write failure', async () => {
  const { root, file } = fixture()
  writeFileSync(file, 'previous'); fault.write = true
  await expect(prepared(file).replace('new')).rejects.toThrow(/disk full/)
  expect(readFileSync(file, 'utf8')).toBe('previous')
  expect(readdirSync(root)).toEqual(['config.json'])
  fault.write = false
  await prepared(file).replace('new')
  expect(readFileSync(file, 'utf8')).toBe('new')
})

it('cannot acknowledge a failed sync even when the desired bytes already exist', async () => {
  const { file } = fixture()
  writeFileSync(file, 'already prepared'); fault.sync = true
  await expect(prepared(file).replace('already prepared')).rejects.toThrow(/sync unavailable/)
  fault.sync = false
  await expect(prepared(file).replace('already prepared')).resolves.toBeDefined()
})

it('confirms unchanged Windows settings without a writable reopen that would bump ctime', async () => {
  const { file } = fixture()
  writeFileSync(file, 'already prepared')
  fault.windows = true
  await expect(prepared(file).replace('already prepared')).resolves.toBeDefined()
  expect(fault.writableOpens).toBe(0)
})

it('retains removal uncertainty until a retry can sync the parent directory', async () => {
  const { file } = fixture()
  writeFileSync(file, 'owned'); fault.sync = true
  await expect(prepared(file).remove()).rejects.toThrow(/sync unavailable/)
  expect(inspectHookFile(file).content).toBeNull()
  await expect(prepared(file).remove()).rejects.toThrow(/sync unavailable/)
  fault.sync = false
  await expect(prepared(file).remove()).resolves.toBeDefined()
})

it('holds invalid UTF-8 without replacing its original bytes', async () => {
  const { file } = fixture(), bytes = Buffer.from([0x7b, 0xff, 0x7d])
  writeFileSync(file, bytes)
  expect(() => inspectHookFile(file)).toThrow()
  expect(readFileSync(file)).toEqual(bytes)
})

it('does not acknowledge a destination changed while its parent is being synced', async () => {
  const { file } = fixture()
  writeFileSync(file, 'old')
  fault.onSync = fd => {
    if (fstatSync(fd).isDirectory()) { fault.onSync = undefined; writeFileSync(file, 'peer replacement') }
  }
  await expect(prepared(file).replace('ours')).rejects.toThrow(/changed/)
  expect(readFileSync(file, 'utf8')).toBe('peer replacement')
})

it('does not acknowledge a removed plugin recreated during parent sync', async () => {
  const { file } = fixture()
  writeFileSync(file, 'managed')
  fault.onSync = fd => {
    if (fstatSync(fd).isDirectory()) { fault.onSync = undefined; writeFileSync(file, 'recreated') }
  }
  await expect(prepared(file).remove()).rejects.toThrow(/recreated/)
  expect(readFileSync(file, 'utf8')).toBe('recreated')
})

it('holds a plugin alias without deleting its shared target or the alias', async () => {
  const { root, file } = fixture(), target = join(root, 'shared.js')
  writeFileSync(target, 'shared plugin'); symlinkSync(target, file)
  await expect(prepared(file).remove()).rejects.toThrow(/alias/)
  expect(realpathSync(file)).toBe(target)
  expect(readFileSync(target, 'utf8')).toBe('shared plugin')
})

it('reconfirms an ancestor name left uncertain by an earlier failed parent sync', async () => {
  const { root } = fixture(), file = join(root, 'a', 'b', 'hooks.json'), inode = statSync(root).ino
  fault.onSync = fd => { if (fstatSync(fd).ino === inode) throw new Error('fixture ancestor publication unavailable') }
  await expect(prepared(file).replace('new')).rejects.toThrow(/ancestor publication/)
  let confirmed = false
  fault.onSync = fd => { if (fstatSync(fd).ino === inode) confirmed = true }
  await prepared(file).replace('new')
  expect(confirmed).toBe(true)
  expect(readFileSync(file, 'utf8')).toBe('new')
})

it('compares the unchanged file descriptor with the reviewed inode before syncing', async () => {
  const { root, file } = fixture(), other = join(root, 'other')
  writeFileSync(file, 'same'); writeFileSync(other, 'same')
  const observed = inspectHookFile(file)
  await expect(runHookPreparation([file], attempt => {
    fault.openAs = other
    return observed.replace('same', attempt)
  })).rejects.toThrow(/changed before sync/)
  expect(readFileSync(file, 'utf8')).toBe('same')
})


it.each(['replacement', 'in-place edit'])('preserves the destination if the staging file suffers a %s during its flush', async change => {
  const { root, file } = fixture()
  writeFileSync(file, 'original')
  fault.onSync = fd => {
    if (fstatSync(fd).isDirectory()) return
    fault.onSync = undefined
    const temporary = join(root, readdirSync(root).find(name => name.startsWith('.harness-hook-'))!)
    if (change === 'replacement') {
      const other = join(root, 'other'); writeFileSync(other, 'foreign'); renameSync(other, temporary)
    } else writeFileSync(temporary, 'foreign')
  }
  await expect(prepared(file).replace('ours')).rejects.toThrow(/staging file changed/)
  expect(readFileSync(file, 'utf8')).toBe('original')
  if (change === 'replacement') {
    const temporary = readdirSync(root).find(name => name.startsWith('.harness-hook-'))!
    expect(readFileSync(join(root, temporary), 'utf8')).toBe('foreign')
  }
})

it.each([0o022, 0o077])('preserves an existing shared file mode under umask %s', async mask => {
  const { file } = fixture()
  writeFileSync(file, 'old'); chmodSync(file, 0o660)
  const previous = process.umask(mask)
  try { await prepared(file).replace('new') } finally { process.umask(previous) }
  expect(statSync(file).mode & 0o777).toBe(0o660)
})


it('rechecks the deadline after the last filesystem observation before removal', async () => {
  const { file } = fixture()
  writeFileSync(file, 'owned')
  let now = 0, leafChecks = 0
  vi.spyOn(performance, 'now').mockImplementation(() => now)
  const observed = inspectHookFile(file)
  await expect(runHookPreparation([file], attempt => {
    fault.onStat = (path, options) => {
      if (path === file && options === undefined && ++leafChecks === 2) now = 20
    }
    return observed.remove(attempt)
  }, { timeoutMs: 10 })).rejects.toThrow(/expired/)
  expect(leafChecks).toBe(2)
  expect(readFileSync(file, 'utf8')).toBe('owned')
})