@reddb-io/cli 1.0.1

package/drivers/js/cli-postinstall.js

@@ -0,0 +1,109 @@
+/**
+ * cli-postinstall.js — install/upgrade/skip for `@reddb-io/cli`.
+ *
+ * Asymmetry vs SDK postinstall (`drivers/js/postinstall.js`):
+ *   - SDK always downloads — wire format is version-coupled to the driver.
+ *   - CLI compares this package's version against `red --version` on PATH:
+ *       absent  → install
+ *       older   → upgrade (overwrite + one-line log)
+ *       equal   → skip
+ *       newer   → skip ("PATH binary is newer; leaving in place")
+ *       garbage → install (warn, treat as absent)
+ *
+ * See ADR 0007 for the rationale.
+ *
+ * Override hooks (env vars):
+ *   REDDB_SKIP_POSTINSTALL=1      do nothing
+ *   REDDB_BIN=/path/to/red        skip — caller already has a binary
+ *   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 } from 'node:path'
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+
+import { fetchReleaseAsset } from './src/internal/asset-fetcher/index.js'
+import { compareInstalled } from './src/internal/version-compare/index.js'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+// CLI manifest lives at the repo root (../../package.json), and that is the
+// `@reddb-io/cli` package — not the SDK manifest next to this file.
+const pkg = require('../../package.json')
+
+const DEFAULT_REPO = 'reddb-io/reddb'
+
+if (process.env.REDDB_SKIP_POSTINSTALL === '1') {
+  process.stdout.write('reddb-cli: postinstall skipped (REDDB_SKIP_POSTINSTALL=1)\n')
+  process.exit(0)
+}
+
+if (typeof process.env.REDDB_BIN === 'string' && process.env.REDDB_BIN !== '') {
+  process.stdout.write(
+    `reddb-cli: postinstall skipped (REDDB_BIN=${process.env.REDDB_BIN})\n`,
+  )
+  process.exit(0)
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `reddb-cli: postinstall could not download the binary (${err.message}).\n` +
+      `          The package will still install. To use the CLI you can:\n` +
+      `            - set REDDB_BIN=/path/to/red\n` +
+      `            - or install the binary manually from https://github.com/${DEFAULT_REPO}/releases\n`,
+  )
+  process.exit(0)
+})
+
+async function main() {
+  const verdict = compareInstalled({
+    packageVersion: pkg.version,
+    exec: () => execSync('red --version', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }),
+  })
+
+  if (verdict.action === 'skip') {
+    process.stdout.write(`reddb-cli: ${verdict.reason} — skipping download\n`)
+    return
+  }
+
+  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 (verdict.action === 'install') {
+    process.stdout.write(`reddb-cli: ${verdict.reason} — installing red ${tag}\n`)
+  } else {
+    // upgrade
+    process.stdout.write(`reddb-cli: ${verdict.reason} — upgrading red to ${tag}\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-cli: 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/drivers/js/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@reddb-io/sdk",
+  "version": "1.0.1",
+  "description": "Official RedDB driver — talks the native RedWire TCP protocol (mTLS), HTTP, gRPC bridge, or embedded stdio JSON-RPC. Works in Node 18+, Bun and Deno.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "src/",
+    "index.d.ts",
+    "postinstall.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.js",
+    "test": "node --test test/cache.test.mjs && node test/smoke.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "reddb",
+    "database",
+    "client",
+    "driver",
+    "json-rpc",
+    "multi-model",
+    "vector",
+    "graph",
+    "document",
+    "key-value"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/reddb-io/reddb",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reddb-io/reddb.git",
+    "directory": "drivers/js"
+  },
+  "bugs": {
+    "url": "https://github.com/reddb-io/reddb/issues"
+  }
+}

package/drivers/js/src/binary.js

@@ -0,0 +1,66 @@
+/**
+ * Locate the `red` binary for SDK / CLI use.
+ *
+ * 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.
+ *   4. Otherwise throw an actionable error.
+ *
+ *   PATH is **never** consulted. The wire-format coupling between the
+ *   SDK and the embedded engine is too tight to silently bind to
+ *   whatever `red` happens to be on PATH (see ADR 0006).
+ *
+ * CLI lookup (`resolveCliBinary`):
+ *   1. `REDDB_BIN` env var.
+ *   2. `<package>/bin/red[.exe]`.
+ *   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, '..')
+
+function defaultBinaryName() {
+  if (typeof process !== 'undefined' && process.platform === 'win32') {
+    return 'red.exe'
+  }
+  return 'red'
+}
+
+/** SDK runtime lookup. Throws actionable error when binary cannot be located. */
+export function resolveSdkBinary() {
+  const legacy = process.env?.REDDB_BINARY_PATH
+  if (typeof legacy === 'string' && legacy !== '' && !process.env?.REDDB_BIN) {
+    return legacy
+  }
+  return resolveBin({
+    name: defaultBinaryName(),
+    packageRoot: PACKAGE_ROOT,
+    envVar: 'REDDB_BIN',
+  })
+}
+
+/** CLI runtime lookup. Allowed to fall back to PATH per ADR 0006. */
+export function resolveCliBinary() {
+  const override = process.env?.REDDB_BIN
+  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')
+}

