@reddb-io/sdk 1.23.4 → 1.24.0

package/README.md

@@ -1,7 +1,8 @@
 # @reddb-io/sdk
 
 Official RedDB SDK for JavaScript and TypeScript. Speaks JSON-RPC 2.0 over
-stdio to a local `red` binary, which is downloaded automatically on install.
+stdio to a local `red` binary, which npm installs for your platform automatically
+(no install script, no download).
 Works in **Node 18+**, **Bun** and **Deno** (via `npm:` specifier) — same
 package, no per-runtime fork.
 
@@ -30,24 +31,34 @@ In Deno:
 import { connect } from 'npm:@reddb-io/sdk'
 ```
 
-The `postinstall` script downloads the matching `red` binary from GitHub
-Releases into `node_modules/@reddb-io/sdk/bin/`. If the download fails (no
-network, 404, unsupported platform) the install now **fails loud** with an
-actionable multi-line message — it no longer silently ships an empty `bin/`
-that explodes the first time you call `connect()`. See the next section
-for the supported offline paths.
+The `red` binary ships as a per-platform package
+(`@reddb-io/red-linux-x64`, `-linux-x64-musl`, `-linux-arm64`,
+`-linux-arm64-musl`, `-linux-arm`, `-darwin-x64`, `-darwin-arm64`,
+`-win32-x64`) listed as an `optionalDependency` of this package. Your package
+manager installs only the one matching your OS, CPU and libc, so there is **no
+install script and no download**: it works with `--ignore-scripts`, behind a
+registry mirror, and offline once the packages are cached. Don't install with
+`--omit=optional` / `--no-optional`, or the binary is skipped.
 
-## Offline / restricted-network installs
+### In-process engine
 
-If your CI or workstation has no network during `npm install`, or your
-environment blocks postinstall scripts entirely, opt out explicitly and
-point the driver at a binary you provide yourself:
+On platforms whose package includes `reddb.node`, `connect('memory://')` and
+`connect('file://...')` run the engine **inside your process** — no subprocess,
+same API and transaction semantics. Elsewhere (and when you pass
+`options.binary`) the SDK spawns `red rpc --stdio` as before. Set
+`REDDB_NATIVE_ADDON=/path/to/reddb.node` to point at a specific addon.
 
-```bash
-# 1. Install the SDK without trying to download the engine.
-REDDB_SKIP_POSTINSTALL=1 npm install @reddb-io/sdk
+Because the engine shares your process, an engine panic aborts the process (the
+engine's crash-safety model relies on WAL recovery, not unwinding). A file-backed
+database allows one writer: a second `connect('file://...')` on the same file
+fails until the first is closed.
+
+## Using your own binary
 
-# 2. At runtime, tell connect() where the red binary lives.
+To use a `red` you provide (a custom build, an unsupported platform), point
+the driver at it:
+
+```bash
 export REDDB_BIN=/path/to/red          # canonical, per ADR 0006
 # (REDDB_BINARY_PATH is a deprecated alias kept for the rollout window.)
 ```
@@ -64,15 +75,11 @@ Three ways to get a `red` binary:
   cargo build --release --bin red
   export REDDB_BIN="$PWD/target/release/red"
   ```
-- Download a prebuilt asset from the releases page and drop it at
-  `<package>/bin/red[.exe]`:
+- Download a prebuilt asset from the releases page:
   <https://github.com/reddb-io/reddb/releases>
 
-When `REDDB_SKIP_POSTINSTALL=1` is set the postinstall script prints a one-line
-notice and exits 0; without it, any download failure exits non-zero so the
-install surfaces the problem immediately. If you forget to provide the
-binary, `connect()` raises a clear `binary "red" not found` error that names
-`REDDB_BIN` as the override.
+If no binary can be found, `connect()` raises a clear `binary "red" not found`
+error that names the expected package and `REDDB_BIN` as the override.
 
 ## Quickstart
 

package/index.d.ts

@@ -167,15 +167,18 @@ export class RedDBError extends Error {
 
 /** Options for cache.put(). Maps to Rust BlobCachePolicy fields. */
 export interface CachePutOptions {
-  /** Entry TTL in milliseconds. Omit to use the namespace default. */
+  /** Hard TTL in milliseconds. Omit for no time-based expiry. */
   ttl_ms?: number
   /** Tags for group invalidation via cache.invalidateTags(). */
   tags?: string[]
-  /** Extended TTL policy (idle eviction, stale-while-revalidate, jitter). */
+  /** Native hard-expiry and admission policy for remote HTTP cache entries. */
   policy?: {
-    idle_evict_ms?: number
-    stale_while_revalidate_ms?: number
-    jitter_ms?: number
+    ttl_ms?: number
+    expires_at_unix_ms?: number
+    max_blob_bytes?: number
+    l1_admission?: 'auto' | 'always' | 'never'
+    priority?: number
+    version?: number
   }
 }
 
@@ -215,7 +218,7 @@ export class CacheClient {
   invalidatePrefix(namespace: string, prefix: string): Promise<number>
   /** Remove all entries tagged with any of the given tags. Returns count removed. */
   invalidateTags(namespace: string, tags: string[]): Promise<number>
-  /** Remove all entries in a namespace (routes to POST /admin/blob_cache/flush_namespace). */
+  /** Remove entries through the caller-scoped POST /cache/ns/:namespace/flush endpoint. */
   flushNamespace(namespace: string): Promise<void>
 }
 
@@ -360,6 +363,7 @@ export class VaultClient {
     options?: { collection?: string; tags?: string[] },
   ): Promise<QueryResult>
   get(key: string, options?: { collection?: string }): Promise<QueryResult>
+  reveal(key: string, options?: { collection?: string }): Promise<QueryResult>
   unseal(key: string, options?: { collection?: string }): Promise<QueryResult>
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reddb-io/sdk",
-  "version": "1.23.4",
-  "description": "Official embedded RedDB SDK — launches a local red binary over stdio JSON-RPC. Use @reddb-io/client for remote HTTP, gRPC, and RedWire.",
+  "version": "1.24.0",
+  "description": "Official embedded RedDB SDK — launches a local red binary over stdio JSON-RPC. The binary arrives as a per-platform optionalDependency — no install script. Use @reddb-io/client for remote HTTP, gRPC, and RedWire.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -14,7 +14,6 @@
   "files": [
     "src/",
     "index.d.ts",
-    "postinstall.js",
     "README.md",
     "LICENSE"
   ],
@@ -43,8 +42,17 @@
   "bugs": {
     "url": "https://github.com/reddb-io/reddb/issues"
   },
+  "optionalDependencies": {
+    "@reddb-io/red-linux-x64": "1.24.0",
+    "@reddb-io/red-linux-x64-musl": "1.24.0",
+    "@reddb-io/red-linux-arm64": "1.24.0",
+    "@reddb-io/red-linux-arm64-musl": "1.24.0",
+    "@reddb-io/red-linux-arm": "1.24.0",
+    "@reddb-io/red-darwin-x64": "1.24.0",
+    "@reddb-io/red-darwin-arm64": "1.24.0",
+    "@reddb-io/red-win32-x64": "1.24.0"
+  },
   "scripts": {
-    "postinstall": "node postinstall.js",
-    "test": "node --test test/ask.test.mjs test/cache.test.mjs test/db-helpers.test.mjs test/embedded-only.test.mjs test/helpers.test.mjs test/insert-ids.test.mjs test/kv.test.mjs test/params.test.mjs test/postinstall.test.mjs test/queue.test.mjs test/redwire.params.test.mjs test/transaction.test.mjs test/url.test.mjs && node test/smoke.test.mjs && node test/conformance.test.mjs && node test/readme-examples.test.mjs"
+    "test": "node --test test/ask.test.mjs test/cache.test.mjs test/db-helpers.test.mjs test/embedded-only.test.mjs test/helpers.test.mjs test/insert-ids.test.mjs test/kv.test.mjs test/params.test.mjs test/platform-binary.test.mjs test/native-engine.test.mjs test/queue.test.mjs test/redwire.params.test.mjs test/transaction.test.mjs test/url.test.mjs && node test/smoke.test.mjs && node test/conformance.test.mjs && node test/readme-examples.test.mjs"
   }
 }

package/src/binary.js

@@ -4,7 +4,8 @@
  * SDK lookup (`resolveSdkBinary`):
  *   1. `REDDB_BIN` env var (the canonical override per ADR 0006).
  *   2. `REDDB_BINARY_PATH` env var (legacy alias, deprecation window).
- *   3. `<package>/bin/red[.exe]` — where postinstall.js dropped it.
+ *   3. The `@reddb-io/red-<platform>` package npm installed for this host
+ *      (see `platform-binary.js`).
  *   4. Otherwise throw an actionable error.
  *
  *   PATH is **never** consulted. The wire-format coupling between the
@@ -13,19 +14,12 @@
  *
  * CLI lookup (`resolveCliBinary`):
  *   1. `REDDB_BIN` env var.
- *   2. `<package>/bin/red[.exe]`.
+ *   2. The `@reddb-io/red-<platform>` package.
  *   3. PATH-resolved bare `red[.exe]` — appropriate for the CLI which
  *      *targets* PATH.
  */
 
-import { existsSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { dirname, resolve, join } from 'node:path'
-
-import { resolveBin } from './internal/bin-resolver/index.js'
-
-const HERE = dirname(fileURLToPath(import.meta.url))
-const PACKAGE_ROOT = resolve(HERE, '..')
+import { platformPackageNames, resolvePlatformBinary } from './platform-binary.js'
 
 function defaultBinaryName() {
   if (typeof process !== 'undefined' && process.platform === 'win32') {
@@ -36,15 +30,27 @@ function defaultBinaryName() {
 
 /** SDK runtime lookup. Throws actionable error when binary cannot be located. */
 export function resolveSdkBinary() {
+  const override = process.env?.REDDB_BIN
+  if (typeof override === 'string' && override !== '') {
+    return override
+  }
   const legacy = process.env?.REDDB_BINARY_PATH
-  if (typeof legacy === 'string' && legacy !== '' && !process.env?.REDDB_BIN) {
+  if (typeof legacy === 'string' && legacy !== '') {
     return legacy
   }
-  return resolveBin({
-    name: defaultBinaryName(),
-    packageRoot: PACKAGE_ROOT,
-    envVar: 'REDDB_BIN',
-  })
+  const packaged = resolvePlatformBinary()
+  if (packaged) {
+    return packaged
+  }
+  const wanted = platformPackageNames()[0]
+  throw new Error(
+    `reddb: binary "${defaultBinaryName()}" not found.\n` +
+      `  expected:    the ${wanted} package (an optionalDependency of @reddb-io/sdk)\n` +
+      `  override:    set REDDB_BIN=/path/to/${defaultBinaryName()}\n` +
+      `  fix:         reinstall without --no-optional / --omit=optional, and make sure\n` +
+      `               ${process.platform}/${process.arch} is a supported platform;\n` +
+      `               or build it: cargo build --release --bin red`,
+  )
 }
 
 /** CLI runtime lookup. Allowed to fall back to PATH per ADR 0006. */
@@ -53,14 +59,5 @@ export function resolveCliBinary() {
   if (typeof override === 'string' && override !== '') {
     return override
   }
-  const local = join(PACKAGE_ROOT, 'bin', defaultBinaryName())
-  if (existsSync(local)) {
-    return local
-  }
-  return defaultBinaryName()
-}
-
-/** Used by postinstall.js to know where to drop the downloaded binary. */
-export function packageBinaryDir() {
-  return join(PACKAGE_ROOT, 'bin')
+  return resolvePlatformBinary() ?? defaultBinaryName()
 }

package/src/cache.js

@@ -2,13 +2,9 @@
  * Cache client — exposes cache.{get,put,exists,invalidate,invalidatePrefix,
  * invalidateTags,flushNamespace} via the underlying HTTP transport.
  *
- * NOTE: These methods require server-side HTTP endpoints under /cache/ns/*.
- * flushNamespace routes to the existing POST /admin/blob_cache/flush_namespace.
- * All others target endpoints planned for a future server release.
- *
- * Requires an HTTP or gRPC transport. On embedded (stdio JSON-RPC), every
- * method throws `UNSUPPORTED_TRANSPORT` before issuing the RPC call —
- * the engine's stdio handler doesn't implement `cache.*`.
+ * The HTTP data-plane endpoints under /cache/ns/* authorize the caller's
+ * tenant and cache namespace. Invalidation is local to the addressed server.
+ * Use the HTTP transport for remote cache operations.
  *
  * Values are base64-encoded in transit so binary payloads survive JSON.
  */
@@ -123,7 +119,7 @@ export class CacheClient {
 
   /**
    * Remove all entries in a namespace.
-   * Routes to POST /admin/blob_cache/flush_namespace (live endpoint).
+   * Uses the caller-scoped POST /cache/ns/:namespace/flush endpoint.
    * @param {string} namespace
    * @returns {Promise<void>}
    */

package/src/http.js

@@ -27,8 +27,8 @@
  *   cache.exists            → GET    /cache/ns/:ns/:key/exists
  *   cache.invalidate        → DELETE /cache/ns/:ns/:key
  *   cache.invalidate_prefix → DELETE /cache/ns/:ns?prefix=...
- *   cache.invalidate_tags   → DELETE /cache/ns/:ns/tags  (body: {tags})
- *   cache.flush_namespace   → POST   /admin/blob_cache/flush_namespace
+ *   cache.invalidate_tags   → POST   /cache/ns/:ns/invalidate-tags (body: {tags})
+ *   cache.flush_namespace   → POST   /cache/ns/:ns/flush
  *
  * Auth: every request after construction carries `Authorization:
  * Bearer <token>` (when set). `setToken(token)` updates it in
@@ -195,11 +195,11 @@ const ROUTES = {
     init: { method: 'DELETE' },
   }),
   'cache.invalidate_tags': (base, { namespace, tags }) => ({
-    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/tags`,
-    init: { method: 'DELETE', body: JSON.stringify({ tags }) },
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/invalidate-tags`,
+    init: { method: 'POST', body: JSON.stringify({ tags }) },
   }),
   'cache.flush_namespace': (base, { namespace }) => ({
-    url: `${base}/admin/blob_cache/flush_namespace`,
-    init: { method: 'POST', body: JSON.stringify({ namespace }) },
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/flush`,
+    init: { method: 'POST' },
   }),
 }

