nexvora 0.1.0

package/README.md

@@ -0,0 +1,144 @@
+# nexvora
+
+One binary for everything NexVora: the **MCP server**, the **CLI**, and the
+**donor daemon**. One install, one login, different commands.
+
+```bash
+npm install -g nexvora
+```
+
+That is the only install command. The native engine ships inside this package
+(via a per-platform optional dependency); `npm` downloads only the binary for
+your OS/CPU. No second package, no separate daemon to install.
+
+## Quick start
+
+```bash
+npm install -g nexvora
+nexvora "summarise the file at ./report.md"   # first run opens your browser to log in once
+```
+
+For end-to-end-encrypted task results that you can fetch later (and that the
+platform can never read), set an **encryption passphrase** once:
+
+```bash
+nexvora vault setup        # prompts for a passphrase; creates + caches your key
+```
+
+That's it. Everything else is just a different first word.
+
+## One command does each job
+
+```bash
+nexvora "summarise RFC 9110"     # one-shot: run a prompt, get the answer, done
+cat notes.txt | nexvora          # prompt from stdin
+nexvora donor                    # join the donor pool (long-running)
+nexvora mcp                      # MCP server over stdio (for Claude Code / Cursor / etc.)
+nexvora vault setup|unlock|lock  # manage your encryption vault (see below)
+nexvora logout                   # clear local credentials
+nexvora daemon stop              # stop the background user daemon
+```
+
+You never run a separate `login` step. The **first** command that needs an
+account opens your browser for a one-time approval (OAuth Device Grant) and
+stores the token in your OS keychain. Every mode shares that one login.
+
+### MCP host config (zero extra commands)
+
+Point your MCP host at the same binary — `npx` installs it on first use:
+
+```json
+{
+  "mcpServers": {
+    "nexvora": { "command": "npx", "args": ["-y", "nexvora", "mcp"] }
+  }
+}
+```
+
+After a global install you can use `{ "command": "nexvora", "args": ["mcp"] }`.
+
+Tasks submitted from an MCP host run on a donor **with your local project
+context** (CLAUDE.md, your MCP servers, hooks) and are end-to-end encrypted.
+`nexvora_submit_task` returns immediately with a Task ID; fetch the answer with
+`nexvora_task_result` (it streams the output so far while the task is still
+running, and serves the final result even after a daemon restart once your vault
+is unlocked).
+
+## Encryption vault (end-to-end results)
+
+Your task **prompt and result** are sealed so the platform can't read them. The
+key that opens them is protected by a passphrase that never leaves your machine.
+
+```bash
+nexvora vault setup     # first time: choose a passphrase, creates the vault
+nexvora vault unlock    # on a new device: re-derive + cache the key
+nexvora vault lock      # drop the cached key from the OS keychain
+```
+
+- The passphrase is **separate** from your account login (the daemon never sees
+  your account password — it logs in via Device Grant).
+- **Account recovery is ON by default**: if you forget the passphrase, an admin
+  can recover your key via escrow on a verified, audited request. Turn it off for
+  maximum privacy (then a lost passphrase means lost history).
+
+## Sessions: single vs long-running
+
+Your **login** (the rotating refresh token in the keychain) persists until you
+`logout`. The single-vs-long-running choice controls the **session key** — the
+ephemeral per-task crypto material — and how long the background daemon lives.
+
+| Mode | Session key | Idle timeout |
+|------|-------------|--------------|
+| One-shot (`nexvora "…"`) | created, torn down after the task | short (daemon quits soon after) |
+| Donor (`nexvora donor`) | per task you serve, per direction | long-running |
+| MCP (`nexvora mcp`) | warm across tool calls | 10 min (keeps the daemon warm) |
+
+- Override the idle window: `nexvora-daemon --mode user --idle 1800` (seconds), or
+  the `NEXVORA_IDLE_TIMEOUT_SECONDS` env var. `0` keeps the daemon up until
+  `nexvora daemon stop`.
+- End a foreground task immediately with Ctrl-C; stop the background daemon with
+  `nexvora daemon stop`.
+
+## Admin commands
+
+```bash
+nexvora escrow init                 # create + install the platform escrow key (once)
+nexvora dispute open <delegation>   # decrypt a disputed result via escrow (audited)
+```
+
+Both prompt for the admin credential locally; the server never decrypts.
+
+## Updating
+
+```bash
+npm install -g nexvora@latest    # or: npm update -g nexvora
+```
+
+The native binary updates with the package. Your login and vault stay in the OS
+keychain across updates — no re-login or re-setup needed.
+
+## How it ships (for maintainers)
+
+This package is a small launcher (`bin/nexvora.js`) that resolves and execs the
+native binary. The binary lives in one of:
+
+`@nexvora/cli-darwin-arm64`, `@nexvora/cli-darwin-x64`,
+`@nexvora/cli-linux-x64`, `@nexvora/cli-win32-x64`
+
+each gated by `os`/`cpu` so npm installs exactly one. Each platform package
+carries two binaries — `nexvora` (the entry point the launcher execs) and
+`nexvora-daemon` (the engine it finds as a sibling).
+
+**Releasing** (see `docs/operations/release-and-deploy.md`): push a tag
+`nexvora-v<version>`. CI (`.github/workflows/nexvora-cli-release.yml`)
+cross-compiles all four targets, runs `scripts/package-binaries.mjs` to stage the
+binaries + sync versions, publishes the platform packages first, then this
+launcher last (`npm publish --provenance`).
+
+`@nexvora/mcp-server` (the TypeScript server) keeps working as before; pass
+`--native` or `NEXVORA_MCP_NATIVE=1` to make it delegate to the native
+`nexvora mcp` during cutover.
+
+## License
+
+UNLICENSED © NexVora

