@openparachute/vault 0.6.4 → 0.6.5-rc.10

package/core/src/schema.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
+import { transaction } from "./txn.js";
 
 export const SCHEMA_VERSION = 23;
 
@@ -680,8 +681,7 @@ function migrateToV13(db: Database): void {
 function migrateToV14(db: Database): void {
   if (!hasTable(db, "tags")) return;
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  const { copiedSchemas, copiedHierarchy } = transaction(db, () => {
     // 1. ALTER TABLE — additive, idempotent.
     const cols: [string, string][] = [
       ["description", "TEXT"],
@@ -762,16 +762,13 @@ function migrateToV14(db: Database): void {
       db.exec("DROP TABLE tag_schemas");
     }
 
-    db.exec("COMMIT");
+    return { copiedSchemas, copiedHierarchy };
+  });
 
-    if (copiedSchemas > 0 || copiedHierarchy > 0) {
-      console.log(
-        `[vault] migrated to schema v14: copied ${copiedSchemas} tag_schemas + ${copiedHierarchy} _tags/* hierarchies onto tags rows`,
-      );
-    }
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
+  if (copiedSchemas > 0 || copiedHierarchy > 0) {
+    console.log(
+      `[vault] migrated to schema v14: copied ${copiedSchemas} tag_schemas + ${copiedHierarchy} _tags/* hierarchies onto tags rows`,
+    );
   }
 }
 
@@ -806,8 +803,7 @@ function migrateToV15(db: Database): void {
   ).get()) !== null;
   if (hasSchemas || hasMappings) return;
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  const { copiedSchemas, copiedMappings } = transaction(db, () => {
     const now = new Date().toISOString();
     let copiedSchemas = 0;
     let copiedMappings = 0;
@@ -884,16 +880,13 @@ function migrateToV15(db: Database): void {
       }
     }
 
-    db.exec("COMMIT");
+    return { copiedSchemas, copiedMappings };
+  });
 
-    if (copiedSchemas > 0 || copiedMappings > 0) {
-      console.log(
-        `[vault] migrated to schema v15: copied ${copiedSchemas} _schemas/* + ${copiedMappings} _schema_defaults mappings into note_schemas/schema_mappings`,
-      );
-    }
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
+  if (copiedSchemas > 0 || copiedMappings > 0) {
+    console.log(
+      `[vault] migrated to schema v15: copied ${copiedSchemas} _schemas/* + ${copiedMappings} _schema_defaults mappings into note_schemas/schema_mappings`,
+    );
   }
 }
 
