inillucent 0.1.4

package/README.md

@@ -0,0 +1,102 @@
+# inillucent
+
+An embedded SQL database that speaks SQLite's dialect on its own storage, with
+full-text and vector search built in — the job of PostgreSQL + pgvector + an
+embedding server, in one process and one file.
+
+```sh
+npm install -g inillucent
+# or, without installing anything permanently:
+npx inillucent help
+```
+
+No native build step and no postinstall download: the binaries ship as
+per-platform packages that npm installs only where they run, so `npm ci` works
+offline and behind a proxy.
+
+## Four programs
+
+| | |
+|---|---|
+| `inillucent` | the command line: `query`, `exec`, `describe`, `import`, `export`, `search`, and twenty more |
+| `inillucent-shell` | an interactive shell shaped like `sqlite3`, with all 63 of its dot commands |
+| `inillucent-mcp` | the same commands served to an AI agent over MCP |
+| `inillucent-migrate` | builds an inillucent database from a SQLite file |
+
+## From a shell
+
+```sh
+inillucent create app.rdb
+inillucent --db app.rdb exec "CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)"
+inillucent --db app.rdb exec "INSERT INTO notes (body) VALUES (?1)" --params '["hello"]'
+inillucent --db app.rdb query "SELECT * FROM notes"
+inillucent --db app.rdb describe notes
+inillucent help
+```
+
+Exit codes carry meaning: `0` success, `1` failed, `2` a command line nobody
+could act on, and **`3` a construct the engine has not built yet** — so a script
+can branch on "not yet" without matching on a message.
+
+## From Node
+
+```js
+import { query, inillucent } from 'inillucent';
+
+const rows = await query('SELECT id, body FROM notes WHERE id > ?1', {
+  db: 'app.rdb',
+  params: [3],
+});
+// [{ id: 4, body: 'hello' }]
+
+const described = await inillucent('describe', { db: 'app.rdb', table: 'notes' });
+console.log(described.ddl, described.indexes, described.row_count_in_table);
+```
+
+Each call is a process, so this is the right tool for the dozen calls a build
+script or a tool wrapper makes and the wrong one for a loop over a million rows.
+For that, write a binding over the C ABI — the header ships in this package's
+platform dependency under `include/`, and
+[`drivers/README.md`](https://github.com/Black-Rainbow-Labs/Inillucent/blob/main/drivers/README.md)
+is written to be followed.
+
+## For an agent
+
+```json
+{
+  "mcpServers": {
+    "inillucent": {
+      "command": "npx",
+      "args": ["-y", "inillucent-mcp", "--db", "app.rdb"]
+    }
+  }
+}
+```
+
+27 tools, generated from the same command table the CLI reads, so the two can
+never drift. `--readonly` refuses every statement that changes something, and
+`--root DIR` refuses every path outside a directory.
+
+## Licence
+
+MIT. Source: <https://github.com/Black-Rainbow-Labs/Inillucent>
+
+## The API
+
+Every method this binding has. The worked example each one appears in is the link; nothing here is
+a summary of a method that does not exist, because
+`cargo test -p inillucent-compat --test documentation` reads this table and fails on a name the
+binding source does not declare.
+
+| what | one line |
+|---|---|
+| `inillucent(command, options)` | run one command of the command line and return its parsed JSON. `options.db` names the file, `options.args` the rest. |
+| `query(sql, options)` | run one `SELECT` and return its rows. `options.params` binds `?1`, `?2`; `options.limit` caps the rows kept. |
+| `resolveBinary(program)` | the path to one of the four programs on this platform, from the platform package npm installed. |
+| `platformPackage()` | the name of the platform package this machine needs, which is what an install failure should name. |
+| `PROGRAMS` | the four programs and what each is for, as an object. |
+
+Every call goes through the command line rather than through the C ABI: the four programs are what
+the platform package ships, and `--output json` is the same object every other binding sees. That
+is why there is no `Connection` here and no transaction - a command is one process, and a
+transaction that spanned two of them would be a transaction nothing held open.

package/bin/inillucent-mcp.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// The `inillucent-mcp` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent-mcp');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/inillucent-migrate.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// The `inillucent-migrate` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent-migrate');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/inillucent-shell.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// The `inillucent-shell` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent-shell');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/bin/inillucent.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// The `inillucent` shim: resolve the platform binary and become it.
+//
+// `spawn` with `stdio: 'inherit'` rather than an exec, because Node has no
+// execve and this has to work on Windows. The child's exit code and its signal
+// are both passed back up: a wrapper that always exited 0 would break every
+// script that branches on the exit code, and inillucent's exit codes carry
+// meaning - 3 is "the engine has not built that".
+import { spawn } from 'node:child_process';
+import { resolveBinary } from '../resolve.mjs';
+
+let binary;
+try {
+  binary = resolveBinary('inillucent');
+} catch (why) {
+  process.stderr.write(String(why.message ?? why) + '\n');
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+child.on('error', (why) => {
+  process.stderr.write(`inillucent: could not run ${binary}: ${why.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise it on ourselves so a shell sees the same thing it would have
+    // seen from the real program, rather than a plain exit.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/index.mjs

@@ -0,0 +1,197 @@
+// inillucent, from Node.
+//
+// **This is not a database binding.** It is the four programs, plus one
+// convenience for calling the command line and getting a typed result back.
+// A real binding would go through the C ABI in
+// `drivers/inillucent-driver-capi/include/inillucent_driver.h` with koffi or an
+// N-API addon, and `drivers/README.md` says exactly how to write one - it is a
+// worthwhile thing to have and it is not this.
+//
+// What this is for: a script or an agent harness that wants to run a query
+// without shelling out by hand and parsing a table. Each call is a process, so
+// it is the wrong tool for a loop over a million rows and the right one for the
+// dozen calls a build script or a tool wrapper makes.
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { resolveBinary, PROGRAMS, platformPackage } from './resolve.mjs';
+
+const run = promisify(execFile);
+
+/**
+ * Encodes one bound value as the JSON text the command line reads.
+ *
+ * **`JSON.stringify` loses three things a parameter can be (task-1979, D13 and
+ * D16).** A NaN and an Infinity both become `null`, so a REAL column silently
+ * stored NULL and nothing said so; `-0` becomes `0`, so the sign of negative
+ * zero was gone before the value left Node; and a byte string has no JSON form
+ * at all, so there was no way to bind a BLOB.
+ *
+ * What is written instead: a non-finite number throws here, where the caller
+ * can see which value it was, rather than turning into a NULL nobody asked for.
+ * Negative zero is written `-0.0`, which JSON's own grammar carries and the
+ * command line's parser reads back as a negative zero. Bytes are written
+ * `{"blob":"<hex>"}`.
+ *
+ * @param value - one element of `params`
+ */
+function encodeParam(value) {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        `a parameter cannot be ${value}: SQL has no spelling for NaN or Infinity.`,
+      );
+    }
+    return Object.is(value, -0) ? '-0.0' : JSON.stringify(value);
+  }
+  if (value instanceof Uint8Array) {
+    const hex = Buffer.from(value).toString('hex');
+    return JSON.stringify({ blob: hex });
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(encodeParam).join(',')}]`;
+  }
+  return JSON.stringify(value === undefined ? null : value);
+}
+
+/**
+ * Encodes the whole `params` array as JSON text.
+ *
+ * @param values - the bound values, in order
+ */
+function encodeParams(values) {
+  return `[${values.map(encodeParam).join(',')}]`;
+}
+
+export { resolveBinary, PROGRAMS, platformPackage };
+
+/**
+ * Runs a program, writing `stdin` to it when there is any.
+ *
+ * `execFile` cannot write to standard input, so a call that has something to
+ * write goes through `spawn` and the two are answered the same way: `{ stdout,
+ * stderr }`, or a rejection carrying both plus the exit code, which is the
+ * shape the caller below already handles.
+ *
+ * @param binary - the program to run
+ * @param args - its command line
+ * @param stdin - what to write to its standard input, or null
+ */
+async function spawnWith(binary, args, stdin) {
+  if (stdin === null) {
+    return run(binary, args, { maxBuffer: 256 * 1024 * 1024 });
+  }
+  const { spawn } = await import('node:child_process');
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      const why = new Error(`inillucent exited ${code}`);
+      why.stdout = stdout;
+      why.stderr = stderr;
+      why.code = code;
+      reject(why);
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(stdin);
+  });
+}
+
+/**
+ * Runs one inillucent command and returns its result object.
+ *
+ * The command line's `--output json` contract: `{ ok, command, columns, rows,
+ * total, more, changes, last_insert_rowid, elapsed_ms, text }` on success, and
+ * `{ ok: false, status, message, ... }` on failure. `status` is one of the
+ * driver's thirteen names, and `unsupported` is its own - a construct the
+ * engine has not built is not a syntax error and should not be handled as one.
+ *
+ * A failure is returned rather than thrown, because the interesting failures
+ * here are answers: "no such table", "this construct is not built yet". Only a
+ * broken invocation throws.
+ *
+ * @param command - the verb, such as "query" or "describe"
+ * @param options - the named arguments the verb takes, plus `db`
+ */
+export async function inillucent(command, options = {}) {
+  const { db, ...rest } = options;
+  const args = [command, '--output', 'json'];
+  let stdin = null;
+  if (db) {
+    args.push('--db', db);
+  }
+  for (const [name, value] of Object.entries(rest)) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+    if (value === true) {
+      args.push(`--${name}`);
+      continue;
+    }
+    if (value === false) {
+      continue;
+    }
+    // **`params` travels on standard input (task-1979, D17).** A command line
+    // has a length ceiling - about 32 KB on Windows - and a parameter past it
+    // failed with an operating system error rather than with anything about
+    // SQL. `--params-file -` has no such limit, and it is also what lets the
+    // encoding above carry bytes and a negative zero.
+    if (name === 'params' && Array.isArray(value)) {
+      stdin = encodeParams(value);
+      args.push('--params-file', '-');
+      continue;
+    }
+    // Any other array is a JSON argument - `vector` is the one - and the
+    // command line reads it as JSON, so it is serialised rather than joined.
+    args.push(`--${name}`, Array.isArray(value) ? JSON.stringify(value) : String(value));
+  }
+  const binary = resolveBinary('inillucent');
+  try {
+    const { stdout } = await spawnWith(binary, args, stdin);
+    return JSON.parse(stdout);
+  } catch (why) {
+    // A non-zero exit still prints the result object on standard output when
+    // `--output json` was asked for, so the failure the caller wants is in
+    // there. Only a truly broken invocation has nothing to parse.
+    if (typeof why.stdout === 'string' && why.stdout.trim().startsWith('{')) {
+      return JSON.parse(why.stdout);
+    }
+    throw new Error(
+      `inillucent ${command} could not be run: ${why.stderr || why.message}`,
+    );
+  }
+}
+
+/**
+ * Runs a query and returns its rows as objects keyed by column name.
+ *
+ * The shape most callers actually want. `inillucent()` is there for the ones
+ * that need the counts, the timing or the failure class.
+ *
+ * @param sql - the statement
+ * @param options - `db`, `params`, `limit`
+ */
+export async function query(sql, options = {}) {
+  const result = await inillucent('query', { sql, ...options });
+  if (!result.ok) {
+    const error = new Error(result.message);
+    error.status = result.status;
+    error.feature = result.feature;
+    throw error;
+  }
+  const names = result.columns.map((column) => column.name);
+  return result.rows.map((row) => Object.fromEntries(names.map((name, at) => [name, row[at]])));
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "inillucent",
+  "version": "0.1.4",
+  "description": "Embedded SQL database with full-text and vector search, an MCP server, and a sqlite3-shaped shell. No native build step: the binaries ship as platform packages.",
+  "keywords": [
+    "database",
+    "sql",
+    "sqlite",
+    "vector",
+    "embedding",
+    "search",
+    "mcp",
+    "cli",
+    "rag"
+  ],
+  "homepage": "https://github.com/Black-Rainbow-Labs/Inillucent#readme",
+  "bugs": "https://github.com/Black-Rainbow-Labs/Inillucent/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Black-Rainbow-Labs/Inillucent.git",
+    "directory": "packages/npm/inillucent"
+  },
+  "license": "MIT",
+  "author": "Black Rainbow Labs",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "inillucent": "bin/inillucent.mjs",
+    "inillucent-shell": "bin/inillucent-shell.mjs",
+    "inillucent-mcp": "bin/inillucent-mcp.mjs",
+    "inillucent-migrate": "bin/inillucent-migrate.mjs"
+  },
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": [
+    "bin",
+    "index.mjs",
+    "resolve.mjs",
+    "README.md"
+  ],
+  "optionalDependencies": {
+    "@blackrainbowlabs/cli-win32-x64": "0.1.4",
+    "@blackrainbowlabs/cli-darwin-arm64": "0.1.4",
+    "@blackrainbowlabs/cli-darwin-x64": "0.1.4",
+    "@blackrainbowlabs/cli-linux-x64": "0.1.4",
+    "@blackrainbowlabs/cli-linux-arm64": "0.1.4"
+  }
+}