package/src/index.js

@@ -19,6 +19,7 @@
  */
 
 import { spawnRed } from './spawn.js'
+import { NativeRpcClient, openNativeEngine, resolveNativeAddon } from './native-engine.js'
 import { resolveSdkBinary } from './binary.js'
 import { RpcClient, RedDBError } from './protocol.js'
 import { parseUri } from './url.js'
@@ -83,6 +84,15 @@ export async function connect(uri, options = {}) {
         'auth is only meaningful for remote connections; embedded modes inherit caller privileges.',
       )
     }
+    // In-process addon when one is installed for this host (and the caller
+    // did not ask for a specific binary); otherwise the `red rpc --stdio`
+    // subprocess. Both serve the same JSON-RPC protocol.
+    const addon = options.binary ? null : resolveNativeAddon()
+    if (addon) {
+      const client = new NativeRpcClient(openNativeEngine(parsed.path || undefined, addon))
+      await client.call('version', {})
+      return new RedDB(client, { transport: 'embedded' })
+    }
     const args = embeddedArgs(parsed)
     const binary = options.binary ?? resolveSdkBinary()
     const child = await spawnRed(binary, args)

package/src/native-engine.js

@@ -0,0 +1,120 @@
+/**
+ * In-process embedded engine (the `reddb.node` Node addon).
+ *
+ * Embedded mode used to spawn `red rpc --stdio` and speak JSON-RPC over the
+ * child's pipes. The addon serves the same protocol — same methods, same
+ * transaction/cursor semantics — as a function call, so there is no
+ * subprocess and no separate `red` binary involved.
+ *
+ * The addon ships inside the `@reddb-io/red-<platform>` package next to
+ * `bin/red` (see `platform-binary.js` for how that package is found).
+ * `REDDB_NATIVE_ADDON=/path/to/reddb.node` overrides the lookup.
+ */
+
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+import { RedDBError } from './protocol.js'
+import { platformPackageNames } from './platform-binary.js'
+
+const require = createRequire(import.meta.url)
+
+/**
+ * @returns {string | null} path to `reddb.node`, or null when no addon is
+ *   installed for this host.
+ */
+export function resolveNativeAddon({
+  resolve = (id) => require.resolve(id),
+  env = process.env,
+  names = platformPackageNames(),
+} = {}) {
+  const override = env.REDDB_NATIVE_ADDON
+  if (typeof override === 'string' && override !== '') return override
+  for (const name of names) {
+    let manifest
+    try {
+      manifest = resolve(`${name}/package.json`)
+    } catch {
+      continue
+    }
+    const addon = join(dirname(manifest), 'reddb.node')
+    if (existsSync(addon)) return addon
+  }
+  return null
+}
+
+/**
+ * Open an embedded engine through the addon.
+ * @param {string | undefined} path database file, or undefined for in-memory
+ * @param {string} addonPath
+ */
+export function openNativeEngine(path, addonPath) {
+  const { Engine } = require(addonPath)
+  return Engine.open(path)
+}
+
+/**
+ * JSON-RPC client over an in-process engine. Same surface as `RpcClient`
+ * (`call`, `close`), so `RedDB` cannot tell the transports apart.
+ *
+ * Requests are chained so they reach the engine in call order even when the
+ * caller does not await each one: the engine's thread pool would otherwise
+ * be free to reorder them, which a transaction (`tx.begin`, then writes)
+ * must never see. The stdio pipe gave this ordering for free.
+ */
+export class NativeRpcClient {
+  /** @param {{ call(request: string): Promise<string>, close(): void }} engine */
+  constructor(engine) {
+    this.engine = engine
+    this.nextId = 1
+    this.closed = false
+    this.closeReason = null
+    this.tail = Promise.resolve()
+  }
+
+  call(method, params = {}) {
+    if (this.closed) {
+      return Promise.reject(
+        new RedDBError('CLIENT_CLOSED', `client is closed: ${this.closeReason ?? 'unknown'}`),
+      )
+    }
+    const id = this.nextId++
+    const request = JSON.stringify({ jsonrpc: '2.0', id, method, params })
+    const run = this.tail.then(() => this.engine.call(request))
+    this.tail = run.then(
+      () => undefined,
+      () => undefined,
+    )
+    return run.then((line) => {
+      const envelope = JSON.parse(line)
+      if (method === 'close') this.#shutdown('close requested')
+      if (envelope.error) {
+        throw new RedDBError(
+          envelope.error.code ?? 'UNKNOWN',
+          envelope.error.message ?? 'unknown error',
+          envelope.error.data,
+        )
+      }
+      return envelope.result
+    })
+  }
+
+  /** Send `close` (discarding any open transaction), then release the file lock. */
+  async close() {
+    if (this.closed) return
+    try {
+      await this.call('close', {})
+    } catch {
+      // best effort — the engine may already be shut down
+    }
+    this.#shutdown('close requested')
+    this.engine.close()
+  }
+
+  #shutdown(reason) {
+    if (this.closed) return
+    this.closed = true
+    this.closeReason = reason
+  }
+}

