agent-facets 0.2.1 → 0.3.0

package/.package.json.bak

@@ -5,13 +5,14 @@
     "url": "https://github.com/agent-facets/facets",
     "directory": "packages/cli"
   },
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
-    "facet": "./dist/facet"
+    "facet": "./bin/facet"
   },
   "scripts": {
     "build": "bun build src/index.ts --compile --outfile dist/facet",
+    "postinstall": "node scripts/postinstall.mjs",
     "prepack": "bun ../../scripts/prepack.ts",
     "postpack": "bun ../../scripts/postpack.ts",
     "types": "tsc --noEmit",

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # agent-facets
 
+## 0.3.0
+
+### Minor Changes
+
+- [#51](https://github.com/agent-facets/facets/pull/51) [`8280bba`](https://github.com/agent-facets/facets/commit/8280bba66d5ab6a132e1b6792bcccce03037a6de) Thanks [@eXamadeus](https://github.com/eXamadeus)! - Support 12 platform binaries (linux, windows, mac and common variants)
+
+### Patch Changes
+
+- [#51](https://github.com/agent-facets/facets/pull/51) [`8280bba`](https://github.com/agent-facets/facets/commit/8280bba66d5ab6a132e1b6792bcccce03037a6de) Thanks [@eXamadeus](https://github.com/eXamadeus)! - Support dev platform "dev" mode via `bun dev` removing the complex build -> link flow
+
+## 0.2.2
+
+### Patch Changes
+
+- [#39](https://github.com/agent-facets/facets/pull/39) [`f380b7b`](https://github.com/agent-facets/facets/commit/f380b7bc5115acec1f974ef1401eba199a2f90fb) Thanks [@eXamadeus](https://github.com/eXamadeus)! - Ensure release CI works in isolation
+- [#46](https://github.com/agent-facets/facets/pull/46) [`a5cbb89`](https://github.com/agent-facets/facets/commit/a5cbb89a46e14e2f79749ea7eafb5aebbd3504b7) Thanks [@eXamadeus](https://github.com/eXamadeus)! - Ensure all CI runs and provenance is managed correctly across packages
+
 ## 0.2.1
 
 ### Patch Changes

package/bin/facet

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+const childProcess = require("child_process")
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+function run(target) {
+  const result = childProcess.spawnSync(target, process.argv.slice(2), {
+    stdio: "inherit",
+  })
+  if (result.error) {
+    console.error(result.error.message)
+    process.exit(1)
+  }
+  const code = typeof result.status === "number" ? result.status : 0
+  process.exit(code)
+}
+
+// Resolution #1: Environment variable override
+const envPath = process.env.FACET_BIN_PATH
+if (envPath) {
+  run(envPath)
+}
+
+// Resolution #2: Cached hard-link from postinstall
+const scriptPath = fs.realpathSync(__filename)
+const scriptDir = path.dirname(scriptPath)
+
+const cached = path.join(scriptDir, ".facet")
+if (fs.existsSync(cached)) {
+  run(cached)
+}
+
+// Resolution #3: Platform package lookup
+const platformMap = {
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+}
+const archMap = {
+  x64: "x64",
+  arm64: "arm64",
+  arm: "arm",
+}
+
+let platform = platformMap[os.platform()]
+if (!platform) {
+  platform = os.platform()
+}
+let arch = archMap[os.arch()]
+if (!arch) {
+  arch = os.arch()
+}
+const base = "agent-facets-" + platform + "-" + arch
+const binary = platform === "windows" ? "facet.exe" : "facet"
+
+function supportsAvx2() {
+  if (arch !== "x64") return false
+
+  if (platform === "linux") {
+    try {
+      return /(^|\s)avx2(\s|$)/i.test(fs.readFileSync("/proc/cpuinfo", "utf8"))
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "darwin") {
+    try {
+      const result = childProcess.spawnSync("sysctl", ["-n", "hw.optional.avx2_0"], {
+        encoding: "utf8",
+        timeout: 1500,
+      })
+      if (result.status !== 0) return false
+      return (result.stdout || "").trim() === "1"
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === "windows") {
+    const cmd =
+      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
+
+    for (const exe of ["powershell.exe", "pwsh.exe", "pwsh", "powershell"]) {
+      try {
+        const result = childProcess.spawnSync(exe, ["-NoProfile", "-NonInteractive", "-Command", cmd], {
+          encoding: "utf8",
+          timeout: 3000,
+          windowsHide: true,
+        })
+        if (result.status !== 0) continue
+        const out = (result.stdout || "").trim().toLowerCase()
+        if (out === "true" || out === "1") return true
+        if (out === "false" || out === "0") return false
+      } catch {
+        continue
+      }
+    }
+
+    return false
+  }
+
+  return false
+}
+
+const names = (() => {
+  const avx2 = supportsAvx2()
+  const baseline = arch === "x64" && !avx2
+
+  if (platform === "linux") {
+    const musl = (() => {
+      try {
+        if (fs.existsSync("/etc/alpine-release")) return true
+      } catch {
+        // ignore
+      }
+
+      try {
+        const result = childProcess.spawnSync("ldd", ["--version"], { encoding: "utf8" })
+        const text = ((result.stdout || "") + (result.stderr || "")).toLowerCase()
+        if (text.includes("musl")) return true
+      } catch {
+        // ignore
+      }
+
+      return false
+    })()
+
+    if (musl) {
+      if (arch === "x64") {
+        if (baseline) return [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+        return [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+      }
+      return [`${base}-musl`, base]
+    }
+
+    if (arch === "x64") {
+      if (baseline) return [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+      return [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+    }
+    return [base, `${base}-musl`]
+  }
+
+  if (arch === "x64") {
+    if (baseline) return [`${base}-baseline`, base]
+    return [base, `${base}-baseline`]
+  }
+  return [base]
+})()
+
+function findBinary(startDir) {
+  let current = startDir
+  for (;;) {
+    const modules = path.join(current, "node_modules")
+    if (fs.existsSync(modules)) {
+      for (const name of names) {
+        const candidate = path.join(modules, name, "bin", binary)
+        if (fs.existsSync(candidate)) return candidate
+      }
+    }
+    const parent = path.dirname(current)
+    if (parent === current) {
+      return
+    }
+    current = parent
+  }
+}
+
+const resolved = findBinary(scriptDir)
+if (!resolved) {
+  console.error(
+    "It seems that your package manager failed to install the right version of the facet CLI for your platform. You can try manually installing " +
+      names.map((n) => `"${n}"`).join(" or ") +
+      " package",
+  )
+  process.exit(1)
+}
+
+run(resolved)

package/bin/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/package.json

@@ -5,13 +5,14 @@
     "url": "https://github.com/agent-facets/facets",
     "directory": "packages/cli"
   },
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
-    "facet": "./dist/facet"
+    "facet": "./bin/facet"
   },
   "scripts": {
     "build": "bun build src/index.ts --compile --outfile dist/facet",
+    "postinstall": "node scripts/postinstall.mjs",
     "prepack": "bun ../../scripts/prepack.ts",
     "postpack": "bun ../../scripts/postpack.ts",
     "types": "tsc --noEmit",
@@ -29,8 +30,8 @@
     "react-devtools-core": "7.0.1"
   },
   "devDependencies": {
-    "@agent-facets/brand": "0.2.0",
-    "@agent-facets/core": "0.2.0",
+    "@agent-facets/brand": "0.2.1",
+    "@agent-facets/core": "0.2.1",
     "@types/bun": "1.3.10",
     "ink-testing-library": "4.0.0"
   },

package/scripts/postinstall.mjs

@@ -0,0 +1,210 @@
+/**
+ * Postinstall script for agent-facets.
+ *
+ * Detects the current platform, architecture, AVX2 support, and musl libc,
+ * then hard-links the optimal binary to bin/.facet for fast launcher resolution.
+ *
+ * Silent failure — if anything goes wrong, the launcher's fallback logic handles it.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { chmodSync, copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, unlinkSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { arch as osArch, platform as osPlatform } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+
+// ---------------------------------------------------------------------------
+// Platform detection
+// ---------------------------------------------------------------------------
+
+function detectPlatform() {
+  const platformMap = { darwin: 'darwin', linux: 'linux', win32: 'windows' }
+  const archMap = { x64: 'x64', arm64: 'arm64', arm: 'arm' }
+  const platform = platformMap[osPlatform()] || osPlatform()
+  const arch = archMap[osArch()] || osArch()
+  return { platform, arch }
+}
+
+// ---------------------------------------------------------------------------
+// AVX2 detection
+// ---------------------------------------------------------------------------
+
+function supportsAvx2(platform) {
+  if (platform === 'linux') {
+    try {
+      return /(^|\s)avx2(\s|$)/i.test(readFileSync('/proc/cpuinfo', 'utf8'))
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === 'darwin') {
+    try {
+      const result = spawnSync('sysctl', ['-n', 'hw.optional.avx2_0'], {
+        encoding: 'utf8',
+        timeout: 1500,
+      })
+      if (result.status !== 0) return false
+      return (result.stdout || '').trim() === '1'
+    } catch {
+      return false
+    }
+  }
+
+  if (platform === 'windows') {
+    const cmd =
+      '(Add-Type -MemberDefinition "[DllImport(""kernel32.dll"")] public static extern bool IsProcessorFeaturePresent(int ProcessorFeature);" -Name Kernel32 -Namespace Win32 -PassThru)::IsProcessorFeaturePresent(40)'
+
+    for (const exe of ['powershell.exe', 'pwsh.exe', 'pwsh', 'powershell']) {
+      try {
+        const result = spawnSync(exe, ['-NoProfile', '-NonInteractive', '-Command', cmd], {
+          encoding: 'utf8',
+          timeout: 3000,
+          windowsHide: true,
+        })
+        if (result.status !== 0) continue
+        const out = (result.stdout || '').trim().toLowerCase()
+        if (out === 'true' || out === '1') return true
+        if (out === 'false' || out === '0') return false
+      } catch {}
+    }
+    return false
+  }
+
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// musl detection (Linux only)
+// ---------------------------------------------------------------------------
+
+function isMusl() {
+  try {
+    if (existsSync('/etc/alpine-release')) return true
+  } catch {
+    // ignore
+  }
+
+  try {
+    const result = spawnSync('ldd', ['--version'], { encoding: 'utf8' })
+    const text = ((result.stdout || '') + (result.stderr || '')).toLowerCase()
+    if (text.includes('musl')) return true
+  } catch {
+    // ignore
+  }
+
+  return false
+}
+
+// ---------------------------------------------------------------------------
+// Build priority-ordered candidate list
+// ---------------------------------------------------------------------------
+
+function buildCandidates(platform, arch, opts = {}) {
+  const base = `agent-facets-${platform}-${arch}`
+  const avx2 = opts.avx2 !== undefined ? opts.avx2 : arch === 'x64' ? supportsAvx2(platform) : false
+  const baseline = arch === 'x64' && !avx2
+
+  if (platform === 'linux') {
+    const musl = opts.musl !== undefined ? opts.musl : isMusl()
+
+    if (musl) {
+      if (arch === 'x64') {
+        if (baseline) return [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+        return [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+      }
+      return [`${base}-musl`, base]
+    }
+
+    if (arch === 'x64') {
+      if (baseline) return [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+      return [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+    }
+    return [base, `${base}-musl`]
+  }
+
+  if (arch === 'x64') {
+    if (baseline) return [`${base}-baseline`, base]
+    return [base, `${base}-baseline`]
+  }
+  return [base]
+}
+
+// ---------------------------------------------------------------------------
+// Find the binary via require.resolve
+// ---------------------------------------------------------------------------
+
+function findBinary(candidates) {
+  const binaryName = osPlatform() === 'win32' ? 'facet.exe' : 'facet'
+
+  for (const candidate of candidates) {
+    try {
+      const pkgPath = require.resolve(`${candidate}/package.json`)
+      const pkgDir = dirname(pkgPath)
+      const binaryPath = join(pkgDir, 'bin', binaryName)
+      if (existsSync(binaryPath)) return binaryPath
+    } catch {
+      // Package not installed — try next candidate
+    }
+  }
+
+  return undefined
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main() {
+  // Windows: no-op — the .exe is used directly
+  if (osPlatform() === 'win32') return
+
+  const { platform, arch } = detectPlatform()
+  const candidates = buildCandidates(platform, arch)
+  const binaryPath = findBinary(candidates)
+
+  if (!binaryPath) return // No binary found — launcher fallback handles it
+
+  const binDir = join(__dirname, '..', 'bin')
+  const targetPath = join(binDir, '.facet')
+
+  // Ensure bin directory exists
+  mkdirSync(binDir, { recursive: true })
+
+  // Remove existing cached binary
+  try {
+    unlinkSync(targetPath)
+  } catch {
+    // Doesn't exist — fine
+  }
+
+  // Hard-link (copy fallback on cross-device)
+  try {
+    linkSync(binaryPath, targetPath)
+  } catch {
+    copyFileSync(binaryPath, targetPath)
+  }
+
+  chmodSync(targetPath, 0o755)
+}
+
+// Guard: only run main() when executed directly, not when imported by tests
+const scriptPath = fileURLToPath(import.meta.url)
+const isDirectExecution = process.argv[1] && resolve(process.argv[1]) === scriptPath
+
+if (isDirectExecution) {
+  try {
+    main()
+  } catch (e) {
+    // Log the error but exit 0 — launcher fallback will handle binary resolution.
+    // We don't want a postinstall failure to break `npm install`.
+    console.error('[agent-facets postinstall] failed to cache platform binary:', e.message || e)
+  }
+}
+
+// Exports for testing — these are no-ops when run as a script
+export { buildCandidates, detectPlatform }

package/src/__tests__/launcher.test.ts

@@ -0,0 +1,106 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+const LAUNCHER_PATH = resolve(import.meta.dir, '..', '..', 'bin', 'facet')
+
+interface ExecResult {
+  stdout: string
+  stderr: string
+  exitCode: number
+}
+
+async function runLauncher(args: string[] = [], env: Record<string, string> = {}): Promise<ExecResult> {
+  const proc = Bun.spawn(['node', LAUNCHER_PATH, ...args], {
+    env: { ...process.env, ...env },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+
+  const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()])
+  const exitCode = await proc.exited
+
+  return { stdout, stderr, exitCode }
+}
+
+describe('launcher — FACET_BIN_PATH override', () => {
+  let tmpDir: string
+  let mockBinaryPath: string
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'launcher-test-'))
+    mockBinaryPath = join(tmpDir, 'mock-facet')
+    await writeFile(mockBinaryPath, '#!/bin/sh\necho "mock-facet: $@"\n')
+    await chmod(mockBinaryPath, 0o755)
+  })
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true })
+  })
+
+  test('runs the binary at FACET_BIN_PATH', async () => {
+    const result = await runLauncher(['--version'], { FACET_BIN_PATH: mockBinaryPath })
+    expect(result.stdout).toContain('mock-facet:')
+    expect(result.exitCode).toBe(0)
+  })
+
+  test('forwards arguments to the target binary', async () => {
+    const result = await runLauncher(['build', '--force', 'my-dir'], { FACET_BIN_PATH: mockBinaryPath })
+    expect(result.stdout).toContain('build --force my-dir')
+  })
+})
+
+describe('launcher — forwards exit code', () => {
+  let tmpDir: string
+  let exitingBinaryPath: string
+
+  beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'launcher-exit-'))
+    exitingBinaryPath = join(tmpDir, 'exit-42')
+    await writeFile(exitingBinaryPath, '#!/bin/sh\nexit 42\n')
+    await chmod(exitingBinaryPath, 0o755)
+  })
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true })
+  })
+
+  test('exits with the same code as the target binary', async () => {
+    const result = await runLauncher([], { FACET_BIN_PATH: exitingBinaryPath })
+    expect(result.exitCode).toBe(42)
+  })
+})
+
+describe('launcher — no binary found', () => {
+  let tmpDir: string
+  let isolatedLauncherPath: string
+
+  beforeAll(async () => {
+    // Create an isolated copy of the launcher in a directory with no node_modules
+    // and no .facet, so resolution falls through to the error path.
+    tmpDir = await mkdtemp(join(tmpdir(), 'launcher-nobin-'))
+    isolatedLauncherPath = join(tmpDir, 'facet')
+    await Bun.write(isolatedLauncherPath, await Bun.file(LAUNCHER_PATH).text())
+    await chmod(isolatedLauncherPath, 0o755)
+  })
+
+  afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true })
+  })
+
+  test('prints error with candidate package names and exits 1', async () => {
+    const proc = Bun.spawn(['node', isolatedLauncherPath], {
+      env: { ...process.env, FACET_BIN_PATH: undefined },
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+
+    const stderr = await new Response(proc.stderr).text()
+    const exitCode = await proc.exited
+
+    expect(exitCode).toBe(1)
+    expect(stderr).toContain('agent-facets-')
+    expect(stderr).toContain('package manager failed')
+  })
+})

package/src/__tests__/postinstall.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, test } from 'bun:test'
+import { resolve } from 'node:path'
+
+// Import the pure functions from the postinstall script
+const postinstallPath = resolve(import.meta.dir, '..', '..', 'scripts', 'postinstall.mjs')
+const { buildCandidates, detectPlatform } = await import(postinstallPath)
+
+describe('detectPlatform', () => {
+  test('returns an object with platform and arch strings', () => {
+    const result = detectPlatform()
+    expect(typeof result.platform).toBe('string')
+    expect(typeof result.arch).toBe('string')
+    expect(result.platform.length).toBeGreaterThan(0)
+    expect(result.arch.length).toBeGreaterThan(0)
+  })
+
+  test('maps darwin correctly', () => {
+    // We're running on macOS in this project
+    const result = detectPlatform()
+    if (process.platform === 'darwin') {
+      expect(result.platform).toBe('darwin')
+    }
+  })
+})
+
+describe('buildCandidates', () => {
+  // ---------------------------------------------------------------------------
+  // Linux glibc
+  // ---------------------------------------------------------------------------
+
+  test('linux x64 avx2 glibc', () => {
+    const result = buildCandidates('linux', 'x64', { avx2: true, musl: false })
+    expect(result).toEqual([
+      'agent-facets-linux-x64',
+      'agent-facets-linux-x64-baseline',
+      'agent-facets-linux-x64-musl',
+      'agent-facets-linux-x64-baseline-musl',
+    ])
+  })
+
+  test('linux x64 no-avx2 glibc', () => {
+    const result = buildCandidates('linux', 'x64', { avx2: false, musl: false })
+    expect(result).toEqual([
+      'agent-facets-linux-x64-baseline',
+      'agent-facets-linux-x64',
+      'agent-facets-linux-x64-baseline-musl',
+      'agent-facets-linux-x64-musl',
+    ])
+  })
+
+  test('linux arm64 glibc', () => {
+    const result = buildCandidates('linux', 'arm64', { avx2: false, musl: false })
+    expect(result).toEqual(['agent-facets-linux-arm64', 'agent-facets-linux-arm64-musl'])
+  })
+
+  // ---------------------------------------------------------------------------
+  // Linux musl
+  // ---------------------------------------------------------------------------
+
+  test('linux x64 avx2 musl', () => {
+    const result = buildCandidates('linux', 'x64', { avx2: true, musl: true })
+    expect(result).toEqual([
+      'agent-facets-linux-x64-musl',
+      'agent-facets-linux-x64-baseline-musl',
+      'agent-facets-linux-x64',
+      'agent-facets-linux-x64-baseline',
+    ])
+  })
+
+  test('linux x64 no-avx2 musl', () => {
+    const result = buildCandidates('linux', 'x64', { avx2: false, musl: true })
+    expect(result).toEqual([
+      'agent-facets-linux-x64-baseline-musl',
+      'agent-facets-linux-x64-musl',
+      'agent-facets-linux-x64-baseline',
+      'agent-facets-linux-x64',
+    ])
+  })
+
+  test('linux arm64 musl', () => {
+    const result = buildCandidates('linux', 'arm64', { avx2: false, musl: true })
+    expect(result).toEqual(['agent-facets-linux-arm64-musl', 'agent-facets-linux-arm64'])
+  })
+
+  // ---------------------------------------------------------------------------
+  // Non-Linux
+  // ---------------------------------------------------------------------------
+
+  test('darwin arm64', () => {
+    const result = buildCandidates('darwin', 'arm64', { avx2: false })
+    expect(result).toEqual(['agent-facets-darwin-arm64'])
+  })
+
+  test('darwin x64 avx2', () => {
+    const result = buildCandidates('darwin', 'x64', { avx2: true })
+    expect(result).toEqual(['agent-facets-darwin-x64', 'agent-facets-darwin-x64-baseline'])
+  })
+
+  test('darwin x64 no-avx2', () => {
+    const result = buildCandidates('darwin', 'x64', { avx2: false })
+    expect(result).toEqual(['agent-facets-darwin-x64-baseline', 'agent-facets-darwin-x64'])
+  })
+
+  test('windows x64 avx2', () => {
+    const result = buildCandidates('windows', 'x64', { avx2: true })
+    expect(result).toEqual(['agent-facets-windows-x64', 'agent-facets-windows-x64-baseline'])
+  })
+
+  test('windows arm64', () => {
+    const result = buildCandidates('windows', 'arm64', { avx2: false })
+    expect(result).toEqual(['agent-facets-windows-arm64'])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Consistency: launcher and postinstall must produce identical candidate lists
+// ---------------------------------------------------------------------------
+
+describe('consistency — launcher and postinstall candidate lists match', () => {
+  /**
+   * Reimplements the launcher's candidate-building logic as a pure function.
+   * This is intentionally a direct translation of the CommonJS code in bin/facet
+   * so the test catches any drift between the two implementations.
+   */
+  function launcherCandidates(platform: string, arch: string, opts: { avx2: boolean; musl?: boolean }): string[] {
+    const base = `agent-facets-${platform}-${arch}`
+    const baseline = arch === 'x64' && !opts.avx2
+
+    if (platform === 'linux') {
+      const musl = !!opts.musl
+
+      if (musl) {
+        if (arch === 'x64') {
+          if (baseline) return [`${base}-baseline-musl`, `${base}-musl`, `${base}-baseline`, base]
+          return [`${base}-musl`, `${base}-baseline-musl`, base, `${base}-baseline`]
+        }
+        return [`${base}-musl`, base]
+      }
+
+      if (arch === 'x64') {
+        if (baseline) return [`${base}-baseline`, base, `${base}-baseline-musl`, `${base}-musl`]
+        return [base, `${base}-baseline`, `${base}-musl`, `${base}-baseline-musl`]
+      }
+      return [base, `${base}-musl`]
+    }
+
+    if (arch === 'x64') {
+      if (baseline) return [`${base}-baseline`, base]
+      return [base, `${base}-baseline`]
+    }
+    return [base]
+  }
+
+  const cases: Array<{ platform: string; arch: string; avx2: boolean; musl?: boolean }> = [
+    // Linux glibc
+    { platform: 'linux', arch: 'x64', avx2: true, musl: false },
+    { platform: 'linux', arch: 'x64', avx2: false, musl: false },
+    { platform: 'linux', arch: 'arm64', avx2: false, musl: false },
+    // Linux musl
+    { platform: 'linux', arch: 'x64', avx2: true, musl: true },
+    { platform: 'linux', arch: 'x64', avx2: false, musl: true },
+    { platform: 'linux', arch: 'arm64', avx2: false, musl: true },
+    // Darwin
+    { platform: 'darwin', arch: 'arm64', avx2: false },
+    { platform: 'darwin', arch: 'x64', avx2: true },
+    { platform: 'darwin', arch: 'x64', avx2: false },
+    // Windows
+    { platform: 'windows', arch: 'arm64', avx2: false },
+    { platform: 'windows', arch: 'x64', avx2: true },
+    { platform: 'windows', arch: 'x64', avx2: false },
+  ]
+
+  for (const c of cases) {
+    const label = `${c.platform}/${c.arch} avx2=${c.avx2}${c.musl !== undefined ? ` musl=${c.musl}` : ''}`
+    test(label, () => {
+      const fromPostinstall = buildCandidates(c.platform, c.arch, { avx2: c.avx2, musl: c.musl })
+      const fromLauncher = launcherCandidates(c.platform, c.arch, { avx2: c.avx2, musl: c.musl })
+      expect(fromPostinstall).toEqual(fromLauncher)
+    })
+  }
+})
+
+// ---------------------------------------------------------------------------
+// Silent failure
+// ---------------------------------------------------------------------------
+
+describe('postinstall — silent failure', () => {
+  test('exits 0 when no platform packages are installed', async () => {
+    const proc = Bun.spawn(['node', resolve(import.meta.dir, '..', '..', 'scripts', 'postinstall.mjs')], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const exitCode = await proc.exited
+    expect(exitCode).toBe(0)
+  })
+})