package/drivers/js/src/cache.js

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ *
+ * Values are base64-encoded in transit so binary payloads survive JSON.
+ */
+
+export class CacheClient {
+  /** @param {{ call: Function }} client */
+  constructor(client) {
+    this._client = client
+  }
+
+  /**
+   * Fetch a cached value. Returns a Uint8Array on hit, null on miss.
+   * @param {string} namespace
+   * @param {string} key
+   * @returns {Promise<Uint8Array | null>}
+   */
+  async get(namespace, key) {
+    const result = await this._client.call('cache.get', { namespace, key })
+    if (result == null || result.value == null) return null
+    return base64ToBytes(result.value)
+  }
+
+  /**
+   * Store a value in the cache.
+   * @param {string} namespace
+   * @param {string} key
+   * @param {Uint8Array | Buffer | string} value  String is UTF-8 encoded.
+   * @param {object} [opts]
+   * @param {number} [opts.ttl_ms]
+   * @param {string[]} [opts.tags]
+   * @param {object} [opts.policy]
+   * @returns {Promise<void>}
+   */
+  async put(namespace, key, value, opts = {}) {
+    const encoded = bytesToBase64(value)
+    await this._client.call('cache.put', {
+      namespace,
+      key,
+      value: encoded,
+      ...opts,
+    })
+  }
+
+  /**
+   * Check whether a key is present.
+   * @param {string} namespace
+   * @param {string} key
+   * @returns {Promise<'present' | 'absent' | 'maybe'>}
+   */
+  async exists(namespace, key) {
+    const result = await this._client.call('cache.exists', { namespace, key })
+    return result?.status ?? 'maybe'
+  }
+
+  /**
+   * Remove a single entry.
+   * @param {string} namespace
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  async invalidate(namespace, key) {
+    await this._client.call('cache.invalidate', { namespace, key })
+  }
+
+  /**
+   * Remove all entries whose key starts with `prefix`.
+   * @param {string} namespace
+   * @param {string} prefix
+   * @returns {Promise<number>} Number of entries removed.
+   */
+  async invalidatePrefix(namespace, prefix) {
+    const result = await this._client.call('cache.invalidate_prefix', { namespace, prefix })
+    return result?.removed ?? 0
+  }
+
+  /**
+   * Remove all entries tagged with any of the given tags.
+   * @param {string} namespace
+   * @param {string[]} tags
+   * @returns {Promise<number>} Number of entries removed.
+   */
+  async invalidateTags(namespace, tags) {
+    const result = await this._client.call('cache.invalidate_tags', { namespace, tags })
+    return result?.removed ?? 0
+  }
+
+  /**
+   * Remove all entries in a namespace.
+   * Routes to POST /admin/blob_cache/flush_namespace (live endpoint).
+   * @param {string} namespace
+   * @returns {Promise<void>}
+   */
+  async flushNamespace(namespace) {
+    await this._client.call('cache.flush_namespace', { namespace })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function bytesToBase64(value) {
+  if (typeof value === 'string') {
+    const bytes = new TextEncoder().encode(value)
+    return bufToBase64(bytes)
+  }
+  if (value instanceof Uint8Array || (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))) {
+    return bufToBase64(value)
+  }
+  throw new TypeError('cache value must be a string, Uint8Array, or Buffer')
+}
+
+function bufToBase64(bytes) {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64')
+  }
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin)
+}
+
+function base64ToBytes(b64) {
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(b64, 'base64'))
+  }
+  const bin = atob(b64)
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}

package/drivers/js/src/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import { resolveCliBinary } from './binary.js'
+
+const binary = resolveCliBinary()
+const args = process.argv.slice(2)
+
+const child = spawn(binary, args, {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: 'inherit',
+})
+
+child.on('error', (err) => {
+  process.stderr.write(`reddb-cli: ${err.message}\n`)
+  process.exit(1)
+})
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.exit(1)
+  }
+  process.exit(code ?? 0)
+})

package/drivers/js/src/config.js

