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.

17.6 KB
Raw Blame
import { createHash } from 'node:crypto'
import { mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { PNG } from 'pngjs'
import { afterAll, beforeEach, describe, expect, it } from 'vitest'
import { PACK_VERSION, decodePack } from './pack.js'
import { PetSheetError, type PetRows } from './sheet.js'
import { PetStore, PetStoreError } from './store.js'

const roots: string[] = []
afterAll(async () => {
  await Promise.all(roots.map((d) => rm(d, { recursive: true, force: true })))
})

// A 768 x 936 sheet; `seed` changes its colours, so each seed is a different source file.
function sheetPng(seed: number): Buffer {
  const png = new PNG({ width: 768, height: 936 })
  for (const row of [0, 7]) {
    for (let c = 0; c < 2; c++) {
      for (let y = 0; y < 30; y++) {
        for (let x = 0; x < 30; x++) {
          const i = ((row * 104 + 30 + y) * 768 + c * 96 + 30 + x) * 4
          png.data.set([(seed * 37) & 255, 90 + c * 40, (x * 5 + y) & 255, 255], i)
        }
      }
    }
  }
  return PNG.sync.write(png)
}

// What the defaults come to on a sheet with only idle and running drawn.
const DEFAULT_ROWS_IDLE: PetRows = { rest: 'idle', working: 'running', listening: 'idle', sending: 'idle', asking: 'idle', relaxing: 'idle' }

let work: string
let dir: string
let store: PetStore
beforeEach(async () => {
  work = await mkdtemp(join(tmpdir(), 'pet-store-'))
  roots.push(work)
  dir = join(work, 'pets')
  store = new PetStore(dir)
})

async function source(seed: number): Promise<string> {
  const path = join(work, `sheet-${seed}.png`)
  await writeFile(path, sheetPng(seed))
  return path
}

// A 768 x 936 sheet with `rows[row]` cells drawn in the given rows, each cell its own shape and colours.
function richPng(rows: Record<number, number>): Buffer {
  const png = new PNG({ width: 768, height: 936 })
  for (const [row, n] of Object.entries(rows).map(([r, n]) => [Number(r), n])) {
    for (let c = 0; c < n; c++) {
      for (let y = 0; y < 40; y++) {
        for (let x = 0; x < 30 + c * 3; x++) {
          const i = ((row * 104 + 20 + y + c) * 768 + c * 96 + 20 + x) * 4
          png.data.set([(row * 29 + c * 17) & 255, (x * 5 + row * 11) & 255, (y * 6 + c * 3) & 255, 255], i)
        }
      }
    }
  }
  return PNG.sync.write(png)
}

const hpets = async () => (await readdir(dir)).filter((n) => n.endsWith('.hpet'))

describe('PetStore', () => {
  it('prepare converts, stores the pack and the source, and returns the id', async () => {
    const { id, bytes, pet } = await store.prepare(await source(1))
    expect(id).toMatch(/^[0-9a-f]{16}$/)
    expect(pet.frames.length).toBeGreaterThan(0)
    const pack = await store.pack(id)
    expect(pack.length).toBe(bytes)
    expect(decodePack(pack).id).toBe(id)
    expect((await readdir(dir)).sort()).toEqual([`${id}.hpet`, `${id}.json`, `${id}.png`])
  })

  it('prepare passes sheet errors through', async () => {
    const bad = join(work, 'bad.png')
    await writeFile(bad, 'nope')
    await expect(store.prepare(bad)).rejects.toMatchObject({ code: 'NOT_PNG' })
  })

  it('store: same source twice → one pack', async () => {
    const path = await source(2)
    const a = await store.prepare(path)
    const b = await store.prepare(path)
    expect(b.id).toBe(a.id)
    await store.apply('claude', a.id)
    const mapping = await store.apply('codex', b.id)
    expect(mapping).toEqual({ all: null, engines: { claude: a.id, codex: a.id } })
    expect(store.mappedIds()).toEqual([a.id])
    expect(await hpets()).toEqual([`${a.id}.hpet`])
  })

  it('store: fifth distinct pack is refused', async () => {
    const ids: string[] = []
    for (const [n, target] of ['all', 'claude', 'codex', 'muse'].entries()) {
      ids.push((await store.prepare(await source(11 + n))).id)
      await store.apply(target, ids[n])
    }
    ids.push((await store.prepare(await source(15))).id)
    const err = await store.apply('gemini', ids[4]).catch((e) => e)
    expect(err).toBeInstanceOf(PetSheetError)
    expect(err).toMatchObject({ code: 'TOO_MANY', message: 'Up to 4 pets at once: reset one first' })
    expect(store.mappedIds().length).toBe(4)
    // Replacing one of the four is fine.
    await store.apply('muse', ids[4])
    expect(store.mappedIds()).toContain(ids[4])
  })

  it('store: reset removes the mapping and deletes the unreferenced pack', async () => {
    const a = await store.prepare(await source(20))
    await store.apply('all', a.id)
    const mapping = await store.reset('all')
    expect(mapping).toEqual({ all: null, engines: {} })
    expect(await readdir(dir)).toEqual(['pets.json'])
  })

  it('a replaced pack is deleted, a still-mapped one kept', async () => {
    const a = await store.prepare(await source(30))
    const b = await store.prepare(await source(31))
    await store.apply('all', a.id)
    await store.apply('claude', a.id)
    await store.apply('all', b.id)
    expect(store.mappedIds().sort()).toEqual([a.id, b.id].sort())
    await store.reset('claude')
    expect(await hpets()).toEqual([`${b.id}.hpet`])
  })

  it('a prepared pack survives another apply until it is applied', async () => {
    const a = await store.prepare(await source(40))
    const b = await store.prepare(await source(41))
    await store.apply('all', a.id)
    await store.reset('all')
    expect(await hpets()).toContain(`${b.id}.hpet`)
    await store.apply('claude', b.id)
    expect(store.mappedIds()).toEqual([b.id])
  })

  it('store: mapping survives a new PetStore on the same dir', async () => {
    const a = await store.prepare(await source(50))
    await store.apply('all', a.id)
    await store.apply('codex', a.id)
    const again = new PetStore(dir)
    expect(again.mapping()).toEqual({ all: a.id, engines: { codex: a.id } })
    expect((await again.pack(a.id)).length).toBeGreaterThan(0)
  })

  it('apply refuses an unknown id and bad targets', async () => {
    await expect(store.apply('all', 'aaaaaaaaaaaaaaaa')).rejects.toMatchObject({ code: 'UNKNOWN_PET' })
    await expect(store.apply('all', '../etc/passwd')).rejects.toMatchObject({ code: 'UNKNOWN_PET' })
    const a = await store.prepare(await source(60))
    await expect(store.apply('__proto__', a.id)).rejects.toMatchObject({ code: 'BAD_TARGET' })
    await expect(store.apply('', a.id)).rejects.toMatchObject({ code: 'BAD_TARGET' })
  })

  it('keeps the source file\'s base name (max 40 chars) in a sidecar, atomically, and sweeps it with the pack', async () => {
    const long = join(work, `${'x'.repeat(60)}.png`)
    await writeFile(long, sheetPng(70))
    const a = await store.prepare(long)
    expect(await store.name(a.id)).toBe('x'.repeat(40))
    expect(JSON.parse(await readFile(join(dir, `${a.id}.json`), 'utf8'))).toEqual({ name: 'x'.repeat(40), rows: DEFAULT_ROWS_IDLE })
    const b = await store.prepare(await source(71))
    expect(await store.name(b.id)).toBe('sheet-71')
    expect((await readdir(dir)).filter((n) => n.endsWith('.tmp'))).toEqual([])
    expect(await store.name('ffffffffffffffff')).toBe('')
    await store.apply('all', b.id)
    await store.reset('all')
    expect((await readdir(dir)).filter((f) => f.startsWith(b.id))).toEqual([]) // pack, source and name go together
  })

  it('engine names are capped at 15 chars (the dial keeps 15) and at most 8 engines get their own pet', async () => {
    const a = await store.prepare(await source(80))
    await expect(store.apply('x'.repeat(16), a.id)).rejects.toMatchObject({ code: 'BAD_TARGET' })
    await store.apply('x'.repeat(15), a.id)
    for (let n = 1; n < 8; n++) await store.apply(`engine${n}`, a.id)
    const err = await store.apply('ninth', a.id).catch((e) => e)
    expect(err).toBeInstanceOf(PetStoreError)
    expect(err.message).toBe('Up to 8 engines can have their own pet')
    await store.apply('engine3', a.id) // replacing one of the eight is fine
    await store.reset('engine3')
    await store.apply('ninth', a.id)
  })

  it('mapping() returns a copy', async () => {
    const m = store.mapping()
    m.all = 'x'
    expect(store.mapping().all).toBeNull()
  })

  it('re-prepares a pack whose version byte is not the current one when its source is kept', async () => {
    const a = await store.prepare(await source(90))
    const file = join(dir, `${a.id}.hpet`)
    const old = await readFile(file)
    old[4] = 0
    await writeFile(file, old)
    const pack = await store.pack(a.id)
    expect(pack[4]).toBe(PACK_VERSION)
    expect(decodePack(pack).id).toBe(a.id)
    expect((await readFile(file))[4]).toBe(PACK_VERSION)
  })

  it('shares the directory with another store: a mapping written there is not overwritten or swept here', async () => {
    const other = new PetStore(dir)
    const x = await store.prepare(await source(91))
    await store.apply('claude', x.id)
    const y = await other.prepare(await source(92))
    await other.apply('codex', y.id)
    expect(other.mapping().engines).toEqual({ claude: x.id, codex: y.id })
    await store.reset('claude')
    expect(store.mapping().engines).toEqual({ codex: y.id })
    expect(await hpets()).toEqual([`${y.id}.hpet`])
    expect(JSON.parse(await readFile(join(dir, 'pets.json'), 'utf8')).engines).toEqual({ codex: y.id })
  })

  it('previews that were never applied do not pile up: mapped plus the newest four stay', async () => {
    const mapped = await store.prepare(await source(100))
    await store.apply('all', mapped.id)
    const previews: string[] = []
    for (let n = 0; n < 7; n++) previews.push((await store.prepare(await source(101 + n))).id)
    expect((await hpets()).sort()).toEqual([mapped.id, ...previews.slice(-4)].map((id) => `${id}.hpet`).sort())
  })

  // Recorded before the row choice existed: without one, a sheet is the very pack (and id) it always was.
  it('without a row choice, the pack and its id are what they were before rows could be chosen', async () => {
    const golden = [
      ['rich', { 0: 3, 3: 2, 5: 1, 6: 2, 7: 4, 8: 2 }, '4ccbe14a80622e7b', 'cda81b4c9f49e6838f8f5989d1e02ec9a0122871f2d1b15acba8c4627a6f9c00'],
      ['plain', { 0: 2, 7: 2 }, '2a6b49cb7b84e278', '9379ef4e9797277e26c15accb15510a70c72b5ff177419aecc891ec8104ffbed'],
      ['wavy', { 0: 4, 3: 3, 7: 1 }, '04b4f64fa278e7c7', '87af31113da33abfb05a0820920120950c1be4e761bec804fcda216e3a0a0076'],
    ] as const
    for (const [label, rows, id, sha] of golden) {
      const path = join(work, `${label}.png`)
      await writeFile(path, richPng(rows))
      expect((await store.prepare(path)).id).toBe(id)
      // ...and the version 1 pack is byte for byte what it was; the pack on disk is version 2, with the same id.
      expect(createHash('sha256').update(await store.pack(id, 1)).digest('hex')).toBe(sha)
      expect((await store.pack(id))[4]).toBe(2)
      expect(decodePack(await store.pack(id)).id).toBe(id)
      // Naming the defaults is no choice at all, and neither is naming what they fall back to.
      const named = await store.prepare(path, undefined, { rest: 'idle', working: 'running', listening: 'review', sending: 'waving', asking: 'waiting' })
      expect(named.id).toBe(id)
    }
    const plain = join(work, 'plain.png')
    expect((await store.prepare(plain, undefined, { listening: 'idle' })).id).toBe('2a6b49cb7b84e278')
  })

  it('a different row choice is a different pack, and its choice is kept beside its name', async () => {
    const path = join(work, 'rich.png')
    await writeFile(path, richPng({ 0: 3, 3: 2, 5: 1, 6: 2, 7: 4, 8: 2 }))
    const plain = await store.prepare(path)
    expect(plain.rows).toEqual({ rest: 'idle', working: 'running', listening: 'review', sending: 'waving', asking: 'waiting', relaxing: 'idle' })
    const swapped = await store.prepare(path, 'Swapped', { working: 'review', listening: 'running', asking: 'jumping' })
    expect(swapped.id).not.toBe(plain.id)
    const rows: PetRows = { rest: 'idle', working: 'review', listening: 'running', sending: 'waving', asking: 'idle', relaxing: 'idle' }
    expect(swapped.rows).toEqual(rows)
    expect(swapped.sheet.rows.idle.length).toBe(3)
    expect(JSON.parse(await readFile(join(dir, `${swapped.id}.json`), 'utf8'))).toEqual({ name: 'Swapped', rows })
    expect(await store.rows(swapped.id)).toEqual(rows)
    expect(decodePack(await store.pack(swapped.id)).working.frames.length).toBe(2)
    // The same choice again is the same pack.
    expect((await store.prepare(path, 'Swapped', { working: 'review', listening: 'running', asking: 'jumping' })).id).toBe(swapped.id)
  })

  it('relaxing joins the id only when it is not the rest row; the sidecar keeps it', async () => {
    const path = join(work, 'rich.png')
    await writeFile(path, richPng({ 0: 3, 3: 2, 5: 1, 6: 2, 7: 4, 8: 2 }))
    const plain = await store.prepare(path)
    expect(plain.id).toBe('4ccbe14a80622e7b')
    // Naming the rest row for relaxing is no choice.
    expect((await store.prepare(path, undefined, { relaxing: 'idle' })).id).toBe(plain.id)
    const calm = await store.prepare(path, 'Calm', { relaxing: 'review' })
    expect(calm.id).not.toBe(plain.id)
    expect(calm.rows.relaxing).toBe('review')
    expect(JSON.parse(await readFile(join(dir, `${calm.id}.json`), 'utf8')).rows.relaxing).toBe('review')
    expect((await store.rows(calm.id))?.relaxing).toBe('review')
    // It differs from the other choices too, and it is its own scene in the pack.
    expect((await store.prepare(path, undefined, { relaxing: 'waving' })).id).not.toBe(calm.id)
    const pack = decodePack(await store.pack(calm.id))
    expect(pack.relaxing.frames.length).toBe(2)
    expect(decodePack(await store.pack(calm.id, 1)).relaxing.frames).toEqual([])
    // A relaxing row with no frames falls back to rest; with another rest, relaxing follows it.
    expect((await store.prepare(path, undefined, { relaxing: 'jumping' })).rows.relaxing).toBe('idle')
    const rested = await store.prepare(path, undefined, { rest: 'review' })
    expect(rested.rows.relaxing).toBe('review')
    expect(rested.id).toBe((await store.prepare(path, undefined, { rest: 'review', relaxing: 'review' })).id)
  })

  it('version 1 is made from the kept source for an older dial, with the same id and without storing it', async () => {
    const a = await store.prepare(await source(95))
    const v1 = await store.pack(a.id, 1)
    expect(v1[4]).toBe(1)
    expect(decodePack(v1).id).toBe(a.id)
    expect((await readFile(join(dir, `${a.id}.hpet`)))[4]).toBe(2)
    expect(await hpets()).toEqual([`${a.id}.hpet`])
    // Without the source there is only the pack that is there.
    await rm(join(dir, `${a.id}.png`))
    expect((await store.pack(a.id, 1))[4]).toBe(2)
  })

  it('a version 2 rebuild that cannot be made falls back to the stored older pack; a source of another pet never replaces it', async () => {
    const a = await store.prepare(await source(97))
    const file = join(dir, `${a.id}.hpet`)
    const v1 = await store.pack(a.id, 1)
    await writeFile(file, v1) // the pack on disk is version 1
    // A source that no longer parses: the stored version 1 is handed out as it is.
    await writeFile(join(dir, `${a.id}.png`), Buffer.from('not a png'))
    expect(await store.pack(a.id, 2)).toEqual(v1)
    // A source that makes another pet: not written over the stored pack, and the stored pack is served.
    await writeFile(join(dir, `${a.id}.png`), sheetPng(98))
    expect(await store.pack(a.id, 2)).toEqual(v1)
    expect(await readFile(file)).toEqual(v1)
    // The stored pack is newer than the dial reads and cannot be remade: that is an error.
    await writeFile(file, await store.pack(a.id, 2).catch(() => v1))
    const v2 = Buffer.from(v1)
    v2[4] = 2
    await writeFile(file, v2)
    await expect(store.pack(a.id, 1)).rejects.toThrow()
  })

  it('a sidecar from before relaxing has it follow the rest row', async () => {
    const a = await store.prepare(await source(96))
    await writeFile(join(dir, `${a.id}.json`), JSON.stringify({ name: 'old', rows: { rest: 'idle', working: 'running', listening: 'idle', sending: 'idle', asking: 'idle' } }))
    expect(await store.rows(a.id)).toEqual(DEFAULT_ROWS_IDLE)
  })

  it('refuses an empty chosen rest or working row', async () => {
    await expect(store.prepare(await source(120), undefined, { working: 'jumping' })).rejects.toMatchObject({ code: 'NO_WORKING' })
    await expect(store.prepare(await source(120), undefined, { rest: 'waving' })).rejects.toMatchObject({ code: 'NO_REST' })
  })

  it('re-prepares an old pack with the row choice it was made with', async () => {
    const path = join(work, 'rich.png')
    await writeFile(path, richPng({ 0: 3, 3: 2, 5: 1, 6: 2, 7: 4, 8: 2 }))
    const a = await store.prepare(path, undefined, { rest: 'review', working: 'waiting' })
    const file = join(dir, `${a.id}.hpet`)
    const fresh = await readFile(file)
    const old = Buffer.from(fresh)
    old[4] = 0
    await writeFile(file, old)
    expect(await store.pack(a.id)).toEqual(fresh)
  })

  it('rows: null for an unknown id, a sidecar without rows, or one with a bad row', async () => {
    expect(await store.rows('nope')).toBeNull()
    expect(await store.rows('ffffffffffffffff')).toBeNull()
    const a = await store.prepare(await source(130))
    await writeFile(join(dir, `${a.id}.json`), JSON.stringify({ name: 'old' }))
    expect(await store.rows(a.id)).toBeNull()
    await writeFile(join(dir, `${a.id}.json`), JSON.stringify({ name: 'old', rows: { ...DEFAULT_ROWS_IDLE, rest: 'sideways' } }))
    expect(await store.rows(a.id)).toBeNull()
    // A pack re-made from a sidecar without rows uses the defaults, as it was made before rows could be chosen.
    await writeFile(join(dir, `${a.id}.json`), JSON.stringify({ name: 'old' }))
    const file = join(dir, `${a.id}.hpet`)
    const fresh = await readFile(file)
    const old = Buffer.from(fresh)
    old[4] = 0
    await writeFile(file, old)
    expect(await store.pack(a.id)).toEqual(fresh)
  })
})