package/src/platform-binary.js

@@ -0,0 +1,62 @@
+/**
+ * Locate the `red` binary shipped as a per-platform npm package.
+ *
+ * `@reddb-io/cli` and `@reddb-io/sdk` declare every `@reddb-io/red-<key>`
+ * package as an `optionalDependency`; the package manager installs only the
+ * one matching the host's `os` / `cpu` / `libc`, so there is no install
+ * script and no download. `<key>` is `<process.platform>-<process.arch>`,
+ * plus `-musl` for the static Linux builds. `scripts/npm-platform-packages.mjs`
+ * owns the publish side; a contract test keeps the two key tables identical.
+ */
+
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+/** `glibc` | `musl` on Linux, `null` elsewhere. */
+export function detectLibc(platform = process.platform) {
+  if (platform !== 'linux') return null
+  const header = process.report?.getReport?.()?.header
+  return header?.glibcVersionRuntime ? 'glibc' : 'musl'
+}
+
+/**
+ * Package names to try, best match first. On Linux the other libc variant is
+ * a fallback: package managers that ignore `libc` install both, and the
+ * static (musl) binary runs on glibc hosts too.
+ */
+export function platformPackageNames({
+  platform = process.platform,
+  arch = process.arch,
+  libc = detectLibc(platform),
+} = {}) {
+  const base = `@reddb-io/red-${platform}-${arch}`
+  if (platform !== 'linux') return [base]
+  return libc === 'musl' ? [`${base}-musl`, base] : [base, `${base}-musl`]
+}
+
+/**
+ * @returns {string | null} absolute path to the binary, or null when no
+ *   platform package for this host is installed.
+ */
+export function resolvePlatformBinary({
+  platform = process.platform,
+  arch = process.arch,
+  libc = detectLibc(platform),
+  resolve = (id) => require.resolve(id),
+} = {}) {
+  const binName = platform === 'win32' ? 'red.exe' : 'red'
+  for (const name of platformPackageNames({ platform, arch, libc })) {
+    let manifest
+    try {
+      manifest = resolve(`${name}/package.json`)
+    } catch {
+      continue
+    }
+    const binary = join(dirname(manifest), 'bin', binName)
+    if (existsSync(binary)) return binary
+  }
+  return null
+}

