@openparachute/vault 0.1.0

package/docker-compose.yml

@@ -0,0 +1,50 @@
+# Parachute Vault — self-hosted deployment
+#
+# Quick start:
+#   1. Copy .env.example to .env and fill in your values
+#   2. docker compose up -d
+#
+# For HTTPS (required for MCP from Claude Desktop):
+#   Set VAULT_DOMAIN in .env, ensure DNS points to this server.
+#   Caddy handles Let's Encrypt automatically.
+#
+# Without HTTPS (local/development):
+#   Leave VAULT_DOMAIN empty — Caddy proxies on port 80 only.
+
+services:
+  vault:
+    build: .
+    restart: unless-stopped
+    volumes:
+      - vault-data:/data
+    env_file: .env
+    environment:
+      - PARACHUTE_HOME=/data
+    expose:
+      - "1940"
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:1940/health"]
+      interval: 30s
+      timeout: 3s
+      start_period: 5s
+
+  caddy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy-data:/data
+      - caddy-config:/config
+    environment:
+      - VAULT_DOMAIN=${VAULT_DOMAIN:-localhost}
+    depends_on:
+      vault:
+        condition: service_healthy
+
+volumes:
+  vault-data:
+  caddy-data:
+  caddy-config:

package/docs/HTTP_API.md

