rubien-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,180 @@
+# rubien-mcp-server
+
+A Model Context Protocol server that wraps `rubien-cli`, making the Rubien reference library available to Claude Code, Claude Desktop, and claude.ai chat as a callable tool catalog.
+
+The server is a thin Node/TypeScript process. It spawns `rubien-cli` under the hood and speaks MCP over one of two transports:
+
+- **stdio** — used by **Claude Code** and **Claude Desktop**. The client launches the server as a child process and talks to it over the pipe. No network, no auth.
+- **Streamable HTTP with bearer-token auth** — used by **claude.ai (web)** via a custom MCP connector. Requires a tunnel (e.g. Cloudflare Tunnel) because your library lives on your Mac.
+
+Pick the section below that matches your client. Most users want one of the two stdio paths.
+
+## Install (Claude Code)
+
+```bash
+claude mcp add rubien -- npx -y rubien-mcp-server
+```
+
+This needs `rubien-cli` on the host:
+- **Mac:** install Rubien.app (DMG) — the entitled `rubien-cli` ships inside it; nothing else to do.
+- **Linux:** `sudo apt install libsqlite3-0 libcurl4 libxml2 libpoppler-glib8 libcairo2 libgdk-pixbuf-2.0-0 libglib2.0-0 ca-certificates`, then download `rubien-cli-*-linux-x86_64.tar.gz` from
+  https://github.com/devzhk/Rubien-releases/releases and **extract it to a directory, keeping `rubien-cli` and the `*.resources` folders together** (the CLI loads citation styles from beside the binary). Point the server at it: `export RUBIEN_CLI=/path/to/extracted/rubien-cli`. Do **not** copy the bare binary onto `PATH` alone — it would lose its resource bundles.
+
+The server checks the CLI's build at startup; if it's too old it prints an update
+instruction and exits (rather than failing mid-call). On **Mac**, update Rubien.app
+(Sparkle). On **Linux**, run `rubien-cli self-update` (signature-verified, replaces in
+place) — or re-download the tarball.
+
+## Prerequisites
+
+- Node.js ≥ 20
+- `rubien-cli` reachable on the host. The server looks for it in this order:
+  1. `$RUBIEN_CLI` env var (explicit path)
+  2. `/Applications/Rubien.app/Contents/Helpers/rubien-cli` (installed app bundle, Mac)
+  3. `~/Applications/Rubien.app/Contents/Helpers/rubien-cli` (Mac)
+  4. `./build/Rubien.app/Contents/Helpers/rubien-cli` (dev build output, Mac)
+  5. `rubien-cli` on `PATH` (Linux installs land here — see the **Install** section above)
+
+**On Mac, prefer the bundled helper.** It's signed with the App Group entitlement and reads the same `library.sqlite` the Rubien app uses. A bare `rubien-cli` on PATH is typically an SPM dev build without the entitlement, which hits a *different* database — see "Database location" in `Docs/CLI-Reference.md`.
+
+**On Linux**, the server runs against a `rubien-cli` installed per the **Install** section above (prebuilt Linux tarball, or built from source). Everything works except `rubien_sync_status`, which always errors (`sync` subcommand isn't registered on Linux builds — CloudKit doesn't exist there).
+
+To pin the spawned CLI to a specific library directory regardless of which binary resolves, set `RUBIEN_LIBRARY_ROOT` in the MCP server's `env` block (Claude Code: `claude mcp add rubien --env RUBIEN_LIBRARY_ROOT=...`; Claude Desktop: under `mcpServers.rubien.env` in `claude_desktop_config.json`). The path is used verbatim — point it at the directory that contains `library.sqlite`:
+
+- Mac sandboxed: `~/Library/Group Containers/9TXK4V3SS8.com.rubien.shared/Rubien`
+- Mac unsandboxed: `~/Library/Application Support/Rubien`
+- Linux: `~/.local/share/rubien` (or wherever `$XDG_DATA_HOME/rubien` resolved to)
+
+## Claude Code (stdio)
+
+The npx command above is the recommended path. To run a local checkout instead (see [Development](#development) for the build):
+
+```bash
+claude mcp add rubien node $(pwd)/dist/index.js
+```
+
+Try it:
+
+> List my 5 most recently added references.
+> Cite reference 42 in Nature style.
+
+Claude Code's permission UI prompts for the destructive tools (`rubien_delete`, `rubien_update`, `rubien_import`, and the property write tools) on first use.
+
+## Claude Desktop (stdio)
+
+Claude Desktop spawns MCP servers itself — no tunnel, no bearer token. Add Rubien to `claude_desktop_config.json` via either route:
+
+- **Edit the file directly** at `~/Library/Application Support/Claude/claude_desktop_config.json`.
+- **Settings → Developer → Edit Config** in Claude Desktop, which opens the same file in your editor.
+
+Add Rubien under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "rubien": {
+      "command": "node",
+      "args": ["/absolute/path/to/Rubien/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop and Rubien appears in the tool picker. To pin the spawned CLI to a specific library (see *Prerequisites* above for paths), add an `env` block:
+
+```json
+"rubien": {
+  "command": "node",
+  "args": ["/absolute/path/to/Rubien/mcp-server/dist/index.js"],
+  "env": {
+    "RUBIEN_LIBRARY_ROOT": "/Users/you/Library/Group Containers/9TXK4V3SS8.com.rubien.shared/Rubien"
+  }
+}
+```
+
+> **Future work — Desktop Extension (`.dxt`).** Claude Desktop also supports one-click MCP installs via `.dxt` packages (a zip containing a `manifest.json` + bundled server). Rubien doesn't ship one yet; packaging it would replace the config-file edit above with a double-click install from a GitHub Release asset.
+
+## claude.ai web (Streamable HTTP + Cloudflare Tunnel)
+
+claude.ai (the web app at https://claude.ai) can't spawn a local process, so it talks to the server over HTTPS via a custom MCP connector. Since your library lives on your Mac, you'll need a tunnel to expose the local server, and bearer-token auth to keep strangers out.
+
+```bash
+# 1. Start the server with a bearer token
+RUBIEN_MCP_BEARER=$(openssl rand -hex 32) \
+  node dist/index.js --http --port 4000 --bearer-token "$RUBIEN_MCP_BEARER"
+
+# 2. Open a tunnel
+cloudflared tunnel --url http://localhost:4000
+# → copy the https://*.trycloudflare.com URL
+
+# 3. In claude.ai: Settings → Connectors → Add custom MCP connector
+#    URL:   https://<your-tunnel>.trycloudflare.com
+#    Token: $RUBIEN_MCP_BEARER (from step 1)
+```
+
+Save the bearer token — you'll need it to reconnect after restarts.
+
+## Security model
+
+This server is designed for **single-user personal use** only.
+
+- The bearer token is a long-lived static secret. There's no rotation, revocation, rate limiting, or replay protection.
+- The server will happily accept any request with the correct token. Don't paste the token into anything you don't trust, and treat a leaked token like an SSH key — regenerate immediately.
+- Cloudflare Tunnel provides TLS termination; the token travels over HTTPS. If you use a plaintext tunnel (e.g. raw ngrok HTTP) the token can be sniffed.
+- A leaked URL without the token is safe — every request gets a 401 — but rotate both if in doubt.
+
+If this setup ever becomes multi-user, the auth layer needs a real story: OAuth, short-lived tokens, and per-client revocation.
+
+## Tool catalog
+
+Roughly 36 tools covering every `rubien-cli` subcommand mode. Names are `rubien_<subject>_<action>` so Claude can pick the right tool from a single-word hint:
+
+| Surface | Tools |
+|---|---|
+| References | `rubien_search`, `rubien_list`, `rubien_get`, `rubien_add`, `rubien_update`, `rubien_delete` |
+| Citations | `rubien_cite`, `rubien_styles_list` |
+| Import/Export | `rubien_import`, `rubien_export` |
+| PDFs | `rubien_pdf_info`, `rubien_pdf_text`, `rubien_pdf_page_image`, `rubien_pdf_download`, `rubien_annotations_list` |
+| Web clips | `rubien_web_get`, `rubien_web_annotations` |
+| Properties (incl. Tags) | `rubien_properties_list`, `rubien_properties_create`, `rubien_properties_delete`, `rubien_properties_rename`, `rubien_properties_show`, `rubien_properties_hide`, `rubien_properties_add_option`, `rubien_properties_rename_option`, `rubien_properties_delete_option`, `rubien_properties_set`, `rubien_properties_add_values`, `rubien_properties_remove_values`, `rubien_properties_clear` |
+| Saved views | `rubien_views_list`, `rubien_views_create`, `rubien_views_delete`, `rubien_views_rename`, `rubien_views_query` |
+| Sync | `rubien_sync_status` (Mac-only — errors on Linux hosts) |
+
+The PDF tools cover inspection and acquisition — `rubien_pdf_info` returns page count plus a flattened outline, `rubien_pdf_text` extracts text by page range or section title, `rubien_pdf_page_image` renders a page to PNG for figure inspection, and `rubien_pdf_download` fetches an open-access PDF for an existing reference and attaches it to the library. `rubien_annotations_list` returns the user's highlights/underlines/anchored-notes on the attached PDF.
+
+The web-clip tools are the counterpart for clipped web pages — `rubien_web_get` returns the extracted body (markdown or HTML, paginated by character offset) along with `siteName` and `annotationCount`, and `rubien_web_annotations` returns highlights with a W3C TextQuoteSelector triple (`prefixText` / `anchorText` / `suffixText`) so the highlight can be located inside the body. Library-only — neither tool fetches from the network.
+
+Destructive tools are tagged with `destructiveHint: true` so Claude Code's permission UI flags them. `rubien_delete` always passes `--force` — the confirmation happens in the MCP client permission UI, not in the CLI's TTY prompt. See the comment in `src/tools/references.ts` for rationale.
+
+## Contract pinning
+
+Every tool's argument shape is defined in zod in the tool file; the expected *response* shape is in `src/schemas.ts`, mirroring the Swift DTOs in `Sources/RubienCLI/RubienCLI.swift` (search for `*DTO`). Crucial convention (see tests in `test/schemas.test.ts`):
+
+- `.optional()` in zod for Swift `Optional` fields — Swift's `JSONEncoder` **omits** nil optionals from output.
+- `.nullable()` only for `AlwaysEncodedOptional<T>` wrappers (currently just `DatabaseViewDTO.groupBy`).
+
+If a Swift DTO changes, update both the Swift side and `src/schemas.ts` in the same commit, per the CLAUDE.md rule about keeping the CLI and data layer in lockstep.
+
+## Development
+
+Build from a local checkout (instead of `npx`):
+
+```bash
+cd mcp-server
+npm install
+npm run build         # → dist/
+npm test              # vitest unit tests
+```
+
+Watch mode:
+
+```bash
+npm run dev       # tsc --watch
+npm run test:watch
+```
+
+MCP Inspector is the fastest way to poke at tool schemas by hand:
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```

package/dist/auth.js

@@ -0,0 +1,36 @@
+/**
+ * Constant-time string comparison. Avoids timing leaks on token verification.
+ */
+function safeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
+/**
+ * Validate Authorization header against the configured bearer token.
+ * Writes a 401 to the response and returns false on mismatch.
+ *
+ * Single-user personal use model: the token is a long-lived static secret
+ * provided via CLI flag / env var. No rotation or revocation. See
+ * README.md → Security model for the full threat model.
+ */
+export function requireBearer(req, res, expectedToken) {
+    const header = req.headers["authorization"];
+    if (typeof header !== "string" || !header.startsWith("Bearer ")) {
+        res.writeHead(401, { "WWW-Authenticate": "Bearer realm=\"rubien-mcp\"" });
+        res.end('{"error":"missing or malformed Authorization header"}');
+        return false;
+    }
+    const token = header.slice("Bearer ".length).trim();
+    if (!safeEqual(token, expectedToken)) {
+        res.writeHead(401, { "WWW-Authenticate": "Bearer realm=\"rubien-mcp\"" });
+        res.end('{"error":"invalid bearer token"}');
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,SAAS,SAAS,CAAC,CAAS,EAAE,CAAS;IACrC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAoB,EACpB,GAAmB,EACnB,aAAqB;IAErB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5C,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,CAAC,CAAC;QAC1E,GAAG,CAAC,GAAG,CAAC,uDAAuD,CAAC,CAAC;QACjE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,CAAC;QACrC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,CAAC,CAAC;QAC1E,GAAG,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cli.js

@@ -0,0 +1,140 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_BUFFER = 32 * 1024 * 1024;
+export class CliError extends Error {
+    exitCode;
+    stderr;
+    constructor(message, exitCode, stderr) {
+        super(message);
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = "CliError";
+    }
+}
+/**
+ * Resolve the rubien-cli binary path, preferring the App-Group-entitled
+ * embedded helper over any PATH-installed binary. A PATH CLI is usually an
+ * unsigned SPM dev build that would hit a different library.sqlite than the
+ * signed app.
+ */
+export function resolveCliPath() {
+    const envOverride = process.env.RUBIEN_CLI;
+    if (envOverride && envOverride.length > 0) {
+        // Validate the env-pointed path so a stale value fails early with a
+        // clear error rather than deep inside execFile.
+        if (!existsSync(envOverride)) {
+            throw new Error(`RUBIEN_CLI points at a path that does not exist: ${envOverride}`);
+        }
+        return envOverride;
+    }
+    const candidates = [
+        "/Applications/Rubien.app/Contents/Helpers/rubien-cli",
+        join(homedir(), "Applications/Rubien.app/Contents/Helpers/rubien-cli"),
+        // Dev path, matching scripts/build-app.sh output.
+        join(process.cwd(), "build/Rubien.app/Contents/Helpers/rubien-cli"),
+        join(process.cwd(), "../build/Rubien.app/Contents/Helpers/rubien-cli"),
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return p;
+    }
+    // Fallback: `rubien-cli` on PATH. Last resort only — typically points at a
+    // dev SPM build without the App Group entitlement, which would read a
+    // different library.sqlite than the signed app.
+    return "rubien-cli";
+}
+/**
+ * Invoke rubien-cli with the given argv and return the parsed result.
+ *
+ * Contract: on exit 0, stdout is JSON (default) or plain text (`textMode`).
+ * On non-zero exit, stderr is `{"error": "..."}` per the contract pinned in
+ * Tests/RubienCLITests/SwiftLibCLITests.swift:189; this function throws a
+ * CliError with that message.
+ */
+export async function invokeCli(args, options = {}) {
+    const cliPath = resolveCliPath();
+    const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    try {
+        const child = execFileAsync(cliPath, args, {
+            timeout,
+            maxBuffer: DEFAULT_MAX_BUFFER,
+        });
+        // Close stdin unconditionally. Even when we have nothing to pipe, leaving
+        // it open causes subcommands that call `readDataToEndOfFile()` (like
+        // `import -`) to block until the timeout fires.
+        if (child.child.stdin) {
+            if (options.stdin !== undefined) {
+                child.child.stdin.write(options.stdin);
+            }
+            child.child.stdin.end();
+        }
+        const { stdout } = await child;
+        if (options.textMode) {
+            return { format: extractFormat(args), text: stdout };
+        }
+        const trimmed = stdout.trim();
+        if (trimmed.length === 0)
+            return null;
+        return JSON.parse(trimmed);
+    }
+    catch (err) {
+        // execFile error shape: { code, signal, stdout, stderr, message }
+        const e = err;
+        const stderr = (e.stderr ?? "").trim();
+        let parsedError;
+        if (stderr.length > 0) {
+            try {
+                const parsed = JSON.parse(stderr);
+                if (parsed && typeof parsed === "object" && "error" in parsed) {
+                    parsedError = String(parsed.error);
+                }
+            }
+            catch {
+                // stderr wasn't JSON; fall through and use raw text.
+            }
+        }
+        const message = parsedError ??
+            (stderr.length > 0 ? stderr : (e.message ?? "rubien-cli invocation failed"));
+        throw new CliError(message, typeof e.code === "number" ? e.code : null, stderr);
+    }
+}
+function extractFormat(args) {
+    const idx = args.indexOf("--format");
+    if (idx >= 0 && idx + 1 < args.length)
+        return args[idx + 1];
+    const idxShort = args.indexOf("-f");
+    if (idxShort >= 0 && idxShort + 1 < args.length)
+        return args[idxShort + 1];
+    return "text";
+}
+/** Convenience: invoke and cast to a specific type. Caller is responsible
+ *  for schema validation (use zod `.parse` at the call site). */
+export async function invokeCliTyped(args, options = {}) {
+    return (await invokeCli(args, options));
+}
+/**
+ * Probe `rubien-cli version` with a short timeout. Returns the parsed
+ * {version, build} or null on any failure (missing subcommand on an old CLI,
+ * non-zero exit, malformed output, timeout). Never throws.
+ */
+export async function getCliVersion() {
+    try {
+        const result = await invokeCli(["version"], { timeoutMs: 5_000 });
+        if (result &&
+            typeof result === "object" &&
+            typeof result.version === "string" &&
+            typeof result.build === "number") {
+            return result;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}