package/src/vault.js

@@ -23,9 +23,13 @@ export class VaultClient {
   }
 
   unseal(key, options = {}) {
+    return this.reveal(key, options)
+  }
+
+  reveal(key, options = {}) {
     const collection = options.collection ?? this.collection
     return this.client.call('query', {
-      sql: `UNSEAL VAULT ${keyedIdentifier(collection)}.${keyedIdentifier(key)}`,
+      sql: `VAULT REVEAL ${keyedIdentifier(collection)}.${keyedIdentifier(key)}`,
     })
   }
 }

package/postinstall.js

@@ -1,146 +0,0 @@
-/**
- * postinstall.js — download the matching `red` binary from GitHub Releases.
- *
- * Behavior:
- *   - Resolves `red-<platform>-<arch>` from `process.platform` + `process.arch`
- *     via the vendored asset fetcher.
- *   - Targets the GitHub release matching this package's version.
- *   - Drops the binary at `<package>/bin/red[.exe]` and chmods +x on Unix.
- *   - Intentional skip paths (workspace checkout, REDDB_SKIP_POSTINSTALL=1)
- *     exit 0 quietly. Any unintentional failure (no network, 404, asset
- *     fetcher error, unsupported platform) prints an actionable multi-line
- *     message to stderr and exits 1 so `npm install` fails loud — never
- *     ships a package with an empty bin/ that explodes later at connect().
- *
- * Override hooks (env vars):
- *   REDDB_SKIP_POSTINSTALL=1      do nothing, exit 0 (caller will provide
- *                                 the binary via REDDB_BIN or a vendored
- *                                 copy at bin/red[.exe])
- *   REDDB_POSTINSTALL_VERSION=…   pull a different release tag
- *   REDDB_POSTINSTALL_REPO=…      pull from a fork (default: reddb-io/reddb)
- */
-
-import { createRequire } from 'node:module'
-import { fileURLToPath } from 'node:url'
-import { dirname, join, sep } from 'node:path'
-import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs'
-
-import { fetchReleaseAsset } from './src/internal/asset-fetcher/index.js'
-
-const HERE = dirname(fileURLToPath(import.meta.url))
-const require = createRequire(import.meta.url)
-const pkg = require('./package.json')
-
-const DEFAULT_REPO = 'reddb-io/reddb'
-
-if (process.env.REDDB_SKIP_POSTINSTALL === '1') {
-  process.stdout.write('reddb: postinstall skipped (REDDB_SKIP_POSTINSTALL=1)\n')
-  process.exit(0)
-}
-
-// Workspace-local install detection. When this file's resolved path is not
-// inside a `node_modules` tree we're running from a fresh checkout of the
-// reddb monorepo (or a fork), where `package.json` may already carry a
-// version whose GitHub Release has not been built yet — and where the
-// developer typically builds `red` with `cargo build` anyway. Skip the
-// download with a clear pointer; release flows still work because the npm
-// tarball, when installed, lives under `node_modules/`.
-if (!HERE.includes(`${sep}node_modules${sep}`)) {
-  process.stdout.write(
-    'reddb: skipping postinstall — running from a workspace checkout (no node_modules/).\n' +
-    '       If you need the binary, either:\n' +
-    '         - cargo build --release --bin red  &&  export REDDB_BIN="$PWD/target/release/red"\n' +
-    '         - or:  curl -fsSL https://raw.githubusercontent.com/reddb-io/reddb/main/install.sh | bash\n' +
-    '       Set REDDB_SKIP_POSTINSTALL=1 to silence this message.\n',
-  )
-  process.exit(0)
-}
-
-main().catch((err) => {
-  process.stderr.write(formatFailure(err))
-  process.exit(1)
-})
-
-function formatFailure(err) {
-  const repo = process.env.REDDB_POSTINSTALL_REPO || DEFAULT_REPO
-  const escapeHatches =
-    `       Escape hatches (any one of these will unblock the install):\n` +
-    `         - Skip the download and provide the binary yourself:\n` +
-    `             REDDB_SKIP_POSTINSTALL=1 npm install\n` +
-    `             then at runtime:  export REDDB_BIN=/path/to/red\n` +
-    `         - Or install red via the official installer and point at it:\n` +
-    `             curl -fsSL https://raw.githubusercontent.com/${repo}/main/install.sh | bash\n` +
-    `             export REDDB_BIN="$(command -v red)"\n` +
-    `         - Or build from a workspace checkout of ${repo}:\n` +
-    `             cargo build --release --bin red\n` +
-    `             export REDDB_BIN="$PWD/target/release/red"\n` +
-    `         - Or download the binary manually from\n` +
-    `             https://github.com/${repo}/releases\n` +
-    `           and place it at <package>/bin/red[.exe]\n`
-
-  if (err && err.code === 'UNSUPPORTED_PLATFORM') {
-    return (
-      `reddb: no prebuilt red binary for ${process.platform}/${process.arch}.\n` +
-      `       Building from source is required for this platform:\n` +
-      `         https://github.com/${repo}#build-from-source\n` +
-      escapeHatches
-    )
-  }
-  if (err && err.code === 'ASSET_NOT_FOUND') {
-    return (
-      `reddb: release asset not found at ${err.url}\n` +
-      `       Common cause: the GitHub Release for this SDK version has not\n` +
-      `       been published yet (or your platform's binary was not produced\n` +
-      `       for that release). You can also pull a specific tag explicitly:\n` +
-      `         REDDB_POSTINSTALL_VERSION=v1.0.5 npm rebuild @reddb-io/sdk\n` +
-      escapeHatches
-    )
-  }
-  return (
-    `reddb: postinstall could not download the red binary (${(err && err.message) || err}).\n` +
-    `       Install failed — the SDK will not work without a binary at\n` +
-    `       <package>/bin/red[.exe] or pointed at by REDDB_BIN.\n` +
-    escapeHatches
-  )
-}
-
-async function main() {
-  const repo = process.env.REDDB_POSTINSTALL_REPO || DEFAULT_REPO
-  const tag = process.env.REDDB_POSTINSTALL_VERSION
-    ? normalizeTag(process.env.REDDB_POSTINSTALL_VERSION)
-    : `v${pkg.version}`
-
-  const binDir = join(HERE, 'bin')
-  const binaryPath = join(binDir, defaultBinaryName())
-
-  if (existsSync(binaryPath)) {
-    process.stdout.write(`reddb: binary already present at ${binaryPath}\n`)
-    return
-  }
-
-  process.stdout.write(
-    `reddb: downloading red ${tag} for ${process.platform}/${process.arch} from ${repo}\n`,
-  )
-  const body = await fetchReleaseAsset({
-    repo,
-    tag,
-    platform: process.platform,
-    arch: process.arch,
-    binName: 'red',
-  })
-  mkdirSync(binDir, { recursive: true })
-  writeFileSync(binaryPath, body)
-  if (process.platform !== 'win32') {
-    chmodSync(binaryPath, 0o755)
-  }
-  process.stdout.write(`reddb: installed binary at ${binaryPath}\n`)
-}
-
-function defaultBinaryName() {
-  return process.platform === 'win32' ? 'red.exe' : 'red'
-}
-
-function normalizeTag(value) {
-  const v = String(value).trim()
-  return v.startsWith('v') ? v : `v${v}`
-}

