@reddb-io/cli 1.0.1

package/drivers/js/src/spawn.js

@@ -0,0 +1,177 @@
+/**
+ * Runtime-agnostic subprocess spawn.
+ *
+ * Returns a uniform handle exposing:
+ *   - `stdin`  WritableStream-like (has `write(buf)`, `end()`)
+ *   - `stdout` AsyncIterable<Uint8Array> for line-buffered reading
+ *   - `kill()` terminate the process
+ *   - `wait()` resolve when the process exits
+ *
+ * Detects Bun and Deno first because they ship native, Node-incompatible
+ * spawn APIs that are faster than their `node:child_process` shims.
+ */
+
+const isBun = typeof globalThis.Bun !== 'undefined' && typeof globalThis.Bun.spawn === 'function'
+const isDeno = typeof globalThis.Deno !== 'undefined' && typeof globalThis.Deno.Command === 'function'
+
+/** @returns {Promise<RedProcess>} */
+export async function spawnRed(binary, args) {
+  if (isBun) return spawnBun(binary, args)
+  if (isDeno) return spawnDeno(binary, args)
+  return spawnNode(binary, args)
+}
+
+// ---------------------------------------------------------------------------
+// Node
+// ---------------------------------------------------------------------------
+
+async function spawnNode(binary, args) {
+  const { spawn } = await import('node:child_process')
+  const child = spawn(binary, args, { stdio: ['pipe', 'pipe', 'inherit'] })
+
+  return {
+    runtime: 'node',
+    stdin: {
+      write(buf) {
+        return new Promise((resolve, reject) => {
+          child.stdin.write(buf, (err) => (err ? reject(err) : resolve()))
+        })
+      },
+      end() {
+        child.stdin.end()
+      },
+    },
+    stdout: child.stdout, // already AsyncIterable<Buffer>
+    kill() {
+      child.kill('SIGTERM')
+    },
+    wait() {
+      return new Promise((resolve) => {
+        child.on('exit', (code) => resolve(code ?? 0))
+      })
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Bun
+// ---------------------------------------------------------------------------
+
+function spawnBun(binary, args) {
+  const child = globalThis.Bun.spawn({
+    cmd: [binary, ...args],
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'inherit',
+  })
+
+  const writer = child.stdin.getWriter ? child.stdin.getWriter() : null
+
+  return {
+    runtime: 'bun',
+    stdin: {
+      async write(buf) {
+        if (writer) {
+          await writer.write(buf)
+        } else {
+          // Older Bun: stdin is a FileSink
+          child.stdin.write(buf)
+          await child.stdin.flush()
+        }
+      },
+      end() {
+        if (writer) {
+          writer.close()
+        } else {
+          child.stdin.end()
+        }
+      },
+    },
+    stdout: bunStdoutToAsyncIterable(child.stdout),
+    kill() {
+      child.kill()
+    },
+    wait() {
+      return child.exited
+    },
+  }
+}
+
+async function* bunStdoutToAsyncIterable(stream) {
+  const reader = stream.getReader()
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) return
+      yield value
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Deno
+// ---------------------------------------------------------------------------
+
+async function spawnDeno(binary, args) {
+  const cmd = new globalThis.Deno.Command(binary, {
+    args,
+    stdin: 'piped',
+    stdout: 'piped',
+    stderr: 'inherit',
+  })
+  const child = cmd.spawn()
+  const writer = child.stdin.getWriter()
+
+  return {
+    runtime: 'deno',
+    stdin: {
+      async write(buf) {
+        await writer.write(buf)
+      },
+      end() {
+        try {
+          writer.close()
+        } catch {
+          // already closed
+        }
+      },
+    },
+    stdout: denoStdoutToAsyncIterable(child.stdout),
+    kill() {
+      try {
+        child.kill('SIGTERM')
+      } catch {
+        // process may already be gone
+      }
+    },
+    async wait() {
+      const status = await child.status
+      return status.code ?? 0
+    },
+  }
+}
+
+async function* denoStdoutToAsyncIterable(stream) {
+  const reader = stream.getReader()
+  try {
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) return
+      yield value
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+/**
+ * @typedef {{
+ *   runtime: 'node' | 'bun' | 'deno',
+ *   stdin: { write(buf: Uint8Array): Promise<void>, end(): void },
+ *   stdout: AsyncIterable<Uint8Array>,
+ *   kill(): void,
+ *   wait(): Promise<number>,
+ * }} RedProcess
+ */

package/drivers/js/src/url.js

@@ -0,0 +1,271 @@
+/**
+ * `red://` connection-string parser.
+ *
+ * One URL covers every transport RedDB speaks:
+ *
+ *   red://                                          embedded in-memory
+ *   red:///abs/path/data.rdb                        embedded persistent
+ *   red://user:pass@host:5050                       remote, default proto=red (wire)
+ *   red://host:8080?proto=https                     remote HTTPS
+ *   red://host:5432?proto=pg                        PostgreSQL wire
+ *   red://host:5055?proto=grpc&token=sk-abc         remote gRPC w/ bearer
+ *   red://host:8080?proto=https&apiKey=ak-xyz       remote HTTPS w/ api key
+ *
+ * Backwards-compat: legacy `memory://`, `file://`, `grpc://` URLs
+ * still work via `parseLegacyUrl`. New code should prefer `red://`
+ * because it carries auth + protocol selection in one place.
+ */
+
+import { RedDBError } from './protocol.js'
+
+/**
+ * @typedef {object} ParsedUri
+ * @property {'embedded' | 'http' | 'https' | 'red' | 'reds' | 'grpc' | 'grpcs' | 'pg'} kind
+ * @property {string} [host]
+ * @property {number} [port]
+ * @property {string} [path]            // for embedded `file://`-equivalent
+ * @property {string} [username]
+ * @property {string} [password]
+ * @property {string} [token]
+ * @property {string} [apiKey]
+ * @property {string} [loginUrl]        // explicit override for login flow
+ * @property {URLSearchParams} [params] // remaining query params
+ * @property {string} originalUri
+ */
+
+/**
+ * Parse any URI string into a normalised `ParsedUri`.
+ * Accepts `red://`, `memory://`, `file://`, `grpc://` (the latter
+ * three for backwards compat).
+ *
+ * @param {string} uri
+ * @returns {ParsedUri}
+ */
+export function parseUri(uri) {
+  if (typeof uri !== 'string' || uri.length === 0) {
+    throw new TypeError(
+      "connect() requires a URI string (e.g. 'red://localhost:5050' or 'red:///data.rdb')",
+    )
+  }
+  if (uri.startsWith('red://') || uri === 'red:' || uri === 'red:/') {
+    return parseRedUrl(uri)
+  }
+  return parseLegacyUrl(uri)
+}
+
+/**
+ * Parse a `red://` URL.
+ *
+ * Authority shape: `[user[:pass]@]host[:port]`
+ * Path: optional, used as filesystem path when `host` is absent or
+ * is the special token `localhost-embedded` (rare).
+ * Query: `proto`, `token`, `apiKey`, `loginUrl`.
+ */
+export function parseRedUrl(uri) {
+  // The host might be missing (`red:///path`), the URL constructor
+  // requires *something* there. Re-write to a parse-friendly shape:
+  // - `red:///x`     → `red://embedded.local/x`   (embedded with path)
+  // - `red://memory` → `red://embedded.local`     (embedded in-memory)
+  // - `red://`       → `red://embedded.local`     (embedded in-memory)
+  let normalised = uri
+  if (uri === 'red:' || uri === 'red:/' || uri === 'red://') {
+    normalised = 'red://embedded.local'
+  } else if (uri.startsWith('red:///')) {
+    normalised = `red://embedded.local${uri.slice('red://'.length)}`
+  } else if (
+    uri === 'red://memory'
+    || uri === 'red://memory/'
+    || uri === 'red://:memory'
+    || uri === 'red://:memory:'  // SQLite-style ":memory:" alias
+  ) {
+    normalised = 'red://embedded.local'
+  }
+
+  let parsed
+  try {
+    parsed = new URL(normalised)
+  } catch (err) {
+    throw new RedDBError('UNPARSEABLE_URI', `failed to parse '${uri}': ${err.message}`)
+  }
+
+  const params = parsed.searchParams
+  const proto = (params.get('proto') || '').toLowerCase()
+  const path = parsed.pathname && parsed.pathname !== '/' ? parsed.pathname : ''
+
+  // Embedded: special host, OR `proto=embedded`, OR no proto + has path
+  // and the user clearly meant a file path (red:///abs/path).
+  if (parsed.hostname === 'embedded.local') {
+    if (path) {
+      return {
+        kind: 'embedded',
+        path,
+        params,
+        originalUri: uri,
+      }
+    }
+    return {
+      kind: 'embedded',
+      params,
+      originalUri: uri,
+    }
+  }
+
+  // Remote — default proto is red (wire).
+  const kind = resolveKind(proto)
+  const port = parsed.port ? Number(parsed.port) : defaultPortFor(kind)
+  const username = parsed.username ? decodeURIComponent(parsed.username) : undefined
+  const password = parsed.password ? decodeURIComponent(parsed.password) : undefined
+
+  return {
+    kind,
+    host: parsed.hostname,
+    port,
+    path: path || undefined,
+    username,
+    password,
+    token: params.get('token') ?? undefined,
+    apiKey: params.get('apiKey') ?? params.get('api_key') ?? undefined,
+    loginUrl: params.get('loginUrl') ?? params.get('login_url') ?? undefined,
+    params,
+    originalUri: uri,
+  }
+}
+
+/**
+ * Backwards-compat parser for the legacy URL shapes the driver
+ * accepted before `red://` existed. Returns the same `ParsedUri`
+ * shape so downstream code is uniform.
+ */
+export function parseLegacyUrl(uri) {
+  if (uri === 'memory://' || uri === 'memory:') {
+    return { kind: 'embedded', originalUri: uri }
+  }
+  if (uri.startsWith('file://')) {
+    const path = uri.slice('file://'.length)
+    if (!path) {
+      throw new TypeError(`invalid file:// URI: missing path in '${uri}'`)
+    }
+    return { kind: 'embedded', path, originalUri: uri }
+  }
+  if (
+    uri.startsWith('grpc://')
+    || uri.startsWith('grpcs://')
+    || uri.startsWith('reds://')
+  ) {
+    const scheme = uri.split('://', 1)[0]
+    const stripped = uri.slice(`${scheme}://`.length)
+    const [hostPort] = stripped.split(/[/?]/, 1)
+    const [host, portStr] = hostPort.split(':')
+    if (!host) {
+      throw new TypeError(`invalid ${scheme}:// URI: missing host in '${uri}'`)
+    }
+    const legacyKind = scheme === 'reds' ? 'reds' : scheme === 'grpcs' ? 'grpcs' : scheme === 'grpc' ? 'grpc' : 'red'
+    return {
+      kind: legacyKind,
+      host,
+      port: portStr ? Number(portStr) : defaultPortFor(legacyKind),
+      originalUri: uri,
+    }
+  }
+  if (uri.startsWith('http://') || uri.startsWith('https://')) {
+    let parsed
+    try {
+      parsed = new URL(uri)
+    } catch (err) {
+      throw new RedDBError('UNPARSEABLE_URI', `failed to parse '${uri}': ${err.message}`)
+    }
+    return {
+      kind: parsed.protocol === 'https:' ? 'https' : 'http',
+      host: parsed.hostname,
+      port: parsed.port ? Number(parsed.port) : defaultPortFor(parsed.protocol === 'https:' ? 'https' : 'http'),
+      path: parsed.pathname !== '/' ? parsed.pathname : undefined,
+      username: parsed.username ? decodeURIComponent(parsed.username) : undefined,
+      password: parsed.password ? decodeURIComponent(parsed.password) : undefined,
+      token: parsed.searchParams.get('token') ?? undefined,
+      apiKey: parsed.searchParams.get('apiKey') ?? undefined,
+      params: parsed.searchParams,
+      originalUri: uri,
+    }
+  }
+  throw new RedDBError(
+    'UNSUPPORTED_SCHEME',
+    `unsupported URI: '${uri}'. Use 'red://...' or one of memory://, file://, grpc://, http(s)://`,
+  )
+}
+
+function resolveKind(protoQueryParam) {
+  switch (protoQueryParam) {
+    case '':
+    case 'red':
+      return 'red'
+    case 'reds':
+      return 'reds'
+    case 'grpc':
+      return 'grpc'
+    case 'grpcs':
+      return 'grpcs'
+    case 'http':
+      return 'http'
+    case 'https':
+      return 'https'
+    case 'pg':
+    case 'postgres':
+    case 'postgresql':
+      return 'pg'
+    default:
+      throw new RedDBError(
+        'UNSUPPORTED_PROTO',
+        `unknown proto='${protoQueryParam}'. Supported: red | reds | grpc | grpcs | http | https | pg`,
+      )
+  }
+}
+
+function defaultPortFor(kind) {
+  switch (kind) {
+    case 'http':
+      return 8080
+    case 'https':
+      return 8443
+    case 'red':
+    case 'reds':
+    case 'redwire':
+      return 5050
+    case 'grpc':
+      return 5055
+    case 'grpcs':
+      return 5056
+    case 'pg':
+    case 'postgres':
+    case 'postgresql':
+      return 5432
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Derive the HTTP login URL (`/auth/login`) from a parsed URI.
+ * Used by the auto-login flow when the user supplies `username:password@`
+ * but not an explicit `loginUrl`.
+ *
+ * Strategy: if proto is already http/https, just append `/auth/login`.
+ * For grpc/grpcs/pg, default to https://host:443 — operators that
+ * don't want that should pass `loginUrl=` explicitly.
+ */
+export function deriveLoginUrl(parsed) {
+  if (parsed.loginUrl) return parsed.loginUrl
+  if (!parsed.host) {
+    throw new RedDBError(
+      'AUTH_LOGIN_NEEDS_HOST',
+      'cannot derive loginUrl without a host; pass it explicitly via loginUrl=...',
+    )
+  }
+  if (parsed.kind === 'http' || parsed.kind === 'https') {
+    const scheme = parsed.kind
+    const port = parsed.port ?? defaultPortFor(parsed.kind)
+    return `${scheme}://${parsed.host}:${port}/auth/login`
+  }
+  // Non-HTTP transports — default to HTTPS on 443 unless the user
+  // tells us otherwise.
+  return `https://${parsed.host}/auth/login`
+}

package/drivers/js/src/vault.js

@@ -0,0 +1,58 @@
+export class VaultClient {
+  constructor(client, collection = 'red.vault') {
+    this.client = client
+    this.collection = collection
+  }
+
+  put(key, value, options = {}) {
+    rejectVolatileOptions(options, 'vault')
+    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: `VAULT PUT ${keyedIdentifier(collection)}.${keyedIdentifier(key)} = ${keyedValueLiteral(value)}${tags}`,
+    })
+  }
+
+  get(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    return this.client.call('query', {
+      sql: `VAULT GET ${keyedIdentifier(collection)}.${keyedIdentifier(key)}`,
+    })
+  }
+
+  unseal(key, options = {}) {
+    const collection = options.collection ?? this.collection
+    return this.client.call('query', {
+      sql: `UNSEAL VAULT ${keyedIdentifier(collection)}.${keyedIdentifier(key)}`,
+    })
+  }
+}
+
+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/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@reddb-io/cli",
+  "version": "1.0.1",
+  "description": "CLI launcher for RedDB. The JS/TS app driver is published as @reddb-io/sdk.",
+  "type": "commonjs",
+  "bin": {
+    "reddb-cli": "./drivers/js/src/cli.js"
+  },
+  "files": [
+    "drivers/js/src/",
+    "drivers/js/cli-postinstall.js",
+    "drivers/js/package.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@9.15.0",
+  "scripts": {
+    "postinstall": "node drivers/js/cli-postinstall.js",
+    "test": "node drivers/js/test/smoke.test.mjs",
+    "version": "node scripts/sync-version.js"
+  },
+  "keywords": [
+    "database",
+    "multi-model",
+    "vector-search",
+    "graph",
+    "document-store",
+    "key-value",
+    "rust",
+    "embedded"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reddb-io/reddb"
+  },
+  "homepage": "https://github.com/reddb-io/reddb"
+}