@adea-ai/plugins 4.0.0 → 4.0.1

package/src/write-artifacts.test.ts

@@ -0,0 +1,375 @@
+import { spawnSync } from 'node:child_process'
+import {
+  mkdtemp,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  symlink,
+  utimes,
+  writeFile,
+} from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, test } from 'bun:test'
+import {
+  catalogFingerprint,
+  withCatalogRead,
+  writeArtifacts,
+  type GeneratedArtifacts,
+  type PublicationStep,
+} from './index.js'
+import { catalogPathsIn } from './catalog-store.js'
+
+const artifacts = (name: string) =>
+  ({ 'catalog.v1.json': name, 'integrity.json': name }) as GeneratedArtifacts
+
+const child = fileURLToPath(new URL('../test-support/catalog-writer-child.ts', import.meta.url))
+
+/** Runs a writer in its own process, optionally with its own TMPDIR. */
+function runWriter(
+  output: string,
+  content: string,
+  crashAt: PublicationStep | 'none',
+  options: { waitMs?: number; tmp?: string } = {}
+) {
+  const result = spawnSync(
+    process.execPath,
+    [
+      child,
+      output,
+      content,
+      crashAt,
+      ...(options.waitMs === undefined ? [] : [String(options.waitMs)]),
+    ],
+    {
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        ...(options.tmp ? { TMPDIR: options.tmp, TMP: options.tmp, TEMP: options.tmp } : {}),
+      },
+    }
+  )
+  // Windows reports a forced termination as an exit status, not a signal.
+  const killed =
+    result.signal === 'SIGKILL' || (process.platform === 'win32' && result.status !== 0)
+  return { stdout: result.stdout.trim(), stderr: result.stderr, killed }
+}
+
+/** A promise the test resolves to let a paused writer continue. */
+function gate() {
+  let open!: () => void
+  const opened = new Promise<void>((resolve) => {
+    open = resolve
+  })
+  return { open, opened }
+}
+
+async function withParent(run: (parent: string) => Promise<void>) {
+  const parent = await mkdtemp(join(tmpdir(), 'catalog-writers-'))
+  try {
+    await run(parent)
+  } finally {
+    await rm(parent, { recursive: true, force: true })
+  }
+}
+
+const read = (output: string) => readFile(join(output, 'catalog.v1.json'), 'utf8')
+/** Coordination leftovers beside an output; a settled output has none. */
+const leftovers = async (parent: string) =>
+  (await readdir(parent)).filter(
+    (name) => name.startsWith('.catalog-') || name.endsWith('.previous')
+  )
+
+describe('writer coordination', () => {
+  test('writers with different temporary directories exclude each other', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      await writeArtifacts(output, artifacts('first'))
+      const otherTmp = join(parent, 'other-tmp')
+      await mkdir(otherTmp)
+      const paused = gate()
+      const reached = gate()
+      const holder = writeArtifacts(output, artifacts('holder'), {
+        onStep: async (step) => {
+          if (step !== 'staged') return
+          reached.open()
+          await paused.opened
+        },
+      })
+      await reached.opened
+      // The diagnosed race: the lock lived in TMPDIR, so a writer with another
+      // TMPDIR took its own lock and swapped concurrently. Both in-process and
+      // as a separate process with its own TMPDIR, the second writer now meets
+      // the first writer's lock.
+      const previousTmp = process.env.TMPDIR
+      process.env.TMPDIR = otherTmp
+      try {
+        await expect(writeArtifacts(output, artifacts('intruder'), { waitMs: 0 })).rejects.toThrow(
+          'CATALOG_WRITE_IN_PROGRESS'
+        )
+      } finally {
+        if (previousTmp === undefined) delete process.env.TMPDIR
+        else process.env.TMPDIR = previousTmp
+      }
+      const separate = runWriter(output, 'separate', 'none', { waitMs: 0, tmp: otherTmp })
+      expect(separate.stdout).toContain('CATALOG_WRITE_IN_PROGRESS')
+      expect(await read(output)).toBe('first')
+      paused.open()
+      await holder
+      expect(await read(output)).toBe('holder')
+      expect(await readdir(otherTmp)).toEqual([])
+      expect(await leftovers(parent)).toEqual([])
+    }))
+
+  test('a waiting writer publishes after the holder, never in between', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      const steps: string[] = []
+      const paused = gate()
+      const reached = gate()
+      const first = writeArtifacts(output, artifacts('first'), {
+        onStep: async (step) => {
+          steps.push(`first:${step}`)
+          if (step !== 'backed-up') return
+          reached.open()
+          await paused.opened
+        },
+      })
+      await reached.opened
+      const contending = gate()
+      const second = writeArtifacts(output, artifacts('second'), {
+        pollMs: 1,
+        onStep: (step) => {
+          steps.push(`second:${step}`)
+          if (step === 'acquiring') contending.open()
+        },
+      })
+      await contending.opened
+      // Let the second writer poll the held lock a few times.
+      await new Promise((resolve) => setTimeout(resolve, 20))
+      paused.open()
+      await Promise.all([first, second])
+      expect(steps).toEqual([
+        'first:acquiring',
+        'first:staged',
+        'first:backed-up',
+        'second:acquiring',
+        'first:swapped',
+        'first:cleaned',
+        'second:staged',
+        'second:backed-up',
+        'second:swapped',
+        'second:cleaned',
+      ])
+      expect(await read(output)).toBe('second')
+      expect(await leftovers(parent)).toEqual([])
+    }))
+
+  test('outputs that differ only in case share one lock', () => {
+    expect(catalogPathsIn('/x', 'Generated').lock).toBe(catalogPathsIn('/x', 'generated').lock)
+    expect(catalogPathsIn('/x', 'generated').lock).not.toBe(catalogPathsIn('/x', 'other').lock)
+    expect(
+      catalogPathsIn('/x', 'generated').lock.startsWith(join('/x', '.catalog-generated-'))
+    ).toBe(true)
+  })
+})
+
+describe('publication against a read snapshot', () => {
+  test('refuses to overwrite a catalog replaced after the base was read', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      await writeArtifacts(output, artifacts('base'))
+      // The diagnosed race: a scoped sync validated the output and read its
+      // lock, another writer replaced the catalog, and the sync then published
+      // over it. The base read and the publication now compare fingerprints.
+      const base = await withCatalogRead(output, () => catalogFingerprint(output))
+      await writeArtifacts(output, artifacts('concurrent'))
+      await expect(
+        writeArtifacts(output, artifacts('stale'), { expectedBase: base })
+      ).rejects.toThrow('CATALOG_BASE_CHANGED')
+      expect(await read(output)).toBe('concurrent')
+      const fresh = await withCatalogRead(output, () => catalogFingerprint(output))
+      await writeArtifacts(output, artifacts('rebased'), { expectedBase: fresh })
+      expect(await read(output)).toBe('rebased')
+      expect(await leftovers(parent)).toEqual([])
+    }))
+
+  test('an absent output is a base, and a first publication must still find it absent', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      const base = await withCatalogRead(output, () => catalogFingerprint(output))
+      expect(base).toBe('absent')
+      await writeArtifacts(output, artifacts('other'))
+      await expect(
+        writeArtifacts(output, artifacts('mine'), { expectedBase: base })
+      ).rejects.toThrow('CATALOG_BASE_CHANGED')
+      expect(await read(output)).toBe('other')
+    }))
+
+  test('a coordinated reader never observes the swap window', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      await writeArtifacts(output, artifacts('old'))
+      const paused = gate()
+      const reached = gate()
+      const writer = writeArtifacts(output, artifacts('new'), {
+        onStep: async (step) => {
+          if (step !== 'backed-up') return
+          reached.open()
+          await paused.opened
+        },
+      })
+      await reached.opened
+      // Between the renames the output does not exist on disk.
+      await expect(read(output)).rejects.toThrow()
+      const reader = withCatalogRead(output, () => read(output), { pollMs: 1 })
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      paused.open()
+      expect(await reader).toBe('new')
+      await writer
+    }))
+})
+
+describe('crash recovery', () => {
+  const cases: readonly { step: PublicationStep; expected: string }[] = [
+    { step: 'staged', expected: 'old' },
+    { step: 'backed-up', expected: 'old' },
+    { step: 'swapped', expected: 'new' },
+    { step: 'cleaned', expected: 'new' },
+  ]
+  for (const { step, expected } of cases) {
+    test(`a writer killed after "${step}" is ${expected === 'old' ? 'rolled back' : 'completed'} by the next reader`, () =>
+      withParent(async (parent) => {
+        const output = join(parent, 'generated')
+        await writeArtifacts(output, artifacts('old'))
+        const crashed = runWriter(output, 'new', step)
+        expect(crashed.killed).toBe(true)
+        expect(crashed.stdout).toBe('')
+        // The killed process left its lock behind; its holder is gone.
+        expect((await readdir(parent)).some((name) => name.endsWith('.lock'))).toBe(true)
+        expect(await withCatalogRead(output, () => read(output), { waitMs: 0 })).toBe(expected)
+        expect(await leftovers(parent)).toEqual([])
+        await writeArtifacts(output, artifacts('after'), { waitMs: 0 })
+        expect(await read(output)).toBe('after')
+      }))
+  }
+
+  test('a writer killed during a first publication leaves no output and no residue', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      expect(runWriter(output, 'new', 'staged').killed).toBe(true)
+      await writeArtifacts(output, artifacts('next'), { waitMs: 0 })
+      expect(await read(output)).toBe('next')
+      expect(await leftovers(parent)).toEqual([])
+    }))
+
+  test('a holder on another host is broken only after its heartbeat lease expires', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      await writeArtifacts(output, artifacts('old'))
+      const { lock, owner } = catalogPathsIn(parent, 'generated')
+      await mkdir(lock)
+      await writeFile(owner, JSON.stringify({ token: 'remote', pid: 1, host: 'elsewhere.invalid' }))
+      await expect(
+        writeArtifacts(output, artifacts('blocked'), { waitMs: 0, staleAfterMs: 60_000 })
+      ).rejects.toThrow(/CATALOG_WRITE_IN_PROGRESS: .*pid 1 on elsewhere\.invalid/)
+      const old = new Date(Date.now() - 120_000)
+      await utimes(owner, old, old)
+      await writeArtifacts(output, artifacts('new'), { waitMs: 0, staleAfterMs: 60_000 })
+      expect(await read(output)).toBe('new')
+      expect(await leftovers(parent)).toEqual([])
+    }))
+
+  test('a holder that lost its lock refuses to swap', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      await writeArtifacts(output, artifacts('old'))
+      const { lock, owner } = catalogPathsIn(parent, 'generated')
+      const writer = writeArtifacts(output, artifacts('late'), {
+        onStep: async (step) => {
+          if (step !== 'staged') return
+          // Another contender judged this holder stale and took the lock.
+          await rename(lock, `${lock}.taken`)
+          await mkdir(lock)
+          await writeFile(owner, JSON.stringify({ token: 'other', pid: process.pid, host: 'x' }))
+        },
+      })
+      await expect(writer).rejects.toThrow('CATALOG_LOCK_LOST')
+      expect(await read(output)).toBe('old')
+      expect(JSON.parse(await readFile(owner, 'utf8')).token).toBe('other')
+    }))
+
+  test('preserves a backup whose provenance is unknown', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      await mkdir(output)
+      await writeFile(join(output, 'catalog.v1.json'), 'current')
+      await mkdir(`${output}.previous`)
+      await writeFile(join(`${output}.previous`, 'recovery'), 'saved')
+      await expect(writeArtifacts(output, artifacts('blocked'))).rejects.toThrow(
+        'CATALOG_RECOVERY_REQUIRED'
+      )
+      expect(await readFile(join(`${output}.previous`, 'recovery'), 'utf8')).toBe('saved')
+      expect(await read(output)).toBe('current')
+      expect(await withCatalogRead(output, () => read(output))).toBe('current')
+      expect(await readFile(join(`${output}.previous`, 'recovery'), 'utf8')).toBe('saved')
+    }))
+
+  test('a failed write keeps the previous catalog and releases the lock', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      await writeArtifacts(output, artifacts('previous'))
+      await expect(
+        writeArtifacts(output, { ...artifacts('broken'), 'missing/file': 'bad' })
+      ).rejects.toThrow('CATALOG_ARTIFACT_NAME_INVALID')
+      await expect(
+        writeArtifacts(output, artifacts('broken'), {
+          onStep: (step) => {
+            if (step === 'backed-up') throw new Error('injected failure')
+          },
+        })
+      ).rejects.toThrow('injected failure')
+      expect(await read(output)).toBe('previous')
+      expect(await leftovers(parent)).toEqual([])
+      await writeArtifacts(output, artifacts('later'), { waitMs: 0 })
+      expect(await read(output)).toBe('later')
+    }))
+})
+
+describe('reserved paths', () => {
+  test('refuses outputs inside coordination files or backups', () =>
+    withParent(async (parent) => {
+      const output = join(parent, 'generated')
+      const { lock } = catalogPathsIn(parent, 'generated')
+      for (const destination of [lock, `${output}.previous`, join(`${output}.previous`, 'x')])
+        await expect(writeArtifacts(destination, artifacts('blocked'))).rejects.toThrow(
+          'CATALOG_WRITE_LOCK_RESERVED'
+        )
+      await mkdir(lock)
+      const alias = join(parent, 'lock-alias')
+      await symlink(lock, alias, 'dir')
+      await expect(writeArtifacts(join(alias, 'nested'), artifacts('blocked'))).rejects.toThrow(
+        'CATALOG_WRITE_LOCK_RESERVED'
+      )
+      await rm(lock, { recursive: true })
+      // A backup can still be read by hand, without coordination.
+      await mkdir(`${output}.previous`)
+      await writeFile(join(`${output}.previous`, 'catalog.v1.json'), 'saved')
+      expect(await withCatalogRead(`${output}.previous`, () => read(`${output}.previous`))).toBe(
+        'saved'
+      )
+    }))
+
+  test('preserves filesystem semantics for a symlink followed by dot dot', () =>
+    withParent(async (parent) => {
+      const real = join(parent, 'real')
+      await mkdir(join(real, 'child'), { recursive: true })
+      await symlink(join(real, 'child'), join(parent, 'link'), 'dir')
+      await writeArtifacts(`${parent}/link/../generated`, artifacts('real target'))
+      expect(await read(join(real, 'generated'))).toBe('real target')
+      await expect(read(join(parent, 'generated'))).rejects.toThrow()
+    }))
+})