@@ -0,0 +1,328 @@
+# Parachute Vault HTTP API
+
+A flat reference for the Parachute Vault HTTP surface. Intended for humans *and*
+agents building tools that read or write a vault over HTTP.
+
+All endpoints serve JSON. The same vault is reachable at two roots:
+
+- `/api/...` — the server's default vault
+- `/vaults/{name}/api/...` — any named vault on this server
+
+Use whichever is convenient. Examples below use the default `/api` root.
+
+## Quick start — render a graph in 5 lines
+
+```js
+const res = await fetch("http://localhost:1940/api/graph", {
+  headers: { Authorization: `Bearer ${apiKey}` },
+});
+const { notes, links, tags, meta } = await res.json();
+// notes: lightweight NoteIndex[] — id, path, tags, createdAt, byteSize, preview
+// links: Link[]                 — sourceId, targetId, relationship, metadata
+// Hand this to d3-force, cytoscape, sigma.js, etc.
+```
+
+That's the whole happy path. Everything else in this doc is detail.
+
+## Conventions
+
+- **Response payloads are camelCase**: `createdAt`, `sourceId`, `mimeType`,
+  `totalNotes`.
+- **Request payloads are camelCase**: you `POST {sourceId, targetId, ...}` and
+  get the same shape back.
+- **Query params are snake_case**: `?include_content=true`, `?tag_match=any`,
+  `?date_from=2025-01-01`. This matches the MCP tool-arg convention, so one
+  concept ports cleanly between HTTP and MCP.
+- **Timestamps are ISO-8601** UTC strings (e.g. `2026-04-07T15:30:00.000Z`).
+- **No envelope**. Responses are the data itself (`{...}` or `[...]`), not
+  wrapped in `{data: ...}`. Error responses are `{error: "...", message?: "..."}`.
+
+## Authentication
+
+Pass your API key as either:
+
+```
+Authorization: Bearer <key>
+X-API-Key: <key>
+```
+
+Requests from localhost bypass auth (you can hit the server directly without a
+key for local dev).
+
+Keys have a **scope**:
+
+- `write` — full access
+- `read`  — `GET`/`HEAD`/`OPTIONS` only; writes return `403 Forbidden`
+
+A read-only key is the right thing to hand to a visualizer or static-site
+generator.
+
+## The shapes
+
+### `Note`
+
+```ts
+{
+  id: string;
+  content: string;
+  path?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt?: string;
+  tags?: string[];
+}
+```
+
+### `NoteIndex` (lean shape)
+
+Returned by list endpoints by default. Same as `Note` minus `content`, plus
+`byteSize` and a one-line `preview` (120 code points, whitespace collapsed).
+
+```ts
+{
+  id: string;
+  path?: string;
+  createdAt: string;
+  updatedAt?: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  byteSize: number;  // UTF-8 bytes of the full content
+  preview: string;   // first ~120 chars, single line
+}
+```
+
+### `Link`
+
+```ts
+{
+  sourceId: string;
+  targetId: string;
+  relationship: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}
+```
+
+### `VaultStats`
+
+```ts
+{
+  totalNotes: number;
+  earliestNote: { id: string; createdAt: string } | null;
+  latestNote:   { id: string; createdAt: string } | null;
+  notesByMonth: { month: string; count: number }[];  // e.g. "2026-04"
+  topTags:      { tag: string; count: number }[];
+  tagCount:     number;
+}
+```
+
+## Defaults: lean lists, fat point reads
+
+- **List endpoints** (`GET /notes`, `GET /graph`) default to `NoteIndex`. The
+  common case is viz/listing, which doesn't need the full body of every note.
+- **Point reads** (`GET /notes/:id`) default to the full `Note`. If you asked
+  for one specific thing by ID, you probably want its content.
+
+Both shapes can be forced either way with `?include_content=true|false`.
+
+## Endpoints
+
+### Server-level
+
+#### `GET /health`
+Returns `{status: "ok", vaults: string[]}`. No auth required.
+
+#### `GET /vaults`
+List all vaults on the server.
+```json
+{
+  "vaults": [
+    { "name": "default", "description": "...", "created_at": "..." }
+  ]
+}
+```
+
+#### `GET /vaults/{name}`
+Single-vault landing payload — name, description, createdAt, and stats in one
+round trip. Useful for a viz site's home page.
+```json
+{
+  "name": "default",
+  "description": "My knowledge graph",
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "stats": { "totalNotes": 617, "topTags": [...], "notesByMonth": [...], ... }
+}
+```
+
+### Notes
+
+#### `GET /notes`
+Query notes. Returns `NoteIndex[]` by default.
+
+Query params:
+- `include_content=true` — return full `Note[]` instead.
+- `ids=a,b,c` — fetch specific notes by ID. Practical limit ~50 IDs due to
+  URL length; for larger batches call multiple times.
+- `tag=foo&tag=bar` — filter by tags (repeat param to pass multiple).
+- `tag_match=all|any` — default `all`.
+- `exclude_tag=foo` — exclude notes with this tag.
+- `date_from=ISO` — inclusive lower bound on `createdAt`.
+- `date_to=ISO` — exclusive upper bound.
+- `sort=asc|desc` — by `createdAt`. Default `asc`.
+- `limit=N` — default 100.
+- `offset=N` — default 0.
+
+#### `POST /notes`
+Create a note. Body:
+```json
+{
+  "content": "...",            // required
+  "id": "optional-client-id",
+  "path": "Projects/Foo",
+  "tags": ["a", "b"],
+  "metadata": { "status": "draft" },
+  "createdAt": "2026-04-07T..."
+}
+```
+Returns the created `Note`, `201 Created`.
+
+#### `GET /notes/{id}`
+Returns the full `Note`. `?include_content=false` returns a `NoteIndex`.
+
+#### `PATCH /notes/{id}`
+Update content, path, or metadata. Body:
+```json
+{ "content": "new body", "path": "new/path", "metadata": {...} }
+```
+
+#### `DELETE /notes/{id}`
+Returns `{deleted: true}`.
+
+#### `POST /notes/{id}/tags`, `DELETE /notes/{id}/tags`
+Body: `{"tags": ["a", "b"]}`.
+
+#### `POST /notes/{id}/attachments`
+Body: `{"path": "files/a.png", "mimeType": "image/png"}`.
+
+#### `GET /notes/{id}/attachments`
+Returns `Attachment[]`.
+
+### Links
+
+#### `GET /links`
+List edges. Polymorphic — filters compose freely.
+
+Query params:
+- `note_id=abc` — only edges touching this note.
+- `direction=outbound|inbound|both` — only meaningful with `note_id`.
+  Default `both`.
+- `relationship=cites` — only edges of this type.
+
+Returns bare `Link[]` — no hydration. If you need the connected notes'
+details, pair the result with `GET /notes?ids=...`.
+
+Examples:
+```
+GET /links                              # everything
+GET /links?note_id=abc                  # all edges touching note abc
+GET /links?note_id=abc&direction=outbound
+GET /links?relationship=cites           # vault-wide, by type
+```
+
+#### `POST /links`
+Body:
+```json
+{ "sourceId": "a", "targetId": "b", "relationship": "cites", "metadata": {...} }
+```
+
+#### `DELETE /links`
+Body:
+```json
+{ "sourceId": "a", "targetId": "b", "relationship": "cites" }
+```
+
+### Graph
+
+#### `GET /graph`
+One-shot knowledge graph payload for visualization.
+
+```json
+{
+  "notes": [ /* NoteIndex[] by default, Note[] if include_content=true */ ],
+  "links": [ /* Link[] */ ],
+  "tags":  [ { "name": "...", "count": 12 } ],
+  "meta": {
+    "totalNotes": 617,
+    "totalLinks": 1234,
+    "filteredNotes": 617,
+    "filteredLinks": 1234,
+    "includeContent": false
+  }
+}
+```
+
+Query params:
+- `include_content=true` — fatten each note to include full content.
+- `tag=foo&tag=bar` — filter to a subgraph (only notes with these tags, and
+  only links where **both** endpoints are in the subset).
+- `tag_match=all|any` — default `all`.
+- `exclude_tag=foo`.
+
+`meta.totalNotes` / `meta.totalLinks` always reflect the full vault;
+`filteredNotes` / `filteredLinks` reflect the response.
+
+### Search
+
+#### `GET /search?q=query`
+Full-text search. Returns `Note[]` (full shape).
+
+Query params:
+- `q=...` — required.
+- `tag=foo` — optional tag filter (repeatable).
+- `limit=N` — default 50.
+
+### Tags
+
+#### `GET /tags`
+Returns `[{name, count}]`.
+
+### Vault stats
+
+You usually want `GET /vaults/{name}` which bundles stats with vault metadata.
+If you only need the stats, call `GET /vaults/{name}` and read `.stats`.
+
+### Storage
+
+#### `POST /storage/upload`
+Multipart form:
+- `file` — required, audio/image, ≤100MB
+
+Returns `{path, size, mimeType}`.
+
+#### `GET /storage/{date}/{filename}`
+Serves the uploaded file.
+
+## CORS
+
+The server sends permissive CORS headers (`Access-Control-Allow-Origin: *`)
+so a static site on any origin can fetch the API. Writes still require a
+valid API key.
+
+## Pairing with MCP
+
+Every read endpoint here has a matching MCP tool over `/mcp`
+(unified) or `/vaults/{name}/mcp` (scoped):
+
+| HTTP                      | MCP tool            |
+|---------------------------|---------------------|
+| `GET /notes`              | `read-notes`        |
+| `GET /notes?ids=...`      | `get-note` (ids)    |
+| `GET /notes/{id}`         | `get-note`          |
+| `GET /links`              | `get-links`         |
+| `GET /graph`              | `get-graph`         |
+| `GET /vaults/{name}`      | `get-vault-stats` + `get-vault-description` |
+| `GET /tags`               | `list-tags`         |
+| `GET /search?q=`          | `search-notes`      |
+
+The MCP tools use the same lean-vs-fat convention (`include_content: true|false`)
+and the same snake_case arg names as the HTTP query params.