@@ -922,15 +915,10 @@ function migrateToV16(db: Database): void {
   // ALTER block so a fresh vault — where the column exists but the index
   // doesn't — still gets it.
   if (!hasColumn(db, "tokens", "vault_name")) {
-    db.exec("BEGIN IMMEDIATE");
-    try {
+    transaction(db, () => {
       db.exec("ALTER TABLE tokens ADD COLUMN vault_name TEXT");
       db.exec("CREATE INDEX IF NOT EXISTS idx_tokens_vault_name ON tokens(vault_name)");
-      db.exec("COMMIT");
-    } catch (err) {
-      db.exec("ROLLBACK");
-      throw err;
-    }
+    });
     return;
   }
 
@@ -980,8 +968,7 @@ function migrateToV17(db: Database): void {
     ).all() as { schema_name: string; match_kind: string; match_value: string }[];
   }
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  transaction(db, () => {
     // Drop the index first — the index references the table; SQLite would
     // tear it down on DROP TABLE but the explicit DROP keeps the order
     // obvious if a future migration reads from sqlite_master mid-flight.
@@ -993,11 +980,7 @@ function migrateToV17(db: Database): void {
     if (hasNoteSchemas) {
       db.exec("DROP TABLE note_schemas");
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   if (droppedSchemas.length > 0 || droppedMappings.length > 0) {
     const schemaNames = droppedSchemas.map((s) => s.name).join(", ");
@@ -1052,8 +1035,7 @@ function migrateToV18(db: Database): void {
   const hasNewUnique = indexes.some((r) => r.name === "idx_notes_path_ext_unique");
   if (!needsColumn && hasNewUnique && !hasOldUnique) return;
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  transaction(db, () => {
     if (needsColumn) {
       db.exec("ALTER TABLE notes ADD COLUMN extension TEXT NOT NULL DEFAULT 'md'");
     }
@@ -1065,11 +1047,7 @@ function migrateToV18(db: Database): void {
         "CREATE UNIQUE INDEX idx_notes_path_ext_unique ON notes(path, extension) WHERE path IS NOT NULL",
       );
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 }
 
 /**

package/core/src/seed-packs.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Content + registry pins for the named seed packs (core/src/seed-packs.ts).
+ *
+ * Pure content tests — no DB. The applier's behavior (idempotence, seeding)
+ * is exercised store-level in src/onboarding-seed.test.ts and CLI-level in
+ * src/add-pack.test.ts.
+ *
+ * The load-bearing pin: the `welcome` pack's tags must stay byte-equal to
+ * notes-ui's NOTES_REQUIRED_SCHEMA — the Notes PWA's connect-time audit
+ * compares `description` verbatim, and its schema banner only clears when the
+ * tags genuinely carry the semantics Notes declares. ONE tag since 2026-07-03:
+ * `#capture` only — entry method (text|voice) is note `metadata.source`
+ * provenance, not taxonomy (sibling notes-ui PR carries the client side).
+ */
+
+import { describe, test, expect } from "bun:test";
+import {
+  applySeedPack,
+  CONNECT_AI_PATH,
+  GETTING_STARTED_CONTENT,
+  GETTING_STARTED_PACK,
+  GETTING_STARTED_PATH,
+  getSeedPack,
+  listSeedPacks,
+  NOTES_REQUIRED_TAGS,
+  SEED_PACK_NAMES,
+  SURFACE_STARTER_CONTENT,
+  SURFACE_STARTER_PACK,
+  SURFACE_STARTER_PATH,
+  TRY_LINKING_PATH,
+  WELCOME_PATH,
+  welcomePack,
+} from "./seed-packs.ts";
+import * as onboardingShim from "./onboarding.ts";
+
+/**
+ * LITERAL copy of `NOTES_REQUIRED_SCHEMA.tags` from
+ * parachute-surface/packages/notes-ui/src/lib/vault/schema.ts — deliberately
+ * NOT imported (different repo; and the whole point is an independent copy
+ * that breaks this test when either side drifts). If this test fails, change
+ * notes-ui and the pack in lockstep, never one side alone.
+ */
+const NOTES_UI_REQUIRED_SCHEMA_TAGS = [
+  {
+    name: "capture",
+    description: "Notes captured directly by the user (text or voice).",
+  },
+];
+
+describe("welcome pack — notes-ui schema parity", () => {
+  test("welcome tags are byte-equal to notes-ui's NOTES_REQUIRED_SCHEMA", () => {
+    expect(NOTES_REQUIRED_TAGS).toEqual(NOTES_UI_REQUIRED_SCHEMA_TAGS);
+    expect(welcomePack().tags).toEqual(NOTES_UI_REQUIRED_SCHEMA_TAGS);
+    // Field-level byte pins (toEqual ignores key order; these don't).
+    for (const [i, expected] of NOTES_UI_REQUIRED_SCHEMA_TAGS.entries()) {
+      expect(NOTES_REQUIRED_TAGS[i]!.name).toBe(expected.name);
+      expect(NOTES_REQUIRED_TAGS[i]!.description).toBe(expected.description);
+    }
+  });
+
+  test("exactly ONE capture tag — no subtype tags, no parent_names (2026-07-03)", () => {
+    // Entry method is metadata.source (text|voice), not taxonomy. The old
+    // capture/text + capture/voice subtypes must not creep back into the seed
+    // (existing vaults carrying them stay valid — tags are user data).
+    expect(NOTES_REQUIRED_TAGS).toHaveLength(1);
+    expect(NOTES_REQUIRED_TAGS[0]!.name).toBe("capture");
+    expect(NOTES_REQUIRED_TAGS[0]!.parent_names).toBeUndefined();
+  });
+});
+
+describe("welcome pack — person-voiced welcome web", () => {
+  test("three notes forming a linked web (welcome ⇄ try-linking, connect-AI → welcome)", () => {
+    const pack = welcomePack();
+    expect(pack.name).toBe("welcome");
+    expect(pack.notes.map((n) => n.path)).toEqual([
+      WELCOME_PATH,
+      TRY_LINKING_PATH,
+      CONNECT_AI_PATH,
+    ]);
+
+    const [welcome, tryLinking, connectAi] = pack.notes;
+    expect(welcome!.content).toContain(`[[${TRY_LINKING_PATH}]]`);
+    expect(tryLinking!.content).toContain(`[[${WELCOME_PATH}]]`);
+    expect(connectAi!.content).toContain(`[[${WELCOME_PATH}]]`);
+  });
+
+  test("content with consoleOrigin is byte-equal to the cloud's welcome copy", () => {
+    // Pinned against parachute-cloud workers/vault/src/welcome.ts
+    // `welcomeNotes(consoleOrigin)` — the sibling cloud PR swaps that module
+    // for this pack, so the ported content must not drift.
+    const origin = "https://cloud.parachute.computer";
+    const pack = welcomePack({ consoleOrigin: origin });
+
+    expect(pack.notes[0]!.content).toBe(`# ${WELCOME_PATH}
+
+This vault is yours.
+Write anything.
+Notes can link to each other, like this: [[${TRY_LINKING_PATH}]].
+`);
+    expect(pack.notes[1]!.content).toBe(`# ${TRY_LINKING_PATH}
+
+Wrap a note's name in double square brackets to make a wikilink, like this one back to [[${WELCOME_PATH}]].
+`);
+    expect(pack.notes[2]!.content).toBe(`# ${CONNECT_AI_PATH}
+
+Your vault speaks MCP. Grab the connection URL from your console at ${origin}.
+Start from [[${WELCOME_PATH}]].
+`);
+  });
+
+  test("without consoleOrigin the Connect-AI line stays generic (no baked origin)", () => {
+    const connectAi = welcomePack().notes[2]!;
+    expect(connectAi.content).toContain(
+      "Your vault speaks MCP. Grab the connection URL from your console.",
+    );
+    expect(connectAi.content).not.toContain("undefined");
+    expect(connectAi.content).not.toContain("at .");
+  });
+});
+
+describe("getting-started pack", () => {
+  test("carries the doctrine note at the canonical path", () => {
+    expect(GETTING_STARTED_PACK.name).toBe("getting-started");
+    expect(GETTING_STARTED_PACK.tags).toEqual([]);
+    expect(GETTING_STARTED_PACK.notes).toEqual([
+      { path: GETTING_STARTED_PATH, content: GETTING_STARTED_CONTENT },
+    ]);
+  });
+
+  test("no dangling [[Surface Starter]] wikilink — points at the add-pack flow instead", () => {
+    // Surface Starter is out of the default seed (ratified 2026-07-02), so the
+    // default-seeded guide must not carry a wikilink to a note that doesn't
+    // exist. It names the pack + the way to add it.
+    expect(GETTING_STARTED_CONTENT).not.toContain("[[Surface Starter]]");
+    expect(GETTING_STARTED_CONTENT).toContain("Surface Starter");
+    expect(GETTING_STARTED_CONTENT).toContain("add-pack surface-starter");
+    // The surface packages are still named for discoverability.
+    expect(GETTING_STARTED_CONTENT).toContain("@openparachute/surface-client");
+    expect(GETTING_STARTED_CONTENT).toContain("@openparachute/surface-render");
+  });
+});
+
+describe("surface-starter pack", () => {
+  test("carries the surface guide at the canonical path (opt-in, not default)", () => {
+    expect(SURFACE_STARTER_PACK.name).toBe("surface-starter");
+    expect(SURFACE_STARTER_PACK.tags).toEqual([]);
+    expect(SURFACE_STARTER_PACK.notes).toEqual([
+      { path: SURFACE_STARTER_PATH, content: SURFACE_STARTER_CONTENT },
+    ]);
+    expect(SURFACE_STARTER_PACK.description).toContain("not seeded by default");
+  });
+
+  test("links back to Getting Started (default-seeded, so the wikilink resolves)", () => {
+    expect(SURFACE_STARTER_CONTENT).toContain("[[Getting Started]]");
+  });
+});
+
+describe("pack registry", () => {
+  test("lists exactly the three packs, in order", () => {
+    expect([...SEED_PACK_NAMES]).toEqual([
+      "welcome",
+      "getting-started",
+      "surface-starter",
+    ]);
+    expect(listSeedPacks().map((p) => p.name)).toEqual([...SEED_PACK_NAMES]);
+    for (const p of listSeedPacks()) {
+      expect(p.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("getSeedPack resolves each name and returns null for unknown", () => {
+    for (const name of SEED_PACK_NAMES) {
+      expect(getSeedPack(name)?.name).toBe(name);
+    }
+    expect(getSeedPack("nope")).toBeNull();
+    expect(getSeedPack("")).toBeNull();
+  });
+
+  test("applySeedPack is exported for both runtimes", () => {
+    expect(typeof applySeedPack).toBe("function");
+  });
+});
+
+describe("onboarding.ts back-compat shim", () => {
+  test("re-exports the canonical paths + contents from seed-packs", () => {
+    expect(onboardingShim.GETTING_STARTED_PATH).toBe(GETTING_STARTED_PATH);
+    expect(onboardingShim.GETTING_STARTED_CONTENT).toBe(GETTING_STARTED_CONTENT);
+    expect(onboardingShim.SURFACE_STARTER_PATH).toBe(SURFACE_STARTER_PATH);
+    expect(onboardingShim.SURFACE_STARTER_CONTENT).toBe(SURFACE_STARTER_CONTENT);
+  });
+});