Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
27d8131a3This file is pinned to the selected release. Download the original to open it in your design tool.
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { execFileSync } from 'node:child_process'
import { createHash } from 'node:crypto'
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { dirname, join } from 'node:path'
import { tmpdir } from 'node:os'
let root = ''
let runtimeDir = ''
let binDir = ''
let cliDir = ''
async function load() {
vi.resetModules()
process.env.ADAPTER_RUNTIME_DIR = runtimeDir
process.env.HARNESS_BIN_DIR = binDir
process.env.ADAPTER_CLI_DIR = cliDir
process.env.ADAPTER_RUNTIME_METADATA_URL = 'https://example.test/runtime/metadata.json'
process.env.ADAPTER_GRID_RUNTIME_METADATA_URL = 'https://example.test/runtime/grid/metadata.json'
delete process.env.HARNESS_GRID_BIN
return import('./runtimeInstall.js')
}
/** A real gzipped tarball laid out the way every managed runtime ships — `<name>-<version>-<key>/bin/<name>`
* (nodejs.org's own shape, which tmux and grid copy) — with a runnable binary inside. */
function buildArchive(version: string, key: string, name: string = 'node'): { bytes: Buffer; root: string } {
const archiveRoot = `${name}-${version}-${key}`
const source = join(root, 'src', archiveRoot)
rmSync(source, { recursive: true, force: true })
mkdirSync(join(source, archiveRoot, 'bin'), { recursive: true })
writeFileSync(join(source, archiveRoot, 'bin', name), '#!/bin/sh\nexit 0\n', { mode: 0o755 })
const archive = join(root, `${archiveRoot}.tar.gz`)
execFileSync('/usr/bin/tar', ['-czf', archive, '-C', source, archiveRoot])
return { bytes: readFileSync(archive), root: archiveRoot }
}
/** A manifest of the shape every managed runtime publishes: `{ <name>: { <platform>: entry } }`. */
function manifestFor(name: string, key: string, version: string, bytes: Buffer, root: string, overrides: Record<string, unknown> = {}): unknown {
return {
[name]: {
[key]: {
version,
url: `https://example.test/runtime/${name}/${root}.tar.gz`,
sha256: createHash('sha256').update(bytes).digest('hex'),
size: bytes.length,
archiveRoot: root,
...overrides,
},
},
}
}
/** A grid already laid down under the runtime dir, the way an earlier ensure leaves it. */
function installedGrid(version: string, key: string, current: boolean): string {
const dir = join(runtimeDir, `grid-${version}-${key}`, 'bin')
mkdirSync(dir, { recursive: true })
const bin = join(dir, 'grid')
writeFileSync(bin, '#!/bin/sh\nexit 0\n', { mode: 0o755 })
if (current) writeFileSync(join(runtimeDir, 'current-grid'), `${bin}\n`)
return bin
}
function currentPlatformKey(): string {
const os = process.platform === 'darwin' ? 'darwin' : 'linux'
return `${os}-${process.arch === 'arm64' ? 'arm64' : 'x64'}`
}
/** Serves the manifest and the archive; any other URL is a test bug. */
function stubFetch(manifest: unknown, archive?: Buffer): void {
vi.stubGlobal('fetch', async (input: string | URL) => {
const url = String(input)
if (url.endsWith('metadata.json')) {
return { ok: true, json: async () => manifest } as unknown as Response
}
if (archive && url.endsWith('.tar.gz')) {
return { ok: true, arrayBuffer: async () => archive.buffer.slice(archive.byteOffset, archive.byteOffset + archive.byteLength) } as unknown as Response
}
return { ok: false, status: 404 } as unknown as Response
})
}
describe('ensureManagedRuntime', () => {
beforeEach(() => {
root = mkdtempSync(join(tmpdir(), 'harness-runtime-install-'))
runtimeDir = join(root, '.harness', 'runtime')
binDir = join(root, '.local', 'bin')
cliDir = join(root, '.harness', 'cli')
mkdirSync(runtimeDir, { recursive: true })
mkdirSync(binDir, { recursive: true })
mkdirSync(cliDir, { recursive: true })
})
afterEach(() => {
vi.unstubAllGlobals()
rmSync(root, { recursive: true, force: true })
for (const key of ['ADAPTER_RUNTIME_DIR', 'HARNESS_BIN_DIR', 'ADAPTER_CLI_DIR', 'ADAPTER_RUNTIME_METADATA_URL', 'ADAPTER_GRID_RUNTIME_METADATA_URL', 'HARNESS_GRID_BIN']) {
delete process.env[key]
}
})
it('does nothing, and fetches nothing, when a runtime is already installed', async () => {
const node = join(runtimeDir, 'node-v22', 'bin', 'node')
mkdirSync(join(runtimeDir, 'node-v22', 'bin'), { recursive: true })
writeFileSync(node, '#!/bin/sh\nexit 0\n', { mode: 0o755 })
writeFileSync(join(runtimeDir, 'current-node'), `${node}\n`)
const fetchSpy = vi.fn()
vi.stubGlobal('fetch', fetchSpy)
const { ensureManagedRuntime } = await load()
expect(await ensureManagedRuntime()).toBe(node)
expect(fetchSpy).not.toHaveBeenCalled()
})
it('downloads, verifies and unpacks a runtime, then records it', async () => {
const key = currentPlatformKey()
const { bytes, root: archiveRoot } = buildArchive('v22.23.2', key)
stubFetch({
node: {
[key]: {
version: 'v22.23.2',
url: 'https://example.test/runtime/node.tar.gz',
sha256: createHash('sha256').update(bytes).digest('hex'),
size: bytes.length,
archiveRoot,
},
},
}, bytes)
const { ensureManagedRuntime } = await load()
const node = await ensureManagedRuntime()
expect(node).toBe(join(runtimeDir, `node-v22.23.2-${key}`, 'bin', 'node'))
expect(existsSync(node!)).toBe(true)
expect(readFileSync(join(runtimeDir, 'current-node'), 'utf8').trim()).toBe(node)
// Staging never survives, whatever happened.
expect(readdirSync(runtimeDir).filter((n) => n.startsWith('.node-staging-'))).toEqual([])
})
it('refuses an archive whose bytes do not match the manifest', async () => {
const key = currentPlatformKey()
const { bytes, root: archiveRoot } = buildArchive('v22.23.2', key)
stubFetch({
node: {
[key]: {
version: 'v22.23.2',
url: 'https://example.test/runtime/node.tar.gz',
sha256: 'a'.repeat(64),
size: bytes.length,
archiveRoot,
},
},
}, bytes)
const { ensureManagedRuntime } = await load()
expect(await ensureManagedRuntime()).toBeNull()
expect(existsSync(join(runtimeDir, 'current-node'))).toBe(false)
})
// Served as a fully valid, correctly-hashed archive — so the ONLY thing that can reject it is the
// scheme check. Anything less and this passes for the wrong reason.
it('refuses a plaintext archive URL even when the bytes are otherwise valid', async () => {
const key = currentPlatformKey()
const { bytes, root: archiveRoot } = buildArchive('v22.23.2', key)
stubFetch({
node: {
[key]: {
version: 'v22.23.2',
url: 'http://example.test/runtime/node.tar.gz',
sha256: createHash('sha256').update(bytes).digest('hex'),
size: bytes.length,
archiveRoot,
},
},
}, bytes)
const { ensureManagedRuntime } = await load()
expect(await ensureManagedRuntime()).toBeNull()
expect(existsSync(join(runtimeDir, 'current-node'))).toBe(false)
})
// A daemon must not fail to start because a download failed; it keeps the interpreter it has.
it('returns null instead of throwing when the manifest is unreachable', async () => {
vi.stubGlobal('fetch', async () => { throw new Error('ENOTFOUND') })
const { ensureManagedRuntime } = await load()
await expect(ensureManagedRuntime()).resolves.toBeNull()
})
})
/**
* The managed grid follows the PIN, where the managed Node stops at "one is installed": the harness
* manifest names the grid version this daemon can drive, and a pin that moved must reach a machine
* that already has an older one. Everything else — the archive shape, the staging, the pointer —
* is the runtime convention Node and tmux already use.
*/
describe('ensureManagedGrid', () => {
const key = currentPlatformKey()
beforeEach(() => {
root = mkdtempSync(join(tmpdir(), 'harness-grid-install-'))
runtimeDir = join(root, '.harness', 'runtime')
binDir = join(root, '.local', 'bin')
cliDir = join(root, '.harness', 'cli')
for (const dir of [runtimeDir, binDir, cliDir]) mkdirSync(dir, { recursive: true })
})
afterEach(() => {
vi.unstubAllGlobals()
// 0555 directories cannot be emptied as they are; give them back before the sweep.
for (const entry of readdirSync(runtimeDir)) {
try { chmodSync(join(runtimeDir, entry, 'bin'), 0o755) } catch { /* not a runtime dir */ }
}
rmSync(root, { recursive: true, force: true })
for (const key of ['ADAPTER_RUNTIME_DIR', 'HARNESS_BIN_DIR', 'ADAPTER_CLI_DIR', 'ADAPTER_RUNTIME_METADATA_URL', 'ADAPTER_GRID_RUNTIME_METADATA_URL', 'HARNESS_GRID_BIN']) {
delete process.env[key]
}
})
it('downloads, verifies and unpacks the pinned grid from its own manifest, records it, and lays it down read-only', async () => {
const { bytes, root: archiveRoot } = buildArchive('0.3.47', key, 'grid')
stubFetch(manifestFor('grid', key, '0.3.47', bytes, archiveRoot), bytes)
const { ensureManagedGrid } = await load()
const grid = await ensureManagedGrid()
expect(grid).toBe(join(runtimeDir, `grid-0.3.47-${key}`, 'bin', 'grid'))
expect(readFileSync(join(runtimeDir, 'current-grid'), 'utf8').trim()).toBe(grid)
// `grid update` replaces the binary with os.replace — a rename INTO this directory. A directory
// it cannot write to is what makes that fail loudly instead of overwriting the pin.
expect(statSync(grid!).mode & 0o777).toBe(0o555)
expect(statSync(dirname(grid!)).mode & 0o777).toBe(0o555)
expect(readdirSync(runtimeDir).filter((n) => n.startsWith('.grid-staging-'))).toEqual([])
})
it('fetches only the manifest when the installed grid IS the pin', async () => {
const installed = installedGrid('0.3.47', key, true)
const { bytes, root: archiveRoot } = buildArchive('0.3.47', key, 'grid')
const urls: string[] = []
stubFetch(manifestFor('grid', key, '0.3.47', bytes, archiveRoot), bytes)
const served = globalThis.fetch
vi.stubGlobal('fetch', async (input: string | URL) => { urls.push(String(input)); return served(input) })
const { ensureManagedGrid } = await load()
expect(await ensureManagedGrid()).toBe(installed)
expect(urls).toEqual(['https://example.test/runtime/grid/metadata.json'])
})
it('follows a pin that moved: installs the new version, keeps the one it replaces, drops older ones', async () => {
installedGrid('0.3.45', key, false)
const previous = installedGrid('0.3.46', key, true)
const { bytes, root: archiveRoot } = buildArchive('0.3.47', key, 'grid')
stubFetch(manifestFor('grid', key, '0.3.47', bytes, archiveRoot), bytes)
const { ensureManagedGrid } = await load()
const grid = await ensureManagedGrid()
expect(grid).toBe(join(runtimeDir, `grid-0.3.47-${key}`, 'bin', 'grid'))
expect(readFileSync(join(runtimeDir, 'current-grid'), 'utf8').trim()).toBe(grid)
// A pane launched before the move has the OLD directory on its PATH for as long as it lives;
// deleting it would take `grid` away from an agent mid-conversation. One version back stays.
expect(existsSync(previous)).toBe(true)
expect(existsSync(join(runtimeDir, `grid-0.3.45-${key}`))).toBe(false)
})
it('tries a pin that does not run on this computer ONCE, and remembers', async () => {
const installed = installedGrid('0.3.46', key, true)
const { bytes, root: archiveRoot } = buildArchive('0.3.47', key, 'grid')
// The archive's grid records every run, then refuses — a wrong-arch build, say.
const runs = join(root, 'runs')
const source = join(root, 'src', archiveRoot, archiveRoot, 'bin', 'grid')
writeFileSync(source, `#!/bin/sh\necho ran >> '${runs}'\nexit 1\n`, { mode: 0o755 })
execFileSync('/usr/bin/tar', ['-czf', join(root, `${archiveRoot}.tar.gz`), '-C', join(root, 'src', archiveRoot), archiveRoot])
const rebuilt = readFileSync(join(root, `${archiveRoot}.tar.gz`))
stubFetch(manifestFor('grid', key, '0.3.47', rebuilt, archiveRoot), rebuilt)
void bytes
const { ensureManagedGrid } = await load()
// The pointer stays on the grid that works, and the one that does not is marked.
expect(await ensureManagedGrid()).toBe(installed)
expect(readFileSync(join(runtimeDir, 'current-grid'), 'utf8').trim()).toBe(installed)
expect(existsSync(join(runtimeDir, `grid-0.3.47-${key}`, '.unrunnable'))).toBe(true)
// Every daemon start asks again; a start must not pay a download and a hung exec for a pin this
// computer has already refused. One manifest fetch, no second run.
expect(await ensureManagedGrid()).toBe(installed)
expect(readFileSync(runs, 'utf8')).toBe('ran\n')
})
it('refuses a manifest that pins a grid older than the floor this daemon can drive', async () => {
const installed = installedGrid('0.3.47', key, true)
const { bytes, root: archiveRoot } = buildArchive('0.3.35', key, 'grid')
stubFetch(manifestFor('grid', key, '0.3.35', bytes, archiveRoot), bytes)
const { ensureManagedGrid } = await load()
expect(await ensureManagedGrid()).toBe(installed)
expect(existsSync(join(runtimeDir, `grid-0.3.35-${key}`))).toBe(false)
expect(readFileSync(join(runtimeDir, 'current-grid'), 'utf8').trim()).toBe(installed)
})
it('leaves a developer\'s HARNESS_GRID_BIN alone: nothing fetched, nothing laid down', async () => {
const fetchSpy = vi.fn()
vi.stubGlobal('fetch', fetchSpy)
const { ensureManagedGrid } = await load()
process.env.HARNESS_GRID_BIN = '/somewhere/else/grid'
expect(await ensureManagedGrid()).toBeNull()
expect(fetchSpy).not.toHaveBeenCalled()
expect(existsSync(join(runtimeDir, 'current-grid'))).toBe(false)
})
it('keeps the grid it has when the manifest is unreachable, and has nothing when it has nothing', async () => {
vi.stubGlobal('fetch', async () => { throw new Error('ENOTFOUND') })
const { ensureManagedGrid } = await load()
await expect(ensureManagedGrid()).resolves.toBeNull()
const installed = installedGrid('0.3.47', key, true)
await expect(ensureManagedGrid()).resolves.toBe(installed)
})
it('refuses an archive whose bytes do not match the manifest, and keeps the pointer where it was', async () => {
const installed = installedGrid('0.3.46', key, true)
const { bytes, root: archiveRoot } = buildArchive('0.3.47', key, 'grid')
stubFetch(manifestFor('grid', key, '0.3.47', bytes, archiveRoot, { sha256: 'a'.repeat(64) }), bytes)
const { ensureManagedGrid } = await load()
expect(await ensureManagedGrid()).toBe(installed)
expect(readFileSync(join(runtimeDir, 'current-grid'), 'utf8').trim()).toBe(installed)
expect(existsSync(join(runtimeDir, `grid-0.3.47-${key}`))).toBe(false)
})
})
describe('startGridPinRecheck', () => {
const key = currentPlatformKey()
beforeEach(() => {
root = mkdtempSync(join(tmpdir(), 'harness-grid-recheck-'))
runtimeDir = join(root, '.harness', 'runtime')
binDir = join(root, '.local', 'bin')
cliDir = join(root, '.harness', 'cli')
for (const dir of [runtimeDir, binDir, cliDir]) mkdirSync(dir, { recursive: true })
vi.useFakeTimers({ toFake: ['setInterval', 'clearInterval'] })
})
afterEach(() => {
vi.useRealTimers()
vi.unstubAllGlobals()
for (const entry of readdirSync(runtimeDir)) {
try { chmodSync(join(runtimeDir, entry, 'bin'), 0o755) } catch { /* not a runtime dir */ }
}
rmSync(root, { recursive: true, force: true })
for (const key of ['ADAPTER_RUNTIME_DIR', 'HARNESS_BIN_DIR', 'ADAPTER_CLI_DIR', 'ADAPTER_RUNTIME_METADATA_URL', 'ADAPTER_GRID_RUNTIME_METADATA_URL', 'HARNESS_GRID_BIN']) {
delete process.env[key]
}
})
/** A snapshot of everything under the runtime dir: names, sizes and times. */
const tree = (): string[] => readdirSync(runtimeDir, { recursive: true, withFileTypes: true })
.map((entry) => { const path = join(entry.parentPath, entry.name); const st = statSync(path); return `${path}:${st.size}:${st.mtimeMs}` })
.sort()
it('re-reads the pin every ten minutes, writes nothing while it matches, and a moved pin reaches the next grid call', async () => {
const installed = installedGrid('0.3.47', key, true)
const old = buildArchive('0.3.47', key, 'grid')
stubFetch(manifestFor('grid', key, '0.3.47', old.bytes, old.root), old.bytes)
const { ensureManagedGrid, startGridPinRecheck, GRID_PIN_RECHECK_MS } = await load()
const { gridBinaryPath } = await import('./gridExec.js')
let last: Promise<unknown> = Promise.resolve()
const ensure = vi.fn(() => (last = ensureManagedGrid()))
// The check, and the bookkeeping that frees the next one.
const checked = async (): Promise<void> => { await last; await new Promise((resolve) => setImmediate(resolve)) }
const stop = startGridPinRecheck({ ensure })
const before = tree()
expect(GRID_PIN_RECHECK_MS).toBe(10 * 60_000)
vi.advanceTimersByTime(GRID_PIN_RECHECK_MS - 1)
expect(ensure).not.toHaveBeenCalled()
vi.advanceTimersByTime(1)
await checked()
expect(ensure).toHaveBeenCalledOnce()
expect(tree()).toEqual(before)
expect(gridBinaryPath({})).toBe(installed)
const next = buildArchive('0.3.49', key, 'grid')
stubFetch(manifestFor('grid', key, '0.3.49', next.bytes, next.root), next.bytes)
vi.advanceTimersByTime(GRID_PIN_RECHECK_MS)
await checked()
expect(gridBinaryPath({})).toBe(join(runtimeDir, `grid-0.3.49-${key}`, 'bin', 'grid'))
stop()
vi.advanceTimersByTime(GRID_PIN_RECHECK_MS * 3)
expect(ensure).toHaveBeenCalledTimes(2)
})
it('runs one check at a time: a slow one is not stacked on', async () => {
const { startGridPinRecheck, GRID_PIN_RECHECK_MS } = await load()
let release: () => void = () => {}
const ensure = vi.fn(() => new Promise<void>((resolve) => { release = resolve }))
const stop = startGridPinRecheck({ ensure })
vi.advanceTimersByTime(GRID_PIN_RECHECK_MS * 3)
expect(ensure).toHaveBeenCalledOnce()
release()
await new Promise((resolve) => setImmediate(resolve))
vi.advanceTimersByTime(GRID_PIN_RECHECK_MS)
expect(ensure).toHaveBeenCalledTimes(2)
stop()
})
})
describe('ensureLauncher', () => {
const NODE = '/opt/harness/runtime/node-v22/bin/node'
beforeEach(() => {
root = mkdtempSync(join(tmpdir(), 'harness-launcher-'))
runtimeDir = join(root, '.harness', 'runtime')
binDir = join(root, '.local', 'bin')
cliDir = join(root, '.harness', 'cli')
for (const dir of [runtimeDir, binDir, cliDir]) mkdirSync(dir, { recursive: true })
})
afterEach(() => {
rmSync(root, { recursive: true, force: true })
for (const key of ['ADAPTER_RUNTIME_DIR', 'HARNESS_BIN_DIR', 'ADAPTER_CLI_DIR', 'ADAPTER_RUNTIME_METADATA_URL']) {
delete process.env[key]
}
})
const launcherPath = () => join(binDir, 'harness')
const cliPath = () => join(cliDir, 'cli.js')
it('repairs the bare-node launcher install-cli.sh used to write', async () => {
writeFileSync(launcherPath(), `#!/bin/sh\nexec node "${cliPath()}" "$@"\n`, { mode: 0o755 })
const { ensureLauncher } = await load()
ensureLauncher(NODE)
expect(readFileSync(launcherPath(), 'utf8')).toBe(`#!/bin/sh\nexec '${NODE}' '${cliPath()}' "$@"\n`)
})
it('repairs an absolute system-Node launcher from the public installer', async () => {
writeFileSync(launcherPath(), `#!/bin/sh\nexec '/opt/homebrew/bin/node' '${cliPath()}' "$@"\n`, { mode: 0o755 })
const { ensureLauncher } = await load()
ensureLauncher(NODE)
expect(readFileSync(launcherPath(), 'utf8')).toContain(`exec '${NODE}'`)
expect(readFileSync(launcherPath(), 'utf8')).not.toContain('homebrew')
})
// The pin is the promise that no release reaches this computer on its own. Repairing the
// interpreter must not quietly revoke it.
it('fixes a dev-pinned launcher without disarming the pin', async () => {
const pinned = [
'#!/bin/sh',
'# Local dev install, PINNED with --no-updates (see scripts/install-cli.sh).',
'# Self-update is off: no release will ever reach this computer on its own, not even a newer one.',
'ADAPTER_UPDATE_DISABLE=true',
'export ADAPTER_UPDATE_DISABLE',
`exec node "${cliPath()}" "$@"`,
'',
].join('\n')
writeFileSync(launcherPath(), pinned, { mode: 0o755 })
const { ensureLauncher } = await load()
ensureLauncher(NODE)
const out = readFileSync(launcherPath(), 'utf8')
expect(out).toContain('ADAPTER_UPDATE_DISABLE=true')
expect(out).toContain('export ADAPTER_UPDATE_DISABLE')
expect(out).toContain('# Local dev install, PINNED with --no-updates (see scripts/install-cli.sh).')
expect(out).toContain(`exec '${NODE}' '${cliPath()}' "$@"`)
expect(out).not.toContain('exec node')
})
it('leaves a launcher that already points at the right Node untouched', async () => {
const correct = `#!/bin/sh\nexec '${NODE}' '${cliPath()}' "$@"\n`
writeFileSync(launcherPath(), correct, { mode: 0o755 })
const { ensureLauncher } = await load()
ensureLauncher(NODE)
expect(readFileSync(launcherPath(), 'utf8')).toBe(correct)
})
it('never touches a script it did not write', async () => {
const foreign = '#!/bin/sh\nexec /usr/local/bin/somebody-elses-tool "$@"\n'
writeFileSync(launcherPath(), foreign, { mode: 0o755 })
const { ensureLauncher } = await load()
ensureLauncher(NODE)
expect(readFileSync(launcherPath(), 'utf8')).toBe(foreign)
})
it('does not create a launcher where none exists', async () => {
const { ensureLauncher } = await load()
ensureLauncher(NODE)
expect(existsSync(launcherPath())).toBe(false)
})
})