package/fly.toml

@@ -0,0 +1,24 @@
+app = "parachute-vault"
+primary_region = "iad"
+
+[build]
+  dockerfile = "Dockerfile"
+
+[env]
+  PORT = "1940"
+  PARACHUTE_HOME = "/data"
+
+[http_service]
+  internal_port = 1940
+  force_https = true
+  auto_stop_machines = "stop"
+  auto_start_machines = true
+  min_machines_running = 0
+
+[[vm]]
+  size = "shared-cpu-1x"
+  memory = "512mb"
+
+[[mounts]]
+  source = "vault_data"
+  destination = "/data"

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@openparachute/vault",
+  "version": "0.1.0",
+  "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
+  "module": "src/cli.ts",
+  "type": "module",
+  "bin": {
+    "parachute": "src/cli.ts"
+  },
+  "scripts": {
+    "start": "bun src/server.ts",
+    "cli": "bun src/cli.ts",
+    "test": "bun test src/",
+    "test:core": "cd core && node --experimental-vm-modules node_modules/vitest/dist/cli.js run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "otpauth": "^9.5.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ParachuteComputer/parachute-vault.git"
+  },
+  "license": "AGPL-3.0"
+}

package/railway.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "Dockerfile"
+  },
+  "deploy": {
+    "startCommand": "bun src/server.ts",
+    "healthcheckPath": "/health",
+    "healthcheckTimeout": 5,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 3
+  }
+}

