@urna/cli 0.5.0

package/README.md

@@ -0,0 +1,281 @@
+![urna: offline-first vector database, rust and python](https://raw.githubusercontent.com/hoffresearch/urna/main/assets/images/urna-hoff-research-db-iage-thumb-git.png)
+
+# Urna
+
+A vector database in one file, with citations that stay valid.
+
+A `.urna` file holds the chunks, the embeddings, the source spans, the indices and the search contract. The rust runtime maps it into memory, checks its hashes, and answers with exact cosine scores and a `urna://content_hash/chunk_id` citation for every hit. It works offline and rebuilds byte for byte. Python builds the file, rust serves it.
+
+## Install
+
+```sh
+brew install hoffresearch/urna/urna
+```
+
+```sh
+npm install -g urna
+```
+
+```sh
+cargo install urna
+```
+
+```sh
+curl -sSf https://raw.githubusercontent.com/hoffresearch/urna/main/scripts/install.sh | sh
+```
+
+Then run setup once. It downloads the offline embedder, prepares a python env and checks the install:
+
+```sh
+urna setup
+```
+
+Python only, no setup step needed:
+
+```sh
+pip install "urna[embed]"
+```
+
+Windows, docker, `cargo binstall` and how to verify a download are in the [install reference](https://github.com/hoffresearch/urna/blob/main/docs/usage.md#reference).
+
+## In the terminal
+
+`urna setup` shows the plan before it writes anything and ends on the doctor checks.
+
+<img src="https://raw.githubusercontent.com/hoffresearch/urna/main/assets/images/urna-setup.png" alt="urna setup: the verify step with every doctor check passing" width="100%">
+
+`urna tui` opens a corpus, validates it, and lets you ask it questions. Each hit shows its score, the stored text and its citation.
+
+```sh
+urna tui my_corpus.urna
+```
+
+<img src="https://raw.githubusercontent.com/hoffresearch/urna/main/assets/images/urna-tui.png" alt="urna tui: the ask tab with scored hits and the cited text of the selected one" width="100%">
+
+## Quickstart
+
+`examples/quickstart/` has twelve short paragraphs and the spec that builds them. From a checkout:
+
+```sh
+urna build --spec examples/quickstart/corpus.toml
+```
+
+```sh
+urna ask examples/quickstart/out/quickstart.urna "can I use this offline" -k 1
+```
+
+```sh
+urna retrieve examples/quickstart/out/quickstart.urna "how do citations work" -k 2 --format jsonl
+```
+
+```sh
+urna cite examples/quickstart/out/quickstart.urna 'urna://sha256:1147b256.../sha256:b5dfeb09...'
+```
+
+```sh
+urna validate examples/quickstart/out/quickstart.urna
+```
+
+`ask` prints the answer with its citation, `retrieve` prints json for another program, `cite` turns a citation back into the stored text, and `validate` checks every hash. To build from your own rows, see [usage section 13](https://github.com/hoffresearch/urna/blob/main/docs/usage.md).
+
+## What the file guarantees
+
+| Property | How |
+|----------|-----|
+| Self-contained | The file is the whole database. Copy it like a sqlite file. |
+| Verifiable | Sha-256 per section, per file and over the decoded content. `urna cite` resolves any citation. |
+| Reproducible | Same chunks and same model give a byte-identical file on any machine. |
+| Offline | The runtime never opens a socket. A query from the wrong model fails at the `model_hash` check. |
+
+## Python
+
+```python
+import urna
+from urna.embed_potion import potion_embedder
+
+emb = potion_embedder()
+db = urna.open("my_corpus.urna")
+qvec = emb.embed_texts(["can I use this offline"])[0]
+
+hits = db.retrieve(qvec, 5, expected_model_hash=emb.model_hash())
+print(hits[0].citation_id, hits[0].score, hits[0].text)
+```
+
+<details>
+<summary>Search variants, validate, build</summary>
+
+```python
+db.search(qvec, 5)                                     # exact
+db.search_ann(qvec, 5, 100)                            # hnsw, then exact rerank
+db.search_hybrid(qvec, "vacina contra covid", 5, 100)  # bm25 + vectors, exact rerank
+db.search_graph(qvec, 5, hops=2, ef=100)               # chunk graph from the seeds
+db.search_space("clip-vit-b32", ivec, 5)               # one named multimodal space
+
+assert db.validate() is True
+info = db.inspect()
+```
+
+Each chunk is a dict with `canonical_text`, `source_uri`, `byte_start`, `byte_end` and `embedding`:
+
+```python
+urna.build(
+    output_path="my_corpus.urna",
+    embedding_model="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+    embedding_dim=384,
+    chunker_version="fixed-512/1",
+    model_hash=model_hash,
+    chunks=chunks,
+    reproducible=True,
+    preset="hybrid",
+)
+```
+
+`python examples/quickstart/quickstart.py` runs the whole loop, build to cited hits, with no network.
+
+</details>
+
+## CLI
+
+The engine verbs take a file and a vector and never run python. The agent verbs (`ask`, `retrieve`, `build`) take text and use the offline embedder. `setup` and `tui` are the terminal ui. `urna --help` lists all three groups.
+
+<details>
+<summary>Agent verbs</summary>
+
+```sh
+urna ask my_corpus.urna "can I use this offline" -k 3
+```
+
+```sh
+urna retrieve my_corpus.urna "can I use this offline" -k 5 --format jsonl
+```
+
+```sh
+urna build --spec corpus.toml --dry-run
+```
+
+`build` reads one toml: the source (sqlite, csv, jsonl, an image dir), the media settings, and one or more embedding models from the registry (`potion`, `clip-vit-b32`, `siglip2`, `wemm-2b`, ...). Each model becomes a named vector space in the same file. The full spec is in [usage section 13](https://github.com/hoffresearch/urna/blob/main/docs/usage.md).
+
+</details>
+
+<details>
+<summary>Search</summary>
+
+```sh
+urna search my_corpus.urna "[0.1, 0.2, ...]" -k 10
+```
+
+```sh
+urna search-ann my_corpus.urna "[0.1, 0.2, ...]" -k 10 --ef 200
+```
+
+```sh
+urna search-graph my_corpus.urna "[0.1, 0.2, ...]" -k 10 --hops 2 --ef 100
+```
+
+```sh
+urna search-space my_corpus.urna "[0.1, ...]" --space "wemm-2b@256" -k 5
+```
+
+```sh
+urna search-text my_corpus.urna "vacina contra covid funciona" -k 5
+```
+
+</details>
+
+<details>
+<summary>Inspect, validate, stats, cite, media, benchmark, doctor</summary>
+
+```sh
+urna inspect my_corpus.urna --json
+```
+
+```sh
+urna validate my_corpus.urna
+```
+
+```sh
+urna stats my_corpus.urna
+```
+
+```sh
+urna cite my_corpus.urna 'urna://sha256:1aa9.../sha256:8f314...'
+```
+
+```sh
+urna media my_corpus.urna --export DIR
+```
+
+```sh
+urna benchmark my_corpus.urna -q 100 -k 10 --ann 100 --madvise-cold
+```
+
+```sh
+urna doctor
+```
+
+</details>
+
+## Benchmarks
+
+100,000 x 384 rows, k=10, one thread, same machine for every store.
+
+| Store | p50 (ms) | p99 (ms) | Cold open (ms) |
+|-------|---------:|---------:|---------------:|
+| hnswlib | 0.32 | 0.53 | 182 |
+| usearch | 0.67 | 61.4 | 58 |
+| urna hybrid | 0.72 | 1.02 | 356 |
+| urna exact | 7.80 | 8.32 | 292 |
+| lancedb | 16.7 | 19.4 | 612 |
+| sqlite-vec | 19.8 | 24.8 | 50 |
+
+Both urna rows return recall@10 = 1.000. Urna's cold open includes checking every section hash before the first answer. Urna does not do updates, filters or concurrent writers. Method and the full table: [docs/benchmarks.md](https://github.com/hoffresearch/urna/blob/main/docs/benchmarks.md).
+
+<details>
+<summary>Presets: size vs recall</summary>
+
+| Preset | Embeddings | Index | Size | Recall@10 |
+|--------|------------|-------|-----:|----------:|
+| `exact` | float32 | | 1.000 | 1.000 |
+| `compressed` | float16 | | 0.339 | 1.000 |
+| `tiny` | int8 | hnsw | 0.256 | 0.992 |
+| `micro` | mrl256-int8 | hnsw | 0.223 | 0.810 |
+| `nano` | int4 | hnsw | 0.209 | 0.913 |
+| `hybrid` | float32 | hnsw + bm25 | 0.609 | 1.000 |
+
+Measured on a 30,725-chunk pt-br corpus. Recall here is rank stability under quantization, not real-query quality. Details in [usage section 6](https://github.com/hoffresearch/urna/blob/main/docs/usage.md).
+
+</details>
+
+<details>
+<summary>Images: 38,627 magic cards in one file</summary>
+
+| Profile | Media | File | Vs the jpeg source |
+|---------|-------|-----:|-------------------:|
+| `archive` | JPEG XL, byte-reversible | 3.61 GB | 1.10x |
+| `stills` | AV1 all-intra crf35 | 1.37 GB | 2.89x |
+| `retrieval` | AV1 all-intra crf50 | 533 MB | 7.46x |
+
+Text-to-image hit@1 over every card: siglip2 0.750, wemm-2b 0.744, jina 0.336, clip 0.098. Code and data: [mtg-urna-benchmark](https://github.com/brennercruvinel/mtg-urna-benchmark).
+
+</details>
+
+## Reference
+
+- [docs/usage.md](https://github.com/hoffresearch/urna/blob/main/docs/usage.md): every verb, presets, models, builds, install channels
+- [docs/benchmarks.md](https://github.com/hoffresearch/urna/blob/main/docs/benchmarks.md): how the numbers were measured
+- [docs/SECURITY.md](https://github.com/hoffresearch/urna/blob/main/docs/SECURITY.md): reporting, hardening, data governance
+- [docs/CHANGELOG](https://github.com/hoffresearch/urna/blob/main/docs/CHANGELOG): releases with measured numbers
+- [docs/arc/arc.toml](https://github.com/hoffresearch/urna/blob/main/docs/arc/arc.toml): the architecture map
+- [AGENTS.md](https://github.com/hoffresearch/urna/blob/main/.contracts/.agents/AGENTS.md): notes for contributors and agents
+
+The crates are `urna-format` (the container), `urna-runtime` (search), `urna` (the binary) and `urna-python` (the bridge).
+
+> Renamed from `nest` after 0.4.0. A `.nest` file written by 0.4.0 still opens.
+
+## License
+
+MIT, see [docs/LICENSE](https://github.com/hoffresearch/urna/blob/main/docs/LICENSE). [Hoff Research](https://hoffresearch.com)
+
+Made it simple, but significant (∂μfμν = jν)
+
+Author: Brenner Cruvinel

package/binary-install.js

@@ -0,0 +1,348 @@
+const {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  mkdtemp,
+  rmSync,
+} = require("fs");
+const { join, sep } = require("path");
+const { spawnSync } = require("child_process");
+const { tmpdir } = require("os");
+
+const https = require("node:https");
+const http = require("node:http");
+
+const tmpDir = tmpdir();
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+function getProxyForUrl(urlString) {
+  const url = new URL(urlString);
+  const isHttps = url.protocol === "https:";
+
+  const noProxy = process.env.NO_PROXY || process.env.no_proxy || "";
+  if (noProxy === "*") return null;
+  if (noProxy) {
+    const hostname = url.hostname.toLowerCase();
+    const noProxyList = noProxy.split(",").map((s) => s.trim().toLowerCase());
+    for (const entry of noProxyList) {
+      if (hostname === entry || hostname.endsWith("." + entry)) {
+        return null;
+      }
+    }
+  }
+
+  const proxyEnv = isHttps
+    ? process.env.HTTPS_PROXY || process.env.https_proxy
+    : process.env.HTTP_PROXY || process.env.http_proxy;
+
+  if (!proxyEnv) return null;
+
+  const proxyUrl = new URL(proxyEnv);
+
+  let auth = null;
+  if (proxyUrl.username || proxyUrl.password) {
+    auth = `${proxyUrl.username}:${proxyUrl.password}`;
+  }
+
+  return {
+    hostname: proxyUrl.hostname,
+    port: proxyUrl.port || (proxyUrl.protocol === "https:" ? 443 : 80),
+    auth: auth,
+  };
+}
+
+function connectThroughProxy(proxy, target) {
+  return new Promise((resolve, reject) => {
+    const headers = {};
+    if (proxy.auth) {
+      headers["Proxy-Authorization"] =
+        "Basic " + Buffer.from(proxy.auth).toString("base64");
+    }
+
+    const connectReq = http.request({
+      hostname: proxy.hostname,
+      port: proxy.port,
+      method: "CONNECT",
+      path: `${target.hostname}:${target.port || 443}`,
+      headers,
+    });
+    connectReq.on("connect", (res, socket) => {
+      if (res.statusCode === 200) {
+        resolve(socket);
+      } else {
+        reject(new Error(`Proxy CONNECT failed with status ${res.statusCode}`));
+      }
+    });
+    connectReq.on("error", reject);
+    connectReq.end();
+  });
+}
+
+function download(urlString, maxRedirects) {
+  if (maxRedirects === undefined) maxRedirects = 5;
+  return new Promise((resolve, reject) => {
+    if (maxRedirects < 0) {
+      return reject(new Error("Too many redirects"));
+    }
+
+    const parsed = new URL(urlString);
+    const isHttps = parsed.protocol === "https:";
+    const mod = isHttps ? https : http;
+    const proxy = getProxyForUrl(urlString);
+
+    const doRequest = (extraOptions) => {
+      const options = Object.assign(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port || (isHttps ? 443 : 80),
+          path: parsed.pathname + parsed.search,
+          method: "GET",
+          headers: { "User-Agent": "cargo-dist-npm-installer" },
+        },
+        extraOptions || {},
+      );
+
+      if (proxy && !isHttps) {
+        // HTTP through HTTP proxy: request the full URL via the proxy
+        options.hostname = proxy.hostname;
+        options.port = proxy.port;
+        options.path = urlString;
+        if (proxy.auth) {
+          options.headers["Proxy-Authorization"] =
+            "Basic " + Buffer.from(proxy.auth).toString("base64");
+        }
+      }
+
+      const req = mod.request(options, (res) => {
+        if (
+          res.statusCode >= 300 &&
+          res.statusCode < 400 &&
+          res.headers.location
+        ) {
+          res.resume();
+          const nextUrl = new URL(res.headers.location, urlString).toString();
+          return download(nextUrl, maxRedirects - 1).then(resolve, reject);
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode} from ${urlString}`));
+        }
+        resolve(res);
+      });
+      req.on("error", reject);
+      req.end();
+    };
+
+    if (proxy && isHttps) {
+      connectThroughProxy(proxy, parsed).then(
+        (socket) => doRequest({ socket, agent: false }),
+        reject,
+      );
+    } else {
+      doRequest();
+    }
+  });
+}
+
+class Package {
+  constructor(platform, name, url, filename, zipExt, binaries) {
+    let errors = [];
+    if (typeof url !== "string") {
+      errors.push("url must be a string");
+    } else {
+      try {
+        new URL(url);
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+    if (name && typeof name !== "string") {
+      errors.push("package name must be a string");
+    }
+    if (!name) {
+      errors.push("You must specify the name of your package");
+    }
+    if (binaries && typeof binaries !== "object") {
+      errors.push("binaries must be a string => string map");
+    }
+    if (!binaries) {
+      errors.push("You must specify the binaries in the package");
+    }
+
+    if (errors.length > 0) {
+      let errorMsg =
+        "One or more of the parameters you passed to the Binary constructor are invalid:\n";
+      errors.forEach((error) => {
+        errorMsg += error;
+      });
+      errorMsg +=
+        '\n\nCorrect usage: new Package("my-binary", "https://example.com/binary/download.tar.gz", {"my-binary": "my-binary"})';
+      error(errorMsg);
+    }
+
+    this.platform = platform;
+    this.url = url;
+    this.name = name;
+    this.filename = filename;
+    this.zipExt = zipExt;
+    this.installDirectory = join(__dirname, "node_modules", ".bin_real");
+    this.binaries = binaries;
+
+    if (!existsSync(this.installDirectory)) {
+      mkdirSync(this.installDirectory, { recursive: true });
+    }
+  }
+
+  exists() {
+    for (const binaryName in this.binaries) {
+      const binRelPath = this.binaries[binaryName];
+      const binPath = join(this.installDirectory, binRelPath);
+      if (!existsSync(binPath)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  install(suppressLogs = false) {
+    if (this.exists()) {
+      if (!suppressLogs) {
+        console.error(
+          `${this.name} is already installed, skipping installation.`,
+        );
+      }
+      return Promise.resolve();
+    }
+
+    try {
+      rmSync(this.installDirectory, { recursive: true, force: true });
+    } catch {
+      // ignore - directory may not exist
+    }
+
+    mkdirSync(this.installDirectory, { recursive: true });
+
+    if (!suppressLogs) {
+      console.error(`Downloading release from ${this.url}`);
+    }
+
+    return download(this.url)
+      .then((res) => {
+        return new Promise((resolve, reject) => {
+          mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
+            if (err) return reject(err);
+            let tempFile = join(directory, this.filename);
+            const sink = res.pipe(createWriteStream(tempFile));
+            sink.on("error", (err) => reject(err));
+            sink.on("close", () => {
+              if (/\.tar\.*/.test(this.zipExt)) {
+                const result = spawnSync("tar", [
+                  "xf",
+                  tempFile,
+                  // The tarballs are stored with a leading directory
+                  // component; we strip one component in the
+                  // shell installers too.
+                  "--strip-components",
+                  "1",
+                  "-C",
+                  this.installDirectory,
+                ]);
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred untarring the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else if (this.zipExt == ".zip") {
+                let result;
+                if (this.platform.artifactName.includes("windows")) {
+                  // Windows does not have "unzip" by default on many installations, instead
+                  // we use Expand-Archive from powershell
+                  result = spawnSync("powershell.exe", [
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-Command",
+                    `& {
+                        param([string]$LiteralPath, [string]$DestinationPath)
+                        Expand-Archive -LiteralPath $LiteralPath -DestinationPath $DestinationPath -Force
+                    }`,
+                    tempFile,
+                    this.installDirectory,
+                  ]);
+                } else {
+                  result = spawnSync("unzip", [
+                    "-q",
+                    tempFile,
+                    "-d",
+                    this.installDirectory,
+                  ]);
+                }
+
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred unzipping the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else {
+                reject(
+                  new Error(`Unrecognized file extension: ${this.zipExt}`),
+                );
+              }
+            });
+          });
+        });
+      })
+      .then(() => {
+        if (!suppressLogs) {
+          console.error(`${this.name} has been installed!`);
+        }
+      })
+      .catch((e) => {
+        error(`Error fetching release: ${e.message}`);
+      });
+  }
+
+  run(binaryName) {
+    const promise = !this.exists() ? this.install(true) : Promise.resolve();
+
+    promise
+      .then(() => {
+        const [, , ...args] = process.argv;
+
+        const options = { cwd: process.cwd(), stdio: "inherit" };
+
+        const binRelPath = this.binaries[binaryName];
+        if (!binRelPath) {
+          error(`${binaryName} is not a known binary in ${this.name}`);
+        }
+        const binPath = join(this.installDirectory, binRelPath);
+        const result = spawnSync(binPath, args, options);
+
+        if (result.error) {
+          error(result.error);
+        }
+
+        process.exit(result.status);
+      })
+      .catch((e) => {
+        error(e.message);
+      });
+  }
+}
+
+module.exports.Package = Package;

package/binary.js

@@ -0,0 +1,124 @@
+const { Package } = require("./binary-install");
+const os = require("os");
+const libc = require("detect-libc");
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+const {
+  name,
+  artifactDownloadUrls,
+  supportedPlatforms,
+  glibcMinimum,
+} = require("./package.json");
+
+// FIXME: implement NPM installer handling of fallback download URLs
+const artifactDownloadUrl = artifactDownloadUrls[0];
+const builderGlibcMajorVersion = glibcMinimum.major;
+const builderGlibcMinorVersion = glibcMinimum.series;
+
+const getPlatform = () => {
+  const rawOsType = os.type();
+  const rawArchitecture = os.arch();
+
+  // We want to use rust-style target triples as the canonical key
+  // for a platform, so translate the "os" library's concepts into rust ones
+  let osType = "";
+  switch (rawOsType) {
+    case "Windows_NT":
+      osType = "pc-windows-msvc";
+      break;
+    case "Darwin":
+      osType = "apple-darwin";
+      break;
+    case "Linux":
+      osType = "unknown-linux-gnu";
+      break;
+  }
+
+  let arch = "";
+  switch (rawArchitecture) {
+    case "x64":
+      arch = "x86_64";
+      break;
+    case "arm64":
+      arch = "aarch64";
+      break;
+  }
+
+  if (rawOsType === "Linux") {
+    if (libc.familySync() == "musl") {
+      osType = "unknown-linux-musl-dynamic";
+    } else if (libc.isNonGlibcLinuxSync()) {
+      console.warn(
+        "Your libc is neither glibc nor musl; trying static musl binary instead",
+      );
+      osType = "unknown-linux-musl-static";
+    } else {
+      let libcVersion = libc.versionSync();
+      let splitLibcVersion = libcVersion.split(".");
+      let libcMajorVersion = splitLibcVersion[0];
+      let libcMinorVersion = splitLibcVersion[1];
+      if (
+        libcMajorVersion != builderGlibcMajorVersion ||
+        libcMinorVersion < builderGlibcMinorVersion
+      ) {
+        // We can't run the glibc binaries, but we can run the static musl ones
+        // if they exist
+        console.warn(
+          "Your glibc isn't compatible; trying static musl binary instead",
+        );
+        osType = "unknown-linux-musl-static";
+      }
+    }
+  }
+
+  // Assume the above succeeded and build a target triple to look things up with.
+  // If any of it failed, this lookup will fail and we'll handle it like normal.
+  let targetTriple = `${arch}-${osType}`;
+  let platform = supportedPlatforms[targetTriple];
+
+  if (!platform) {
+    error(
+      `Platform with type "${rawOsType}" and architecture "${rawArchitecture}" is not supported by ${name}.\nYour system must be one of the following:\n\n${Object.keys(
+        supportedPlatforms,
+      ).join(",")}`,
+    );
+  }
+
+  return platform;
+};
+
+const getPackage = () => {
+  const platform = getPlatform();
+  const url = `${artifactDownloadUrl}/${platform.artifactName}`;
+  let filename = platform.artifactName;
+  let ext = platform.zipExt;
+  let binary = new Package(platform, name, url, filename, ext, platform.bins);
+
+  return binary;
+};
+
+const install = (suppressLogs) => {
+  if (!artifactDownloadUrl || artifactDownloadUrl.length === 0) {
+    console.warn("in demo mode, not installing binaries");
+    return;
+  }
+  const pkg = getPackage();
+
+  return pkg.install(suppressLogs);
+};
+
+const run = (binaryName) => {
+  const pkg = getPackage();
+
+  pkg.run(binaryName);
+};
+
+module.exports = {
+  install,
+  run,
+  getPackage,
+};

package/install.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { install } = require("./binary");
+install(false);

package/npm-shrinkwrap.json

@@ -0,0 +1,52 @@
+{
+  "lockfileVersion": 3,
+  "name": "@urna/cli",
+  "packages": {
+    "": {
+      "bin": {
+        "urna": "run-urna.js"
+      },
+      "dependencies": {
+        "detect-libc": "^2.1.2"
+      },
+      "devDependencies": {
+        "prettier": "^3.8.3"
+      },
+      "engines": {
+        "node": ">=14.14",
+        "npm": ">=6"
+      },
+      "hasInstallScript": true,
+      "license": "MIT",
+      "name": "@urna/cli",
+      "version": "0.5.0"
+    },
+    "node_modules/detect-libc": {
+      "engines": {
+        "node": ">=8"
+      },
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "version": "2.1.2"
+    },
+    "node_modules/prettier": {
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "dev": true,
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      },
+      "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==",
+      "license": "MIT",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.3.tgz",
+      "version": "3.8.3"
+    }
+  },
+  "requires": true,
+  "version": "0.5.0"
+}

package/package.json

@@ -0,0 +1,126 @@
+{
+  "artifactDownloadUrls": [
+    "https://github.com/hoffresearch/urna/releases/download/v0.5.0"
+  ],
+  "bin": {
+    "urna": "run-urna.js"
+  },
+  "dependencies": {
+    "detect-libc": "^2.1.2"
+  },
+  "description": "sovereign embedded vector database: single-file .urna container with content-addressable citations, offline-first",
+  "devDependencies": {
+    "prettier": "^3.8.3"
+  },
+  "engines": {
+    "node": ">=14.14",
+    "npm": ">=6"
+  },
+  "glibcMinimum": {
+    "major": 2,
+    "series": 31
+  },
+  "homepage": "https://urna.dev",
+  "keywords": [
+    "command-line-utilities",
+    "database-implementations",
+    "vector-database",
+    "embeddings",
+    "search",
+    "offline",
+    "citations"
+  ],
+  "license": "MIT",
+  "name": "@urna/cli",
+  "preferUnplugged": true,
+  "repository": "https://github.com/hoffresearch/urna",
+  "scripts": {
+    "fmt": "prettier --write **/*.js",
+    "fmt:check": "prettier --check **/*.js",
+    "postinstall": "node ./install.js"
+  },
+  "supportedPlatforms": {
+    "aarch64-apple-darwin": {
+      "artifactName": "urna-aarch64-apple-darwin.tar.xz",
+      "bins": {
+        "urna": "urna"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-pc-windows-msvc": {
+      "artifactName": "urna-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "urna": "urna.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "aarch64-unknown-linux-gnu": {
+      "artifactName": "urna-aarch64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "urna": "urna"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-unknown-linux-musl-dynamic": {
+      "artifactName": "urna-aarch64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "urna": "urna"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-unknown-linux-musl-static": {
+      "artifactName": "urna-aarch64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "urna": "urna"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-apple-darwin": {
+      "artifactName": "urna-x86_64-apple-darwin.tar.xz",
+      "bins": {
+        "urna": "urna"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-pc-windows-gnu": {
+      "artifactName": "urna-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "urna": "urna.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "x86_64-pc-windows-msvc": {
+      "artifactName": "urna-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "urna": "urna.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "x86_64-unknown-linux-gnu": {
+      "artifactName": "urna-x86_64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "urna": "urna"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-unknown-linux-musl-dynamic": {
+      "artifactName": "urna-x86_64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "urna": "urna"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-unknown-linux-musl-static": {
+      "artifactName": "urna-x86_64-unknown-linux-musl.tar.xz",
+      "bins": {
+        "urna": "urna"
+      },
+      "zipExt": ".tar.xz"
+    }
+  },
+  "version": "0.5.0",
+  "volta": {
+    "node": "18.14.1",
+    "npm": "9.5.0"
+  }
+}

package/run-urna.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { run } = require("./binary");
+run("urna");