package/src/internal/asset-fetcher/asset-name.js

@@ -1,37 +0,0 @@
-/**
- * Resolve the GitHub release asset filename for a given Node
- * `process.platform` / `process.arch` pair and binary base name.
- *
- * Mapping is the existing scheme from `drivers/js/postinstall.js`:
- *   linux  + x64       → <bin>-linux-x86_64
- *   linux  + arm64     → <bin>-linux-aarch64
- *   linux  + arm/armv7l→ <bin>-linux-armv7
- *   darwin + x64       → <bin>-macos-x86_64
- *   darwin + arm64     → <bin>-macos-aarch64
- *   win32  + x64       → <bin>-windows-x86_64.exe
- *
- * Throws `UnsupportedPlatformError` for any other combination.
- */
-
-export class UnsupportedPlatformError extends Error {
-  constructor(platform, arch) {
-    super(`unsupported platform/arch combination: ${platform}/${arch}`)
-    this.name = 'UnsupportedPlatformError'
-    this.code = 'UNSUPPORTED_PLATFORM'
-    this.platform = platform
-    this.arch = arch
-  }
-}
-
-export function composeAssetName({ platform, arch, binName }) {
-  if (typeof binName !== 'string' || binName === '') {
-    throw new TypeError('composeAssetName: `binName` must be a non-empty string')
-  }
-  if (platform === 'linux' && arch === 'x64') return `${binName}-linux-x86_64`
-  if (platform === 'linux' && arch === 'arm64') return `${binName}-linux-aarch64`
-  if (platform === 'linux' && (arch === 'arm' || arch === 'armv7l')) return `${binName}-linux-armv7`
-  if (platform === 'darwin' && arch === 'x64') return `${binName}-macos-x86_64`
-  if (platform === 'darwin' && arch === 'arm64') return `${binName}-macos-aarch64`
-  if (platform === 'win32' && arch === 'x64') return `${binName}-windows-x86_64.exe`
-  throw new UnsupportedPlatformError(platform, arch)
-}

package/src/internal/asset-fetcher/checksum.js

@@ -1,23 +0,0 @@
-import { createHash } from 'node:crypto'
-
-export class ChecksumMismatchError extends Error {
-  constructor(expected, actual) {
-    super(`checksum mismatch: expected sha256=${expected}, got sha256=${actual}`)
-    this.name = 'ChecksumMismatchError'
-    this.code = 'CHECKSUM_MISMATCH'
-    this.expected = expected
-    this.actual = actual
-  }
-}
-
-export function sha256Hex(buf) {
-  return createHash('sha256').update(buf).digest('hex')
-}
-
-export function verifySha256(buf, expected) {
-  const expectedNorm = String(expected).trim().toLowerCase()
-  const actual = sha256Hex(buf)
-  if (actual !== expectedNorm) {
-    throw new ChecksumMismatchError(expectedNorm, actual)
-  }
-}

package/src/internal/asset-fetcher/download.js