package/scripts/migrate-audio-to-opus.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Tests for scripts/migrate-audio-to-opus.ts.
+ *
+ * Spins up a temp vault layout under a fresh PARACHUTE_HOME, seeds a WAV
+ * attachment, runs the script in dry-run then real mode, asserts the DB
+ * row was rewritten, the .ogg file exists, and the original was unlinked.
+ *
+ * Uses the real ffmpeg binary (matches src/audio-encoding.test.ts).
+ *
+ * Requires `@openparachute/narrate` which is not a vault dependency.
+ * Install manually (`bun add @openparachute/narrate`) to run these tests.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { SCHEMA_SQL } from "../core/src/schema.ts";
+
+// @openparachute/narrate is not a vault dependency — dynamically import
+// so the test file can at least be parsed without the optional package.
+let runMigration: typeof import("./migrate-audio-to-opus.ts").runMigration;
+let hasDep = false;
+try {
+  ({ runMigration } = await import("./migrate-audio-to-opus.ts"));
+  hasDep = true;
+} catch {
+  // dependency missing — tests will be skipped below
+}
+
+function buildSilentWav(samples: number): Buffer {
+  const sampleRate = 8000;
+  const numChannels = 1;
+  const bitsPerSample = 16;
+  const byteRate = (sampleRate * numChannels * bitsPerSample) / 8;
+  const blockAlign = (numChannels * bitsPerSample) / 8;
+  const dataSize = samples * blockAlign;
+  const chunkSize = 36 + dataSize;
+  const buf = Buffer.alloc(44 + dataSize);
+  let off = 0;
+  buf.write("RIFF", off); off += 4;
+  buf.writeUInt32LE(chunkSize, off); off += 4;
+  buf.write("WAVE", off); off += 4;
+  buf.write("fmt ", off); off += 4;
+  buf.writeUInt32LE(16, off); off += 4;
+  buf.writeUInt16LE(1, off); off += 2;
+  buf.writeUInt16LE(numChannels, off); off += 2;
+  buf.writeUInt32LE(sampleRate, off); off += 4;
+  buf.writeUInt32LE(byteRate, off); off += 4;
+  buf.writeUInt16LE(blockAlign, off); off += 2;
+  buf.writeUInt16LE(bitsPerSample, off); off += 2;
+  buf.write("data", off); off += 4;
+  buf.writeUInt32LE(dataSize, off); off += 4;
+  return buf;
+}
+
+let tmpHome: string;
+let prevHome: string | undefined;
+let prevAssets: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(
+    tmpdir(),
+    `migrate-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(tmpHome, { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  prevAssets = process.env.ASSETS_DIR;
+  process.env.PARACHUTE_HOME = tmpHome;
+  delete process.env.ASSETS_DIR; // use default per-vault assets dir
+});
+
+afterEach(() => {
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (prevAssets === undefined) delete process.env.ASSETS_DIR;
+  else process.env.ASSETS_DIR = prevAssets;
+  try {
+    rmSync(tmpHome, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+});
+
+interface SeedResult {
+  vault: string;
+  dbPath: string;
+  assetsBase: string;
+  noteId: string;
+  attachmentId: string;
+  relWavPath: string;
+  absWavPath: string;
+  relOggPath: string;
+  absOggPath: string;
+  noteUpdatedAt: string;
+}
+
+function seedVaultWithWav(vaultName: string): SeedResult {
+  const vaultDir = join(tmpHome, "vaults", vaultName);
+  mkdirSync(vaultDir, { recursive: true });
+  const dbPath = join(vaultDir, "vault.db");
+  const assetsBase = join(vaultDir, "assets");
+  mkdirSync(assetsBase, { recursive: true });
+
+  const db = new Database(dbPath);
+  db.exec(SCHEMA_SQL);
+
+  const noteId = "n_" + Math.random().toString(36).slice(2, 10);
+  const attachmentId = "a_" + Math.random().toString(36).slice(2, 10);
+  const now = new Date().toISOString();
+
+  db.prepare(
+    "INSERT INTO notes (id, content, path, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)",
+  ).run(noteId, "hello reader", null, "{}", now, now);
+
+  const relWavPath = `tts/2026-04-08/${noteId}-123.wav`;
+  const absWavPath = join(assetsBase, relWavPath);
+  mkdirSync(join(assetsBase, "tts", "2026-04-08"), { recursive: true });
+  // Write ~1s of silence WAV. ffmpeg handles this fine.
+  writeFileSync(absWavPath, buildSilentWav(8000));
+
+  db.prepare(
+    "INSERT INTO attachments (id, note_id, path, mime_type, metadata, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+  ).run(attachmentId, noteId, relWavPath, "audio/wav", "{}", now);
+
+  db.close();
+
+  return {
+    vault: vaultName,
+    dbPath,
+    assetsBase,
+    noteId,
+    attachmentId,
+    relWavPath,
+    absWavPath,
+    relOggPath: relWavPath.replace(/\.wav$/, ".ogg"),
+    absOggPath: absWavPath.replace(/\.wav$/, ".ogg"),
+    noteUpdatedAt: now,
+  };
+}
+
+describe.skipIf(!hasDep)("migrate-audio-to-opus", () => {
+  test("dry-run reports candidates without touching anything", async () => {
+    const seed = seedVaultWithWav("default");
+
+    const logs: string[] = [];
+    const origLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map((a) => String(a)).join(" "));
+    };
+    try {
+      const summaries = await runMigration(["--vault", "default", "--dry-run"]);
+      expect(summaries.length).toBe(1);
+      expect(summaries[0].dryRunCandidates).toBe(1);
+      expect(summaries[0].converted).toBe(0);
+      expect(summaries[0].errors).toBe(0);
+    } finally {
+      console.log = origLog;
+    }
+
+    expect(logs.some((l) => l.includes("DRY-RUN convert") && l.includes(seed.relWavPath))).toBe(
+      true,
+    );
+
+    // Nothing moved.
+    expect(existsSync(seed.absWavPath)).toBe(true);
+    expect(existsSync(seed.absOggPath)).toBe(false);
+
+    const db = new Database(seed.dbPath);
+    try {
+      const row = db
+        .prepare("SELECT path, mime_type FROM attachments WHERE id = ?")
+        .get(seed.attachmentId) as { path: string; mime_type: string };
+      expect(row.path).toBe(seed.relWavPath);
+      expect(row.mime_type).toBe("audio/wav");
+    } finally {
+      db.close();
+    }
+  });
+
+  test("full run converts WAV to Opus, updates DB, unlinks original, no updated_at bump", async () => {
+    const seed = seedVaultWithWav("default");
+
+    const origLog = console.log;
+    console.log = () => {};
+    try {
+      const summaries = await runMigration(["--vault", "default"]);
+      expect(summaries[0].converted).toBe(1);
+      expect(summaries[0].errors).toBe(0);
+      expect(summaries[0].bytesAfter).toBeGreaterThan(0);
+    } finally {
+      console.log = origLog;
+    }
+
+    // Original .wav removed, .ogg exists and has OggS magic bytes.
+    expect(existsSync(seed.absWavPath)).toBe(false);
+    expect(existsSync(seed.absOggPath)).toBe(true);
+    const oggBytes = readFileSync(seed.absOggPath);
+    expect(oggBytes.toString("ascii", 0, 4)).toBe("OggS");
+
+    // DB row rewritten.
+    const db = new Database(seed.dbPath);
+    try {
+      const row = db
+        .prepare("SELECT path, mime_type FROM attachments WHERE id = ?")
+        .get(seed.attachmentId) as { path: string; mime_type: string };
+      expect(row.path).toBe(seed.relOggPath);
+      expect(row.mime_type).toBe("audio/ogg");
+
+      // Note's updated_at must NOT have changed — this is a storage
+      // migration, not a content edit.
+      const note = db
+        .prepare("SELECT updated_at FROM notes WHERE id = ?")
+        .get(seed.noteId) as { updated_at: string };
+      expect(note.updated_at).toBe(seed.noteUpdatedAt);
+    } finally {
+      db.close();
+    }
+  });
+
+  test("re-running after a successful migration is a no-op (idempotent)", async () => {
+    seedVaultWithWav("default");
+
+    const origLog = console.log;
+    console.log = () => {};
+    try {
+      await runMigration(["--vault", "default"]);
+      const second = await runMigration(["--vault", "default"]);
+      expect(second[0].converted).toBe(0);
+      expect(second[0].skipped).toBe(1);
+      expect(second[0].errors).toBe(0);
+    } finally {
+      console.log = origLog;
+    }
+  });
+});