package/resolve.mjs

@@ -0,0 +1,114 @@
+// Finds the binary for the machine this is running on.
+//
+// The arrangement is esbuild's, and it is the right one: the binaries live in
+// per-platform packages listed as `optionalDependencies`, npm installs only the
+// one that matches, and this package's `bin` entries are tiny shims that
+// resolve it and hand over. There is no postinstall script and nothing is
+// downloaded at install time, which means `npm ci` works offline, in a locked
+// CI, and behind a registry proxy - none of which is true of a package that
+// fetches a binary from GitHub when it is installed.
+//
+// The cost is that a platform without a published package cannot install, and
+// the failure has to say so in a sentence somebody can act on rather than as an
+// unresolved import. That is what `resolveBinary` is for.
+
+import { createRequire } from 'node:module';
+import { accessSync, constants, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+/** The platform packages, by the `process.platform`-`process.arch` pair each serves. */
+const PACKAGES = {
+  'win32-x64': '@inillucent/cli-win32-x64',
+  'darwin-arm64': '@inillucent/cli-darwin-arm64',
+  'darwin-x64': '@inillucent/cli-darwin-x64',
+  'linux-x64': '@inillucent/cli-linux-x64',
+  'linux-arm64': '@inillucent/cli-linux-arm64',
+};
+
+/** The four programs the release ships, and what each one is for. */
+export const PROGRAMS = {
+  inillucent: 'the command line: query, exec, describe, import, export, search',
+  'inillucent-shell': 'the interactive sqlite3-shaped shell',
+  'inillucent-mcp': 'the MCP server, for an agent',
+  'inillucent-migrate': 'builds an inillucent database from a SQLite file',
+};
+
+/**
+ * Returns the platform package name for this machine, or null if there is none.
+ */
+export function platformPackage() {
+  return PACKAGES[`${process.platform}-${process.arch}`] ?? null;
+}
+
+/**
+ * Returns the absolute path of one of the four programs on this machine.
+ *
+ * @param program - which program, as it is named in PROGRAMS
+ */
+export function resolveBinary(program) {
+  if (!(program in PROGRAMS)) {
+    throw new Error(`inillucent has no program called ${program}`);
+  }
+  // **`INILLUCENT_BIN` wins, the way it already does for the Go and PHP
+  // wrappers (task-1969, 4.5).** It names the `inillucent` binary; the others
+  // are looked for beside it, which is where a build and an install both put
+  // them. Without this the wrappers stage of `tools/validate` could point the
+  // other two languages at a freshly built binary and had no way to point this
+  // one, so the only npm test that could run was the one that reads the
+  // platform table as text.
+  //
+  // It throws rather than falling through when the named binary is not there:
+  // a caller who says where the binary is and is wrong wants to know, not to
+  // have the resolver quietly go looking somewhere else.
+  const named = process.env.INILLUCENT_BIN;
+  if (named) {
+    const suffix = process.platform === 'win32' ? '.exe' : '';
+    const beside = program === 'inillucent'
+      ? named
+      : join(dirname(named), `${program}${suffix}`);
+    if (!existsSync(beside)) {
+      throw new Error(
+        `INILLUCENT_BIN is set and ${beside} is not there.
+` +
+          `  Unset INILLUCENT_BIN to look for an installed copy instead.`,
+      );
+    }
+    return beside;
+  }
+  const name = platformPackage();
+  if (!name) {
+    throw new Error(
+      `inillucent has no prebuilt binary for ${process.platform}-${process.arch}.\n` +
+        `  Build it from source instead:  cargo install inillucent-cli\n` +
+        `  Or open an issue: https://github.com/Black-Rainbow-Labs/Inillucent/issues`,
+    );
+  }
+  const suffix = process.platform === 'win32' ? '.exe' : '';
+  let path;
+  try {
+    // The platform package's own entry point tells us where its bin directory
+    // is, rather than this package guessing at a node_modules layout - which
+    // pnpm, yarn's pnp and a hoisted npm tree all arrange differently.
+    path = require.resolve(`${name}/bin/${program}${suffix}`);
+  } catch {
+    throw new Error(
+      `inillucent's binary for ${process.platform}-${process.arch} is not installed.\n` +
+        `  The package ${name} should have been installed as an optional dependency.\n` +
+        `  If your installer was run with --no-optional, install it directly:\n` +
+        `    npm install ${name}\n`,
+    );
+  }
+  try {
+    accessSync(path, constants.X_OK);
+  } catch {
+    // An npm tarball does not always preserve the executable bit, and the
+    // failure it produces otherwise is EACCES from execve with no explanation.
+    throw new Error(
+      `${path} is not executable.\n  Fix it with:  chmod +x ${path}\n` +
+        `  Then please report it: https://github.com/Black-Rainbow-Labs/Inillucent/issues`,
+    );
+  }
+  return path;
+}