@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/src/config.test.ts

@@ -169,6 +169,33 @@ describe("config", () => {
     expect(loaded!.transcription).toBeUndefined();
   });
 
+  test("round-trips per-vault auto_transcribe.enabled (true + false)", () => {
+    // The PATCH /api/vault handler persists the per-vault toggle via
+    // writeVaultConfig; confirm it survives a read-back — this is the exact
+    // field shouldAutoTranscribe reads per-vault (per-vault → global → true).
+    const base: VaultConfig = {
+      name: "testvault",
+      api_keys: [],
+      created_at: "2026-01-01T00:00:00.000Z",
+    };
+
+    writeVaultConfig({ ...base, auto_transcribe: { enabled: true } });
+    expect(readVaultConfig("testvault")!.auto_transcribe?.enabled).toBe(true);
+
+    writeVaultConfig({ ...base, auto_transcribe: { enabled: false } });
+    expect(readVaultConfig("testvault")!.auto_transcribe?.enabled).toBe(false);
+  });
+
+  test("vault config without auto_transcribe loads as undefined (falls back to global)", () => {
+    const config: VaultConfig = {
+      name: "testvault",
+      api_keys: [],
+      created_at: "2026-01-01T00:00:00.000Z",
+    };
+    writeVaultConfig(config);
+    expect(readVaultConfig("testvault")!.auto_transcribe).toBeUndefined();
+  });
+
   test("round-trips discovery: enabled|disabled", () => {
     // Default: absent means enabled (endpoint serves names).
     writeGlobalConfig({ port: 1940 });
@@ -213,6 +240,72 @@ describe("config", () => {
     expect(reloaded.api_keys?.find((k) => k.id === "k_legacy")?.scope).toBe("write");
   });
 
+  // ----- vault#234: anchored api_keys field regexes ----------------------
+  // The api_keys field regexes (label/scope/key_hash/created_at/last_used_at)
+  // used to be unanchored, so a COMMENTED `# scope: read` line matched, and a
+  // value-less `scope: ` (trailing space) captured the NEXT field's token
+  // (`key_hash`). The writer never emits either shape — only hand-editing
+  // reaches these branches — but a malformed scope could silently mis-scope a
+  // key. The regexes are now line-anchored + horizontal-whitespace-bounded.
+
+  test("vault#234: commented `# scope:` line is ignored, scope falls back to default", () => {
+    const fs = require("fs");
+    const path = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234"), { recursive: true });
+    // The only `scope:` line is commented out; the parser must NOT pick it up.
+    fs.writeFileSync(
+      path,
+      `name: mv234\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_cmt\n    label: commented\n    # scope: read\n    key_hash: sha256:cmt\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    const loaded = readVaultConfig("mv234");
+    const key = loaded!.api_keys.find((k) => k.id === "k_cmt");
+    expect(key).toBeDefined();
+    // Commented scope ignored → default "write", NOT "read".
+    expect(key!.scope).toBe("write");
+    expect(key!.key_hash).toBe("sha256:cmt");
+  });
+
+  test("vault#234: value-less `scope: ` (trailing space) does NOT capture the next field", () => {
+    const fs = require("fs");
+    const path = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234b", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234b"), { recursive: true });
+    // `scope: ` has a trailing space and no value; the OLD regex skipped the
+    // newline and captured `sha256:trailing` (the key_hash) as the scope.
+    fs.writeFileSync(
+      path,
+      `name: mv234b\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_trail\n    label: trailing\n    scope: \n    key_hash: sha256:trailing\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    const loaded = readVaultConfig("mv234b");
+    const key = loaded!.api_keys.find((k) => k.id === "k_trail");
+    expect(key).toBeDefined();
+    // The hash must NOT have been borrowed as the scope.
+    expect(key!.scope).not.toBe("sha256:trailing");
+    expect(key!.scope).toBe("write"); // default
+    // And the real key_hash is still parsed correctly.
+    expect(key!.key_hash).toBe("sha256:trailing");
+  });
+
+  test("vault#234: a valid `scope: read` still parses (positive control, both parsers)", () => {
+    const fs = require("fs");
+    // Vault-level parser.
+    const vpath = join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234c", "vault.yaml");
+    fs.mkdirSync(join(process.env.PARACHUTE_HOME!, "vault", "data", "mv234c"), { recursive: true });
+    fs.writeFileSync(
+      vpath,
+      `name: mv234c\ncreated_at: "2026-01-01T00:00:00.000Z"\napi_keys:\n  - id: k_v\n    label: reader\n    scope: read\n    key_hash: sha256:v\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    expect(readVaultConfig("mv234c")!.api_keys.find((k) => k.id === "k_v")?.scope).toBe("read");
+
+    // Global parser, same grammar.
+    const gpath = join(process.env.PARACHUTE_HOME!, "vault", "config.yaml");
+    fs.writeFileSync(
+      gpath,
+      `port: 1940\napi_keys:\n  - id: k_g\n    label: reader\n    # scope: write\n    scope: read\n    key_hash: sha256:g\n    created_at: "2026-01-01T00:00:00.000Z"\n`,
+    );
+    // The commented `# scope: write` is skipped; the real `scope: read` wins.
+    expect(readGlobalConfig().api_keys?.find((k) => k.id === "k_g")?.scope).toBe("read");
+  });
+
   test("writeEnvFile writes .env at 0600 (SCRIBE_AUTH_TOKEN secrecy)", () => {
     // Regression for vault#354 reviewer finding: the .env holds
     // SCRIBE_AUTH_TOKEN (the vault↔scribe loopback bearer). On a
@@ -250,6 +343,22 @@ describe("config", () => {
     writeGlobalConfig({ port: 1940, autostart: false });
     expect(readGlobalConfig().autostart).toBe(false);
   });
+
+  test("round-trips default_mirror: internal|off", () => {
+    // Absent: createVault falls back to the in-code default ("internal" —
+    // backup-on-by-default). The knob is only persisted when explicitly set.
+    writeGlobalConfig({ port: 1940 });
+    expect(readGlobalConfig().default_mirror).toBeUndefined();
+
+    // Explicit internal — new vaults get the History-preset local git mirror.
+    writeGlobalConfig({ port: 1940, default_mirror: "internal" });
+    expect(readGlobalConfig().default_mirror).toBe("internal");
+
+    // Explicit off — the opt-out operators set on git-less / disk-constrained
+    // / cloud boxes so new vaults are created with no mirror config.
+    writeGlobalConfig({ port: 1940, default_mirror: "off" });
+    expect(readGlobalConfig().default_mirror).toBe("off");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/config.ts

@@ -115,6 +115,17 @@ export function vaultConfigPath(name: string): string {
   return join(vaultDir(name), "vault.yaml");
 }
 
+/**
+ * Per-vault attachments directory: `<vaultDir>/assets`, or the `ASSETS_DIR`
+ * env override when set (single-assets-root deployments). Lives here next to
+ * the other path helpers — neutral ground that both `routes.ts` (upload/serve)
+ * and `usage.ts` (footprint dir-walk) import without a cycle. `routes.ts`
+ * re-exports it for the existing callers (mirror-deps, server, triggers, …).
+ */
+export function assetsDir(name: string): string {
+  return process.env.ASSETS_DIR ?? join(vaultDir(name), "assets");
+}
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -172,6 +183,23 @@ export interface VaultConfig {
   transcription?: {
     context?: TriggerIncludeContext[];
   };
+  /**
+   * Per-vault auto-transcribe override (vault#353 follow-up). When set, this
+   * vault's value takes precedence over the server-wide
+   * `GlobalConfig.auto_transcribe.enabled`. Resolution at the decision point
+   * (`shouldAutoTranscribe`) is **per-vault → global → true**: a vault that
+   * sets `enabled` here uses it; a vault that leaves it unset falls back to
+   * the global toggle, which itself defaults ON.
+   *
+   * This is what makes scribe's "link to vault X" genuinely per-vault —
+   * `PATCH /vault/X/api/vault {auto_transcribe:{enabled:true}}` flips only
+   * vault X, never the whole server. URL + bearer are still resolved per-
+   * process (services.json / SCRIBE_AUTH_TOKEN); only the on/off toggle is
+   * per-vault.
+   */
+  auto_transcribe?: {
+    enabled?: boolean;
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -229,6 +257,20 @@ export interface TriggerAction {
    * top-level `context` field (send=json). send=content ignores this.
    */
   include_context?: TriggerIncludeContext[];
+  /**
+   * Optional webhook auth. When `auth.bearer` is set, the trigger sends
+   * `Authorization: Bearer <bearer>` on the webhook POST — the JWT path that
+   * retires the shared `?secret=` query param. Back-compat: a webhook URL
+   * carrying its own `?secret=` still works; `auth` is purely additive.
+   * Runtime triggers (registered via the /api/triggers REST surface) are the
+   * primary users; config.yaml triggers may also carry it.
+   */
+  auth?: TriggerAuth;
+}
+
+export interface TriggerAuth {
+  /** Bearer token (typically a hub-issued JWT) for the webhook Authorization header. */
+  bearer?: string;
 }
 
 export interface TriggerConfig {
@@ -270,6 +312,19 @@ export interface GlobalConfig {
    * point their own supervisor at it.
    */
   autostart?: boolean;
+  /**
+   * Boot auto-create marker (2026-06-09 hub-module-boundary migration, the
+   * vault wave's `cmdRemove` improvement). Server boot auto-creates a
+   * `default` vault when `listVaults()` is empty — the Docker / hub-install
+   * first-run path. When the operator EXPLICITLY deletes their last vault
+   * via `parachute-vault remove`, that auto-create would silently resurrect
+   * a fresh `default` (with fresh credentials) on the next boot. `cmdRemove`
+   * writes `auto_create: false` when it removes the last vault; boot skips
+   * the auto-create while the marker is present. Fresh installs (no
+   * config.yaml at all) never carry the marker, so the Docker first-run
+   * behavior is preserved. See `bootAutoCreateAllowed`.
+   */
+  auto_create?: boolean;
   /** Backup configuration: schedule, retention, destinations. */
   backup?: BackupConfig;
   /**
@@ -280,6 +335,29 @@ export interface GlobalConfig {
    * resolved path. See `./mirror-config.ts`.
    */
   mirror?: MirrorConfigType;
+  /**
+   * Server-wide DEFAULT for newly created vaults' backup posture. Decides
+   * whether `createVault` writes the History-preset internal mirror
+   * (local git backup of the markdown projection) at create time.
+   *
+   *   - `"internal"` (default) — new vaults get a local git mirror enabled
+   *     out of the box (backup-on-by-default). The History preset:
+   *     `{enabled:true, location:internal, sync_mode:events, auto_commit:true,
+   *     auto_push:false}`. GitHub off-site backup remains an opt-in upgrade.
+   *   - `"off"` — new vaults are created with no mirror config (the historical
+   *     pre-default behavior). The escape hatch for git-less / disk-constrained
+   *     boxes and cloud deploys, where doubling disk per vault is unwanted.
+   *     Cloud / container deploys SHOULD set this to `off`.
+   *
+   * Create-time ONLY — this knob does NOT retroactively enable mirrors on
+   * already-created vaults (that would ~double disk across every existing
+   * vault). Existing-vault opt-in is a separate, deliberate follow-up.
+   *
+   * The container/cloud first-boot auto-create path in `server.ts` does NOT
+   * funnel through `createVault`, so it is unaffected by this knob and stays
+   * mirror-off regardless — matching the recommended cloud posture.
+   */
+  default_mirror?: "internal" | "off";
   /**
    * Auto-transcribe configuration for the vault↔scribe handoff (vault#353,
    * design 2026-05-21 Part 2). When `enabled: true` AND scribe is discoverable
@@ -396,6 +474,14 @@ function serializeVaultConfig(config: VaultConfig): string {
     lines.push(`audio_retention: ${config.audio_retention}`);
   }
 
+  // Per-vault auto-transcribe override. Serialized as a nested block so future
+  // fields can grow under it (mirrors the GlobalConfig shape). Only emitted
+  // when `enabled` is explicitly set — an unset vault falls back to global.
+  if (config.auto_transcribe?.enabled !== undefined) {
+    lines.push("auto_transcribe:");
+    lines.push(`  enabled: ${config.auto_transcribe.enabled}`);
+  }
+
   if (config.transcription?.context?.length) {
     lines.push("transcription:");
     lines.push("  context:");
@@ -484,14 +570,32 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
   }
 
   // Parse api_keys
+  //
+  // Accepted grammar (vault#234): each `id:` block is the writer's output —
+  // one field per line, indented two spaces under the `- id:` list item:
+  //
+  //     - id: <id>
+  //       label: <label>            # free text to end of line
+  //       scope: <scope>            # single token (read|write|admin|…)
+  //       key_hash: <hash>          # single token
+  //       created_at: "<iso>"       # quoted or bare, no embedded newline
+  //       last_used_at: "<iso>"
+  //
+  // Each field regex is line-anchored (`^...`, `m` flag) so a COMMENTED line
+  // (`# scope: read`) never matches — the line must begin with optional
+  // leading whitespace then the bare key. The value matcher uses horizontal
+  // whitespace only (`[^\S\r\n]*`, never `\s*`) after the colon so a
+  // value-less field (`scope: ` with a trailing space) can't skip the newline
+  // and capture the NEXT field's value. A missing optional field falls back to
+  // its default rather than borrowing a neighbor's token.
   const keyBlocks = yaml.split(/\n\s+-\s+id:\s+/).slice(1);
   for (const block of keyBlocks) {
     const idMatch = block.match(/^(\S+)/);
-    const labelMatch = block.match(/label:\s*(.+)/);
-    const scopeMatch = block.match(/scope:\s*(\S+)/);
-    const hashMatch = block.match(/key_hash:\s*(\S+)/);
-    const createdAtMatch = block.match(/created_at:\s*"?([^"\n]+)"?/);
-    const lastUsedMatch = block.match(/last_used_at:\s*"?([^"\n]+)"?/);
+    const labelMatch = block.match(/^[^\S\r\n]*label:[^\S\r\n]*(.+)/m);
+    const scopeMatch = block.match(/^[^\S\r\n]*scope:[^\S\r\n]*(\S+)/m);
+    const hashMatch = block.match(/^[^\S\r\n]*key_hash:[^\S\r\n]*(\S+)/m);
+    const createdAtMatch = block.match(/^[^\S\r\n]*created_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
+    const lastUsedMatch = block.match(/^[^\S\r\n]*last_used_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
 
     if (idMatch && hashMatch) {
       config.api_keys.push({
@@ -514,6 +618,22 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
     config.transcription = { context: transcriptionContext };
   }
 
+  // Parse the per-vault auto_transcribe block — currently single boolean
+  // `enabled`. Nested 2-space-indent block (mirrors the GlobalConfig parser)
+  // so future fields can grow under it without breaking the regex.
+  const autoTranscribeStart = yaml.match(/^auto_transcribe:\s*$/m);
+  if (autoTranscribeStart) {
+    const after = yaml.slice((autoTranscribeStart.index ?? 0) + autoTranscribeStart[0].length);
+    for (const line of after.split("\n")) {
+      if (line.match(/^\S/) && line.trim().length > 0) break; // next top-level key
+      const m = line.match(/^\s+enabled:\s*(true|false)/);
+      if (m) {
+        config.auto_transcribe = { enabled: m[1]! === "true" };
+        break;
+      }
+    }
+  }
+
   return config;
 }
 
@@ -1151,6 +1271,20 @@ export function migrateVaultInternalLayout(): void {
 // Global config
 // ---------------------------------------------------------------------------
 
+/**
+ * Whether server boot may auto-create the first vault when none exist.
+ *
+ * Only the explicit `auto_create: false` marker (written by `cmdRemove`
+ * when it deletes the LAST vault) blocks the auto-create. A fresh install
+ * has no config.yaml — `readGlobalConfig()` returns defaults with
+ * `auto_create` unset — so Docker / hub-install first-run still
+ * auto-creates `default`. Pure + exported so the boot gate is testable
+ * without booting a server.
+ */
+export function bootAutoCreateAllowed(config: Pick<GlobalConfig, "auto_create">): boolean {
+  return config.auto_create !== false;
+}
+
 export function readGlobalConfig(): GlobalConfig {
   try {
     const gcPath = globalConfigPath();
@@ -1162,6 +1296,8 @@ export function readGlobalConfig(): GlobalConfig {
       const totpSecretMatch = yaml.match(/^totp_secret:\s*"([^"]+)"/m);
       const discoveryMatch = yaml.match(/^discovery:\s*(enabled|disabled)/m);
       const autostartMatch = yaml.match(/^autostart:\s*(true|false)/m);
+      const autoCreateMatch = yaml.match(/^auto_create:\s*(true|false)/m);
+      const defaultMirrorMatch = yaml.match(/^default_mirror:\s*(internal|off)/m);
       // auto_transcribe block — currently single boolean `enabled` (vault#353).
       // Parsed as a nested 2-space-indent block so future fields can grow under
       // it without breaking the regex; only `enabled` is read for v0.6.
@@ -1190,6 +1326,12 @@ export function readGlobalConfig(): GlobalConfig {
       if (autostartMatch) {
         config.autostart = autostartMatch[1]! === "true";
       }
+      if (autoCreateMatch) {
+        config.auto_create = autoCreateMatch[1]! === "true";
+      }
+      if (defaultMirrorMatch) {
+        config.default_mirror = defaultMirrorMatch[1]! as "internal" | "off";
+      }
       if (autoTranscribeEnabled !== undefined) {
         config.auto_transcribe = { enabled: autoTranscribeEnabled };
       }
@@ -1212,16 +1354,19 @@ export function readGlobalConfig(): GlobalConfig {
       }
 
       // Parse global api_keys
+      // Same line-anchored grammar as the vault-level parser above (vault#234)
+      // — commented lines don't match; a value-less field can't capture the
+      // next field's token across the newline.
       const keyBlocks = yaml.split(/\n\s+-\s+id:\s+/).slice(1);
       if (keyBlocks.length > 0) {
         config.api_keys = [];
         for (const block of keyBlocks) {
           const idMatch = block.match(/^(\S+)/);
-          const labelMatch = block.match(/label:\s*(.+)/);
-          const scopeMatch = block.match(/scope:\s*(\S+)/);
-          const hashMatch = block.match(/key_hash:\s*(\S+)/);
-          const createdAtMatch = block.match(/created_at:\s*"?([^"\n]+)"?/);
-          const lastUsedMatch = block.match(/last_used_at:\s*"?([^"\n]+)"?/);
+          const labelMatch = block.match(/^[^\S\r\n]*label:[^\S\r\n]*(.+)/m);
+          const scopeMatch = block.match(/^[^\S\r\n]*scope:[^\S\r\n]*(\S+)/m);
+          const hashMatch = block.match(/^[^\S\r\n]*key_hash:[^\S\r\n]*(\S+)/m);
+          const createdAtMatch = block.match(/^[^\S\r\n]*created_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
+          const lastUsedMatch = block.match(/^[^\S\r\n]*last_used_at:[^\S\r\n]*"?([^"\n]+?)"?\s*$/m);
           if (idMatch && hashMatch) {
             config.api_keys.push({
               id: idMatch[1]!,
@@ -1259,6 +1404,8 @@ export function writeGlobalConfig(config: GlobalConfig): void {
   if (config.default_vault) lines.push(`default_vault: ${config.default_vault}`);
   if (config.discovery) lines.push(`discovery: ${config.discovery}`);
   if (config.autostart !== undefined) lines.push(`autostart: ${config.autostart}`);
+  if (config.auto_create !== undefined) lines.push(`auto_create: ${config.auto_create}`);
+  if (config.default_mirror) lines.push(`default_mirror: ${config.default_mirror}`);
   if (config.owner_password_hash) {
     lines.push(`owner_password_hash: "${config.owner_password_hash}"`);
   }

package/src/content-range-routes.test.ts

@@ -0,0 +1,178 @@
+/**
+ * REST face of content range / pagination (bounded reads for large notes).
+ *
+ * Exercises all four GET shapes that accept `content_offset` /
+ * `content_length`:
+ *   - GET /notes?id=…           (single, folded into the collection route)
+ *   - GET /notes/:idOrPath      (single point read)
+ *   - GET /notes?…              (structured list)
+ *   - GET /notes?search=…       (full-text list)
+ *
+ * Slice mechanics (codepoint boundaries, reassembly invariant) are pinned
+ * in core/src/content-range.test.ts; this suite covers the HTTP wiring:
+ * param parsing, 400s, per-shape application, and the no-params
+ * regression. Fully sandboxed — in-memory SQLite, no daemon.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunStore } from "./vault-store.ts";
+import { handleNotes } from "./routes.ts";
+
+let db: Database;
+let store: BunStore;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new BunStore(db);
+});
+
+afterEach(() => {
+  db.close();
+});
+
+const BASE = "http://localhost/api";
+
+function get(path: string): Promise<Response> {
+  return handleNotes(new Request(`${BASE}/notes${path}`, { method: "GET" }), store, pathSub(path));
+}
+
+/** Extract the handleNotes subpath ("/<id>" for point reads, "" otherwise). */
+function pathSub(path: string): string {
+  const m = path.match(/^\/([^?/]+)/);
+  return m ? `/${m[1]}` : "";
+}
+
+describe("REST content range — single note", () => {
+  it("GET /notes?id=… honors content_length and adds the range fields", async () => {
+    const note = await store.createNote("0123456789");
+    const res = await get(`?id=${note.id}&content_length=4`);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.content).toBe("0123");
+    expect(body.content_offset).toBe(0);
+    expect(body.content_total_length).toBe(10);
+    expect(body.content_next_offset).toBe(4);
+  });
+
+  it("GET /notes/:id honors content_offset (tail read to the end)", async () => {
+    const note = await store.createNote("hello world", { path: "tail-note" });
+    const res = await get(`/${note.id}?content_offset=6`);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.content).toBe("world");
+    expect(body.content_total_length).toBe(11);
+    expect(body.content_next_offset).toBeNull();
+  });
+
+  it("paged loop over REST reassembles multi-byte content byte-identically", async () => {
+    const content = "ab\u{1F600}cd 你好 ".repeat(20).trim();
+    const note = await store.createNote(content);
+    let offset = 0;
+    let assembled = "";
+    for (;;) {
+      const res = await get(`/${note.id}?content_offset=${offset}&content_length=16`);
+      expect(res.status).toBe(200);
+      const body: any = await res.json();
+      expect(Buffer.byteLength(body.content, "utf8")).toBeLessThanOrEqual(16);
+      assembled += body.content;
+      if (body.content_next_offset === null) break;
+      offset = body.content_next_offset;
+    }
+    expect(assembled).toBe(content);
+  });
+
+  it("offset past end → 200 with empty slice and null next_offset", async () => {
+    const note = await store.createNote("abc");
+    const res = await get(`?id=${note.id}&content_offset=500`);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.content).toBe("");
+    expect(body.content_next_offset).toBeNull();
+    expect(body.content_total_length).toBe(3);
+  });
+
+  it("include_content=false + range params → 400 INVALID_QUERY", async () => {
+    const note = await store.createNote("abc");
+    const res = await get(`?id=${note.id}&include_content=false&content_length=8`);
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.code).toBe("INVALID_QUERY");
+    expect(body.error).toContain("include_content");
+  });
+
+  it("zero / sub-minimum / malformed budgets → 400 INVALID_QUERY", async () => {
+    const note = await store.createNote("abc");
+    for (const qs of ["content_length=0", "content_length=2", "content_length=abc", "content_offset=-1"]) {
+      const res = await get(`?id=${note.id}&${qs}`);
+      expect(res.status).toBe(400);
+      const body: any = await res.json();
+      expect(body.code).toBe("INVALID_QUERY");
+    }
+  });
+
+  it("no range params → response shape unchanged (regression)", async () => {
+    const note = await store.createNote("plain body", { path: "plain" });
+    const res = await get(`/${note.id}`);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.content).toBe("plain body");
+    expect("content_total_length" in body).toBe(false);
+    expect("content_next_offset" in body).toBe(false);
+    expect("content_offset" in body).toBe(false);
+  });
+});
+
+describe("REST content range — list shapes", () => {
+  it("structured list with include_content=true applies the window per note", async () => {
+    await store.createNote("first body first body", { tags: ["paged"] });
+    await store.createNote("second body second body", { tags: ["paged"] });
+    const res = await get(`?tag=paged&include_content=true&content_length=6`);
+    expect(res.status).toBe(200);
+    const body: any[] = await res.json();
+    expect(body.length).toBe(2);
+    for (const n of body) {
+      expect(Buffer.byteLength(n.content, "utf8")).toBeLessThanOrEqual(6);
+      expect(typeof n.content_total_length).toBe("number");
+      expect(n.content_next_offset).toBe(6);
+    }
+  });
+
+  it("structured list on the lean default + range params → 400", async () => {
+    await store.createNote("body", { tags: ["paged"] });
+    const res = await get(`?tag=paged&content_length=8`);
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.code).toBe("INVALID_QUERY");
+    expect(body.error).toContain("include_content");
+  });
+
+  it("search list with include_content=true applies the window per note", async () => {
+    await store.createNote("the quick brown fox jumps over the lazy dog");
+    const res = await get(`?search=fox&include_content=true&content_length=9`);
+    expect(res.status).toBe(200);
+    const body: any[] = await res.json();
+    expect(body.length).toBe(1);
+    expect(Buffer.byteLength(body[0].content, "utf8")).toBeLessThanOrEqual(9);
+    expect(body[0].content_total_length).toBe(
+      Buffer.byteLength("the quick brown fox jumps over the lazy dog", "utf8"),
+    );
+  });
+
+  it("search list on the lean default + range params → 400", async () => {
+    await store.createNote("the quick brown fox");
+    const res = await get(`?search=fox&content_length=8`);
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.code).toBe("INVALID_QUERY");
+  });
+
+  it("list without range params → no range fields injected (regression)", async () => {
+    await store.createNote("body here", { tags: ["paged"] });
+    const res = await get(`?tag=paged&include_content=true`);
+    expect(res.status).toBe(200);
+    const body: any[] = await res.json();
+    expect("content_total_length" in body[0]).toBe(false);
+    expect("content_next_offset" in body[0]).toBe(false);
+  });
+});

package/src/export-watch.test.ts

@@ -35,6 +35,7 @@ import {
   runGitCommitCycle,
   shouldCommit,
 } from "./export-watch.ts";
+import { GitNotInstalledError } from "./git-preflight.ts";
 
 const CLI = path.resolve(import.meta.dir, "cli.ts");
 
@@ -504,6 +505,28 @@ describe("runGitCommitCycle", () => {
     });
     expect(result.message).toBe("note: Inbox/DonorMeeting");
   });
+
+  test("git missing → throws GitNotInstalledError (sync surfaces friendly error, not raw spawn crash)", async () => {
+    // vault#415 — the sync/commit path must surface the actionable
+    // git-not-installed message (which the manager threads into
+    // status.last_error) instead of crashing with a raw "Executable not
+    // found in $PATH". Force the preflight to see no git via the `which`
+    // seam; no real spawn should be reached.
+    fs.writeFileSync(path.join(dir, "Note.md"), "# n\n");
+    await expect(
+      runGitCommitCycle({
+        repoDir: dir,
+        template: DEFAULT_COMMIT_TEMPLATE,
+        notesChanged: 1,
+        vaultName: "default",
+        firstNoteTitle: "Note",
+        push: false,
+        which: () => null,
+      }),
+    ).rejects.toBeInstanceOf(GitNotInstalledError);
+    // The commit cycle bailed at the preflight — no commit landed.
+    expect(gitLogOneline(dir)).toHaveLength(1); // only the seed
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/export-watch.ts

@@ -13,6 +13,8 @@
  * detection. See `parachute-patterns/cookbook/vault-portable-export.md`.
  */
 
+import { ensureGitAvailable } from "./git-preflight.ts";
+
 // ---------------------------------------------------------------------------
 // Commit message templating
 // ---------------------------------------------------------------------------
@@ -269,11 +271,23 @@ export async function runGitCommitCycle(opts: {
   push: boolean;
   /** Override for tests — defaults to `new Date().toISOString()`. */
   now?: () => string;
+  /**
+   * Override the git-presence probe (test seam — defaults to `Bun.which`).
+   * Inject a fn returning `null` to exercise the git-not-installed path.
+   */
+  which?: (cmd: string) => string | null;
 }): Promise<{
   committed: boolean;
   message?: string;
   push?: { attempted: true; ok: boolean; error?: string };
 }> {
+  // Preflight: every step below shells `git`. On a git-less server the first
+  // `Bun.spawn(["git", ...])` would throw a raw "Executable not found" error;
+  // surface the friendly, actionable GitNotInstalledError so callers can
+  // thread it into mirror status (`last_error`) instead of crashing the
+  // watch loop with an opaque message.
+  ensureGitAvailable(opts.which);
+
   const now = opts.now ?? (() => new Date().toISOString());
 
   const add = await gitAddAll(opts.repoDir);