package/bin/nexvora.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Thin launcher for the native `nexvora` binary.
+ *
+ * The real engine (auth + OS keychain, MCP stdio server, CLI, donor daemon,
+ * encrypted tunnel) is a single Rust binary. It ships in exactly one per-platform
+ * npm package (`@nexvora/cli-<os>-<cpu>`), each gated by package.json `os`/`cpu`
+ * so npm installs only the one matching the host. This launcher resolves that
+ * binary and execs it transparently — argv, stdio, signals, and exit code all
+ * pass straight through, so `nexvora mcp` speaks MCP over stdio with no
+ * interference, and Ctrl-C reaches the binary directly.
+ *
+ * It is intentionally tiny and does NO work itself: one command — `nexvora` —
+ * is all the user ever runs; the binary handles first-run login on its own.
+ */
+
+const { spawn } = require("node:child_process");
+
+/** os-cpu -> per-platform package that carries the prebuilt binary. */
+const PLATFORM_PACKAGES = {
+  "darwin-arm64": "@nexvora/cli-darwin-arm64",
+  "darwin-x64": "@nexvora/cli-darwin-x64",
+  "linux-x64": "@nexvora/cli-linux-x64",
+  "win32-x64": "@nexvora/cli-win32-x64",
+};
+
+function fail(message) {
+  process.stderr.write(`nexvora: ${message}\n`);
+  process.exit(1);
+}
+
+function resolveBinary() {
+  const key = `${process.platform}-${process.arch}`;
+  const pkg = PLATFORM_PACKAGES[key];
+  if (!pkg) {
+    fail(
+      `unsupported platform ${key}.\n` +
+        `Supported: ${Object.keys(PLATFORM_PACKAGES).join(", ")}.`,
+    );
+  }
+  const exe = process.platform === "win32" ? "nexvora.exe" : "nexvora";
+  try {
+    return require.resolve(`${pkg}/bin/${exe}`);
+  } catch {
+    fail(
+      `the native binary for ${key} is missing.\n` +
+        `Its package '${pkg}' was not installed — usually because optional\n` +
+        `dependencies were skipped. Reinstall with them enabled:\n` +
+        `  npm install -g nexvora\n` +
+        `(remove any --no-optional / --omit=optional flag, and check proxy settings).`,
+    );
+  }
+}
+
+const child = spawn(resolveBinary(), process.argv.slice(2), { stdio: "inherit" });
+
+// Forward termination signals to the binary so long-lived modes (donor, mcp)
+// shut down cleanly and tear down the session key (L3) on the way out.
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  });
+}
+
+child.on("error", (err) => fail(err.message));
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // Re-raise so the parent reports the same termination cause.
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "nexvora",
+  "version": "0.1.0",
+  "description": "NexVora — one binary for the MCP server, CLI, and donor daemon. Single login, run anything.",
+  "keywords": [
+    "nexvora",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cli",
+    "donor",
+    "ai"
+  ],
+  "license": "UNLICENSED",
+  "bin": {
+    "nexvora": "bin/nexvora.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "//": "The actual native (Rust) binary ships in exactly one of these per-platform packages; npm installs only the one matching the user's os/cpu (see each package's os/cpu fields). bin/nexvora.js resolves and execs it.",
+  "optionalDependencies": {
+    "@nexvora/cli-darwin-arm64": "0.1.0",
+    "@nexvora/cli-darwin-x64": "0.1.0",
+    "@nexvora/cli-linux-x64": "0.1.0",
+    "@nexvora/cli-win32-x64": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/buntythecoder/nexvora-backend.git",
+    "directory": "packages/nexvora"
+  }
+}