@@ -1,170 +0,0 @@
-import { request as httpsRequest } from 'node:https'
-import { request as httpRequest } from 'node:http'
-
-const MAX_REDIRECTS = 5
-
-/**
- * Hosts a release download may be served from. The postinstall script writes
- * the response to disk and then executes it, so an unrestricted redirect
- * chain (or a plain-http hop) turns any network position into code
- * execution on the installing machine. GitHub serves release assets from
- * `github.com` and redirects to its object storage.
- */
-const ALLOWED_HOSTS = new Set([
-  'github.com',
-  'objects.githubusercontent.com',
-  'release-assets.githubusercontent.com',
-  'raw.githubusercontent.com',
-])
-
-/**
- * Ceiling on a downloaded asset. The `red` binary is tens of megabytes; a
- * response without this cap is buffered in full whatever its size.
- */
-const MAX_BODY_BYTES = 512 * 1024 * 1024
-
-export class DisallowedHostError extends Error {
-  constructor(url) {
-    super(`refusing to download from a non-allowlisted host: ${url}`)
-    this.name = 'DisallowedHostError'
-    this.code = 'DISALLOWED_HOST'
-    this.url = url
-  }
-}
-
-export class ResponseTooLargeError extends Error {
-  constructor(url, limit) {
-    super(`response from ${url} exceeds the ${limit}-byte limit`)
-    this.name = 'ResponseTooLargeError'
-    this.code = 'RESPONSE_TOO_LARGE'
-    this.url = url
-    this.limit = limit
-  }
-}
-
-/**
- * Reject anything that is not https on an allowlisted host. Applied to the
- * initial URL and to every redirect target, since a redirect is exactly how
- * an attacker would leave the allowlist.
- *
- * `allowedHosts` exists so the test suite can point the transport at a local
- * server; production callers never pass it and get {@link ALLOWED_HOSTS}
- * plus the https requirement.
- */
-export function assertDownloadableUrl(url, allowedHosts = ALLOWED_HOSTS) {
-  let parsed
-  try {
-    parsed = new URL(url)
-  } catch {
-    throw new DisallowedHostError(url)
-  }
-  const isDefaultPolicy = allowedHosts === ALLOWED_HOSTS
-  if (isDefaultPolicy && parsed.protocol !== 'https:') {
-    throw new DisallowedHostError(url)
-  }
-  if (!allowedHosts.has(parsed.hostname)) {
-    throw new DisallowedHostError(url)
-  }
-  return parsed
-}
-
-export class AssetNotFoundError extends Error {
-  constructor(url) {
-    super(`asset not found (HTTP 404) at ${url}`)
-    this.name = 'AssetNotFoundError'
-    this.code = 'ASSET_NOT_FOUND'
-    this.url = url
-  }
-}
-
-export class HttpError extends Error {
-  constructor(status, url) {
-    super(`HTTP ${status} fetching ${url}`)
-    this.name = 'HttpError'
-    this.code = 'HTTP_ERROR'
-    this.status = status
-    this.url = url
-  }
-}
-
-export class TooManyRedirectsError extends Error {
-  constructor(url) {
-    super(`too many redirects (>${MAX_REDIRECTS}) starting at ${url}`)
-    this.name = 'TooManyRedirectsError'
-    this.code = 'TOO_MANY_REDIRECTS'
-    this.url = url
-  }
-}
-
-function resolveLocation(currentUrl, location) {
-  if (/^https?:\/\//i.test(location)) return location
-  return new URL(location, currentUrl).toString()
-}
-
-export function downloadFollowingRedirects(
-  url,
-  { userAgent, originalUrl, allowedHosts } = {},
-  depth = 0,
-) {
-  const startUrl = originalUrl || url
-  if (depth > MAX_REDIRECTS) {
-    return Promise.reject(new TooManyRedirectsError(startUrl))
-  }
-  let parsed
-  try {
-    parsed = assertDownloadableUrl(url, allowedHosts)
-  } catch (err) {
-    return Promise.reject(err)
-  }
-  const request = parsed.protocol === 'http:' ? httpRequest : httpsRequest
-  return new Promise((resolve, reject) => {
-    const req = request(
-      url,
-      {
-        method: 'GET',
-        headers: {
-          'User-Agent': userAgent || 'reddb-internal-asset-fetcher',
-          Accept: 'application/octet-stream',
-        },
-      },
-      (res) => {
-        const status = res.statusCode || 0
-        if (status >= 300 && status < 400 && res.headers.location) {
-          res.resume()
-          const next = resolveLocation(url, res.headers.location)
-          downloadFollowingRedirects(
-            next,
-            { userAgent, originalUrl: startUrl, allowedHosts },
-            depth + 1,
-          ).then(resolve, reject)
-          return
-        }
-        if (status === 404) {
-          res.resume()
-          reject(new AssetNotFoundError(startUrl))
-          return
-        }
-        if (status < 200 || status >= 300) {
-          res.resume()
-          reject(new HttpError(status, url))
-          return
-        }
-        const chunks = []
-        let received = 0
-        res.on('data', (chunk) => {
-          received += chunk.length
-          if (received > MAX_BODY_BYTES) {
-            res.destroy()
-            reject(new ResponseTooLargeError(startUrl, MAX_BODY_BYTES))
-            return
-          }
-          chunks.push(chunk)
-        })
-        res.on('end', () => resolve(Buffer.concat(chunks)))
-        res.on('error', reject)
-      },
-    )
-    req.on('error', reject)
-    req.end()
-  })
-}

package/src/internal/asset-fetcher/index.js

@@ -1,130 +0,0 @@
-/**
- * @reddb-io/internal-asset-fetcher — fetch a `red`/`red_client` binary
- * from a GitHub release.
- *
- * Public surface: one function.
- *
- *   fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256? }) → Buffer
- *
- * Steps:
- *   1. Map (platform, arch, binName) → asset filename.
- *   2. Compose the GitHub download URL: `https://github.com/<repo>/releases/download/<tag>/<asset>`.
- *   3. Follow up to 5 redirects, returning the final body as a Buffer.
- *   4. If `sha256` was supplied, verify before returning.
- *
- * Errors carry distinct `.code` values so callers can differentiate:
- *   - UNSUPPORTED_PLATFORM   — no asset for this platform/arch
- *   - ASSET_NOT_FOUND        — HTTP 404 (release/tag/asset name wrong)
- *   - CHECKSUM_MISMATCH      — body downloaded but sha256 mismatched
- *   - HTTP_ERROR             — any other non-2xx status
- *   - TOO_MANY_REDIRECTS     — redirect chain longer than 5 hops
- *
- * Internal modules (`./asset-name.js`, `./download.js`, `./checksum.js`)
- * are not part of the public contract — only `fetchReleaseAsset` is.
- * They are imported directly in tests for focused coverage.
- */
-
-import { composeAssetName } from './asset-name.js'
-import { downloadFollowingRedirects } from './download.js'
-import { sha256Hex, verifySha256, ChecksumMismatchError } from './checksum.js'
-
-/**
- * A GitHub `owner/name` pair. `repo` reaches this function from
- * `REDDB_POSTINSTALL_REPO` / `REDDB_MCP_REPO`, and is interpolated into the
- * download URL, so a value containing a path or authority would point the
- * download somewhere else entirely.
- */
-const REPO_PATTERN = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/
-
-/** A release tag, as it appears in the download URL path. */
-const TAG_PATTERN = /^[A-Za-z0-9._+-]+$/
-
-export class ChecksumUnavailableError extends Error {
-  constructor(assetName) {
-    super(
-      `no SHA256SUMS entry for ${assetName}; refusing to install an unverified binary ` +
-        `(set REDDB_POSTINSTALL_ALLOW_UNVERIFIED=1 to override)`,
-    )
-    this.name = 'ChecksumUnavailableError'
-    this.code = 'CHECKSUM_UNAVAILABLE'
-    this.assetName = assetName
-  }
-}
-
-/**
- * Parse a `SHA256SUMS` file (`<hex>  <filename>` per line) and return the
- * digest recorded for `assetName`, or `null` when it is not listed.
- */
-export function sha256FromSumsFile(text, assetName) {
-  for (const line of String(text).split('\n')) {
-    const match = line.trim().match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/)
-    if (match && match[2].trim() === assetName) {
-      return match[1].toLowerCase()
-    }
-  }
-  return null
-}
-
-export async function fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256 } = {}) {
-  if (typeof repo !== 'string' || repo === '') {
-    throw new TypeError('fetchReleaseAsset: `repo` must be a non-empty string (e.g. "reddb-io/reddb")')
-  }
-  if (typeof tag !== 'string' || tag === '') {
-    throw new TypeError('fetchReleaseAsset: `tag` must be a non-empty string (e.g. "v0.2.9")')
-  }
-  if (typeof platform !== 'string' || platform === '') {
-    throw new TypeError('fetchReleaseAsset: `platform` must be a non-empty string')
-  }
-  if (typeof arch !== 'string' || arch === '') {
-    throw new TypeError('fetchReleaseAsset: `arch` must be a non-empty string')
-  }
-
-  if (!REPO_PATTERN.test(repo)) {
-    throw new TypeError(`fetchReleaseAsset: \`repo\` must be "owner/name", got ${JSON.stringify(repo)}`)
-  }
-  if (!TAG_PATTERN.test(tag)) {
-    throw new TypeError(`fetchReleaseAsset: \`tag\` contains unsupported characters: ${JSON.stringify(tag)}`)
-  }
-
-  const assetName = composeAssetName({ platform, arch, binName })
-  const base = `https://github.com/${repo}/releases/download/${tag}`
-  const body = await downloadFollowingRedirects(`${base}/${assetName}`)
-
-  // The caller may pin a digest; otherwise fall back to the `SHA256SUMS`
-  // file the release publishes beside the assets. The downloaded bytes are
-  // written to disk and executed, so installing them unverified is the one
-  // outcome worth failing the install over — `install.sh` has verified since
-  // it shipped, and this path had not.
-  if (sha256) {
-    verifySha256(body, sha256)
-    return body
-  }
-
-  let expected = null
-  try {
-    const sums = await downloadFollowingRedirects(`${base}/SHA256SUMS`)
-    expected = sha256FromSumsFile(sums.toString('utf8'), assetName)
-  } catch {
-    expected = null
-  }
-  if (expected) {
-    if (sha256Hex(body) !== expected) {
-      throw new ChecksumMismatchError(expected, sha256Hex(body))
-    }
-    return body
-  }
-  if (allowUnverified()) {
-    return body
-  }
-  throw new ChecksumUnavailableError(assetName)
-}
-
-/**
- * Escape hatch for installing from a release that predates `SHA256SUMS`, or
- * from a fork that does not publish one. Opt-in and loud rather than the
- * silent default it used to be.
- */
-function allowUnverified() {
-  const raw = process.env.REDDB_POSTINSTALL_ALLOW_UNVERIFIED
-  return raw === '1' || raw === 'true' || raw === 'yes'
-}