package/native/README.md

@@ -1,24 +0,0 @@
-# Windows staged reader
-
-The Windows reader opens the final path component with `CreateFileW` and
-`FILE_FLAG_OPEN_REPARSE_POINT`, refuses reparse points, directories and non-disk
-handles, then reads from that same handle on a Node-API async worker. The parent
-directory remains trusted, and regular-file contents may change through another
-handle. This is not filesystem confinement or a snapshot. The Windows reader
-caps input at 512 MiB and returns no bytes on failure; the POSIX reader retains
-its existing behavior. Missing paths retain `ENOENT`.
-
-`scripts/build-staged-reader.sh` builds x64 and arm64 modules on Linux from
-Zig 0.14.1 and Node 24.22.1 headers and import libraries, checking each pinned
-SHA-256 before use. It records the source commit and output hashes in
-`build-provenance.txt`. There is no runtime download or installation hook.
-The release workflow builds the modules before packing them; the package
-includes only the production modules and provenance, while the repository root
-build copies available production modules beside the compiled reader. Missing,
-invalid, or unsupported binaries fail closed.
-
-The Windows qualification workflow builds the same sources and exercises both
-architectures with Node and Bun, including size limits and concurrent pathname
-replacement. It also checks the source and compiled reader layouts. A successful
-cross-compile alone does not establish Windows compatibility; in particular,
-Bun's Windows loader must be tested with the Node import library.