@@ -0,0 +1,66 @@
+export class ConfigClient {
+  constructor(client, collection = 'red.config') {
+    this.client = client
+    this.collection = collection
+  }
+
+  put(key, value, options = {}) {
+    rejectVolatileOptions(options, 'config')
+    const collection = options.collection ?? this.collection
+    const tags = Array.isArray(options.tags) && options.tags.length > 0
+      ? ` TAGS [${options.tags.map(keyedStringLiteral).join(', ')}]`
+      : ''
+    return this.client.call('query', {
+      sql: `PUT CONFIG ${keyedIdentifier(collection)} ${keyedIdentifier(key)} = ${configValueLiteral(value, options)}${tags}`,
+    })
+  }
+
+  get(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    return this.client.call('query', {
+      sql: `GET CONFIG ${keyedIdentifier(collection)} ${keyedIdentifier(key)}`,
+    })
+  }
+
+  resolve(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    return this.client.call('query', {
+      sql: `RESOLVE CONFIG ${keyedIdentifier(collection)} ${keyedIdentifier(key)}`,
+    })
+  }
+}
+
+function configValueLiteral(value, options) {
+  if (options.secretRef) {
+    const { collection, key } = options.secretRef
+    return `SECRET_REF(vault, ${keyedIdentifier(collection)}.${keyedIdentifier(key)})`
+  }
+  return keyedValueLiteral(value)
+}
+
+function rejectVolatileOptions(options, domain) {
+  for (const field of ['ttl', 'ttlMs', 'ttl_ms', 'expireMs', 'expire_ms', 'expiresAt']) {
+    if (options[field] != null) {
+      throw new TypeError(`${domain} does not support TTL or expiration options`)
+    }
+  }
+}
+
+function keyedIdentifier(value) {
+  const out = String(value)
+  if (!/^[A-Za-z0-9_.]+$/.test(out)) {
+    throw new TypeError('keyed collection and key names must use letters, numbers, underscores, or dots')
+  }
+  return out
+}
+
+function keyedValueLiteral(value) {
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (value == null) return 'NULL'
+  if (Array.isArray(value) || typeof value === 'object') return JSON.stringify(value)
+  return keyedStringLiteral(value)
+}
+
+function keyedStringLiteral(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}

package/drivers/js/src/http.js