package/src/internal/bin-resolver/index.js

@@ -1,57 +0,0 @@
-/**
- * @reddb-io/internal-bin-resolver — runtime lookup for a pinned binary.
- *
- * Precedence:
- *   1. `process.env[envVar]` if set and non-empty → returned verbatim.
- *      No existence probe: the env var is the user's "I know what I'm
- *      doing" override.
- *   2. `<packageRoot>/bin/<name>` if it exists.
- *   3. Otherwise throw an actionable error naming the env var, the
- *      expected local path, and a one-line `pnpm install` hint.
- *
- * `PATH` is deliberately never consulted. SDK/client wire formats are
- * version-coupled to the binary; silent fallback to a stale `PATH`
- * binary fails as misframed RPC, not "command not found". See ADR 0006.
- */
-
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-
-/**
- * @param {{ name: string, packageRoot: string, envVar: string }} opts
- * @returns {string} absolute path to the binary
- * @throws {Error} when neither env override nor local binary is usable
- */
-export function resolveBin(opts) {
-  if (!opts || typeof opts !== 'object') {
-    throw new TypeError('resolveBin: options object required')
-  }
-  const { name, packageRoot, envVar } = opts
-  if (typeof name !== 'string' || name === '') {
-    throw new TypeError('resolveBin: `name` must be a non-empty string')
-  }
-  if (typeof packageRoot !== 'string' || packageRoot === '') {
-    throw new TypeError('resolveBin: `packageRoot` must be a non-empty string')
-  }
-  if (typeof envVar !== 'string' || envVar === '') {
-    throw new TypeError('resolveBin: `envVar` must be a non-empty string')
-  }
-
-  const override = process.env?.[envVar]
-  if (typeof override === 'string' && override !== '') {
-    return override
-  }
-
-  const local = join(packageRoot, 'bin', name)
-  if (existsSync(local)) {
-    return local
-  }
-
-  throw new Error(
-    `reddb: binary "${name}" not found.\n` +
-      `  expected at: ${local}\n` +
-      `  override:    set ${envVar}=/path/to/${name}\n` +
-      `  fix:         re-run \`pnpm install\` (the postinstall script downloads it),\n` +
-      `               or check the postinstall log for a download error.`,
-  )
-}