@@ -0,0 +1,200 @@
+/**
+ * HTTP transport for the JS driver.
+ *
+ * Mirrors the public surface of `RpcClient` (call, close) but talks
+ * straight to the RedDB HTTP server via fetch() — no binary spawn.
+ * Each `RedDB` method is mapped to a REST endpoint; method names
+ * stay identical to the JSON-RPC ones so `RedDB` doesn't need to
+ * know which transport it's using.
+ *
+ * Endpoint mapping (server-side defined in src/server/routing.rs):
+ *
+ *   query / explain     → POST /query, POST /query/explain
+ *   insert              → POST /collections/:name/rows
+ *   bulk_insert         → POST /collections/:name/bulk/rows
+ *   get                 → GET  /collections/:name/{id}      (entity scan + filter)
+ *   delete              → DELETE /collections/:name/{id}
+ *   health              → GET  /health
+ *   version             → GET  /admin/version
+ *   auth.login          → POST /auth/login
+ *   auth.whoami         → GET  /auth/whoami
+ *   auth.create_api_key → POST /auth/api-keys
+ *   auth.revoke_api_key → DELETE /auth/api-keys/:key
+ *   auth.change_password→ POST /auth/change-password
+ *
+ *   cache.get               → GET    /cache/ns/:ns/:key
+ *   cache.put               → PUT    /cache/ns/:ns/:key
+ *   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
+ *
+ * Auth: every request after construction carries `Authorization:
+ * Bearer <token>` (when set). `setToken(token)` updates it in
+ * place — used by the login flow that exchanges credentials for
+ * a fresh bearer.
+ */
+
+import { RedDBError } from './protocol.js'
+
+export class HttpRpcClient {
+  /**
+   * @param {object} opts
+   * @param {string} opts.baseUrl   Server origin, e.g. 'https://reddb.example.com:8443'
+   * @param {string} [opts.token]   Bearer token / API key
+   */
+  constructor({ baseUrl, token }) {
+    if (typeof baseUrl !== 'string' || baseUrl.length === 0) {
+      throw new TypeError('HttpRpcClient: baseUrl required')
+    }
+    this.baseUrl = baseUrl.replace(/\/$/, '')
+    this.token = token ?? null
+  }
+
+  setToken(token) {
+    this.token = token
+  }
+
+  async close() {
+    // HTTP is stateless — nothing to close.
+  }
+
+  /**
+   * Generic RPC entry point. Routes the named method to the
+   * corresponding HTTP endpoint and returns the parsed JSON body.
+   */
+  async call(method, params = {}) {
+    const route = ROUTES[method]
+    if (!route) {
+      throw new RedDBError(
+        'UNKNOWN_METHOD',
+        `HTTP transport has no route for method '${method}'`,
+      )
+    }
+    const { url, init } = route(this.baseUrl, params)
+    const response = await fetch(url, this.attachAuth(init))
+    return parseResponse(response)
+  }
+
+  attachAuth(init) {
+    const headers = new Headers(init.headers || {})
+    if (this.token && !headers.has('authorization')) {
+      headers.set('authorization', `Bearer ${this.token}`)
+    }
+    if (init.body && !headers.has('content-type')) {
+      headers.set('content-type', 'application/json')
+    }
+    return { ...init, headers }
+  }
+}
+
+async function parseResponse(response) {
+  const text = await response.text()
+  let body = null
+  if (text) {
+    try {
+      body = JSON.parse(text)
+    } catch {
+      body = { raw: text }
+    }
+  }
+  if (!response.ok) {
+    const code = body?.error_code || `HTTP_${response.status}`
+    const message = body?.error || body?.message || `request failed with status ${response.status}`
+    throw new RedDBError(code, message, body)
+  }
+  // RedDB envelope is `{ ok, result, error? }` for some endpoints
+  // and bare JSON for others. Unwrap the envelope when present.
+  if (body && typeof body === 'object' && 'ok' in body) {
+    if (body.ok === false) {
+      const code = body.error_code || 'RPC_ERROR'
+      throw new RedDBError(code, body.error || 'unknown error', body)
+    }
+    return body.result ?? body
+  }
+  return body
+}
+
+// ---------------------------------------------------------------------------
+// Method → HTTP route mapping
+// ---------------------------------------------------------------------------
+
+const ROUTES = {
+  health: (base) => ({ url: `${base}/health`, init: { method: 'GET' } }),
+  version: (base) => ({ url: `${base}/admin/version`, init: { method: 'GET' } }),
+  query: (base, { sql }) => ({
+    url: `${base}/query`,
+    init: { method: 'POST', body: JSON.stringify({ query: sql }) },
+  }),
+  insert: (base, { collection, payload }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/rows`,
+    init: { method: 'POST', body: JSON.stringify(payload) },
+  }),
+  bulk_insert: (base, { collection, payloads }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/bulk/rows`,
+    init: { method: 'POST', body: JSON.stringify({ rows: payloads }) },
+  }),
+  get: (base, { collection, id }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
+    init: { method: 'GET' },
+  }),
+  delete: (base, { collection, id }) => ({
+    url: `${base}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`,
+    init: { method: 'DELETE' },
+  }),
+  'auth.login': (base, { username, password }) => ({
+    url: `${base}/auth/login`,
+    init: { method: 'POST', body: JSON.stringify({ username, password }) },
+  }),
+  'auth.whoami': (base) => ({
+    url: `${base}/auth/whoami`,
+    init: { method: 'GET' },
+  }),
+  'auth.create_api_key': (base, params = {}) => ({
+    url: `${base}/auth/api-keys`,
+    init: { method: 'POST', body: JSON.stringify(params) },
+  }),
+  'auth.revoke_api_key': (base, { key }) => ({
+    url: `${base}/auth/api-keys/${encodeURIComponent(key)}`,
+    init: { method: 'DELETE' },
+  }),
+  'auth.change_password': (base, { current_password, new_password }) => ({
+    url: `${base}/auth/change-password`,
+    init: {
+      method: 'POST',
+      body: JSON.stringify({
+        current_password,
+        new_password,
+      }),
+    },
+  }),
+  'cache.get': (base, { namespace, key }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+    init: { method: 'GET' },
+  }),
+  'cache.put': (base, { namespace, key, value, ttl_ms, tags, policy }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+    init: { method: 'PUT', body: JSON.stringify({ value, ttl_ms, tags, policy }) },
+  }),
+  'cache.exists': (base, { namespace, key }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}/exists`,
+    init: { method: 'GET' },
+  }),
+  'cache.invalidate': (base, { namespace, key }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
+    init: { method: 'DELETE' },
+  }),
+  'cache.invalidate_prefix': (base, { namespace, prefix }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}?prefix=${encodeURIComponent(prefix)}`,
+    init: { method: 'DELETE' },
+  }),
+  'cache.invalidate_tags': (base, { namespace, tags }) => ({
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/tags`,
+    init: { method: 'DELETE', body: JSON.stringify({ tags }) },
+  }),
+  'cache.flush_namespace': (base, { namespace }) => ({
+    url: `${base}/admin/blob_cache/flush_namespace`,
+    init: { method: 'POST', body: JSON.stringify({ namespace }) },
+  }),
+}