package/src/internal/version-compare/index.js

@@ -1,163 +0,0 @@
-/**
- * @reddb-io/internal-version-compare — install/upgrade/skip verdict for
- * the CLI postinstall.
- *
- * Asymmetry vs SDK/client (per ADR 0006):
- *   - SDK/client postinstalls *always* download a pinned binary because
- *     the wire format is version-coupled to the driver.
- *   - The CLI is a launcher. Users typically already have `red` on PATH
- *     and would resent each `npm i -g @reddb-io/cli` re-downloading.
- *     We compare versions and only fetch when strictly newer.
- *
- * Verdict table:
- *   exec throws                            → action='install'  (no binary detected)
- *   exec returns unparseable output        → action='install'  (warn, fetch fresh)
- *   PATH version  <  packageVersion        → action='upgrade'
- *   PATH version  >= packageVersion        → action='skip'
- *
- * Prerelease ordering follows semver 2.0.0 §11: a normal release ranks
- * above any prerelease of the same MAJOR.MINOR.PATCH.
- */
-
-const SEMVER_RE = /\b(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?\b/
-
-/**
- * Extract a semver-shaped version string from arbitrary `red --version`
- * output. Accepts `reddb 0.2.9`, bare `0.2.9`, or `red 1.0.0-rc.1`.
- *
- * @param {string} text
- * @returns {string|null} normalised `MAJOR.MINOR.PATCH[-prerelease]` or null
- */
-export function parseVersion(text) {
-  if (typeof text !== 'string') return null
-  const m = text.match(SEMVER_RE)
-  if (!m) return null
-  const [, maj, min, pat, pre] = m
-  return pre ? `${maj}.${min}.${pat}-${pre}` : `${maj}.${min}.${pat}`
-}
-
-/**
- * semver 2.0.0 ordering. Returns -1 / 0 / 1.
- *
- * Throws TypeError if either side is not parseable — this is a
- * programmer error, not a runtime fallback path.
- */
-export function compareSemver(a, b) {
-  const pa = parseVersion(a)
-  const pb = parseVersion(b)
-  if (pa === null) throw new TypeError(`compareSemver: invalid version "${a}"`)
-  if (pb === null) throw new TypeError(`compareSemver: invalid version "${b}"`)
-
-  const [coreA, preA] = splitCore(pa)
-  const [coreB, preB] = splitCore(pb)
-
-  for (let i = 0; i < 3; i++) {
-    if (coreA[i] !== coreB[i]) return coreA[i] < coreB[i] ? -1 : 1
-  }
-
-  // Cores equal — apply §11: no-prerelease ranks above any prerelease.
-  if (preA === null && preB === null) return 0
-  if (preA === null) return 1
-  if (preB === null) return -1
-
-  return comparePrerelease(preA, preB)
-}
-
-function splitCore(v) {
-  const dash = v.indexOf('-')
-  const core = dash === -1 ? v : v.slice(0, dash)
-  const pre = dash === -1 ? null : v.slice(dash + 1)
-  const parts = core.split('.').map((n) => Number(n))
-  return [parts, pre]
-}
-
-function comparePrerelease(a, b) {
-  const sa = a.split('.')
-  const sb = b.split('.')
-  const len = Math.min(sa.length, sb.length)
-  for (let i = 0; i < len; i++) {
-    const c = compareIdentifier(sa[i], sb[i])
-    if (c !== 0) return c
-  }
-  if (sa.length === sb.length) return 0
-  return sa.length < sb.length ? -1 : 1
-}
-
-function compareIdentifier(a, b) {
-  const aNum = /^\d+$/.test(a)
-  const bNum = /^\d+$/.test(b)
-  if (aNum && bNum) {
-    const na = Number(a)
-    const nb = Number(b)
-    return na === nb ? 0 : na < nb ? -1 : 1
-  }
-  if (aNum) return -1 // numeric < alphanumeric per §11
-  if (bNum) return 1
-  return a === b ? 0 : a < b ? -1 : 1
-}
-
-/**
- * Decide what the CLI postinstall should do.
- *
- * @param {{ packageVersion: string, exec: () => string }} opts
- *   `exec` is called with no arguments and is expected to return the
- *   stdout of `red --version` (sync). It may throw — that signals "no
- *   PATH binary detected" and routes to action='install'.
- * @returns {{ action: 'install'|'upgrade'|'skip', reason: string }}
- */
-export function compareInstalled(opts) {
-  if (!opts || typeof opts !== 'object') {
-    throw new TypeError('compareInstalled: options object required')
-  }
-  const { packageVersion, exec } = opts
-  if (typeof packageVersion !== 'string' || packageVersion === '') {
-    throw new TypeError('compareInstalled: `packageVersion` must be a non-empty string')
-  }
-  if (typeof exec !== 'function') {
-    throw new TypeError('compareInstalled: `exec` must be a function')
-  }
-  if (parseVersion(packageVersion) === null) {
-    throw new TypeError(`compareInstalled: \`packageVersion\` "${packageVersion}" is not parseable semver`)
-  }
-
-  let raw
-  try {
-    raw = exec()
-  } catch (err) {
-    return {
-      action: 'install',
-      reason: `no PATH \`red\` binary detected (${err.message || 'exec failed'})`,
-    }
-  }
-
-  const installed = parseVersion(typeof raw === 'string' ? raw : '')
-  if (installed === null) {
-    return {
-      action: 'install',
-      reason: `unparseable PATH \`red --version\` output (${truncate(String(raw))})`,
-    }
-  }
-
-  const cmp = compareSemver(installed, packageVersion)
-  if (cmp < 0) {
-    return {
-      action: 'upgrade',
-      reason: `PATH \`red\` ${installed} is older than package ${packageVersion}`,
-    }
-  }
-  if (cmp > 0) {
-    return {
-      action: 'skip',
-      reason: `PATH \`red\` ${installed} is newer than package ${packageVersion}`,
-    }
-  }
-  return {
-    action: 'skip',
-    reason: `PATH \`red\` already at ${installed}`,
-  }
-}
-
-function truncate(s) {
-  const oneLine = s.replace(/\s+/g, ' ').trim()
-  return oneLine.length > 80 ? `${oneLine.slice(0, 77)}...` : oneLine
-}