@openparachute/vault 0.1.0

package/core/src/paths.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { normalizePath, pathTitle, hasInvalidChars } from "./paths.js";
+
+// ---------------------------------------------------------------------------
+// Path normalization
+// ---------------------------------------------------------------------------
+
+describe("normalizePath", () => {
+  it("passes through simple paths", () => {
+    expect(normalizePath("Projects/README")).toBe("Projects/README");
+  });
+
+  it("strips .md extension", () => {
+    expect(normalizePath("Note.md")).toBe("Note");
+    expect(normalizePath("Projects/README.md")).toBe("Projects/README");
+    expect(normalizePath("Note.MD")).toBe("Note");
+  });
+
+  it("strips leading/trailing slashes", () => {
+    expect(normalizePath("/Projects/README")).toBe("Projects/README");
+    expect(normalizePath("Projects/README/")).toBe("Projects/README");
+  });
+
+  it("collapses multiple slashes", () => {
+    expect(normalizePath("Projects//Parachute///README")).toBe("Projects/Parachute/README");
+  });
+
+  it("converts backslashes to forward slashes", () => {
+    expect(normalizePath("Projects\\Parachute\\README")).toBe("Projects/Parachute/README");
+  });
+
+  it("trims whitespace", () => {
+    expect(normalizePath("  My Note  ")).toBe("My Note");
+  });
+
+  it("returns null for empty/whitespace", () => {
+    expect(normalizePath("")).toBeNull();
+    expect(normalizePath("   ")).toBeNull();
+    expect(normalizePath(null)).toBeNull();
+    expect(normalizePath(undefined)).toBeNull();
+  });
+
+  it("returns null for just .md", () => {
+    expect(normalizePath(".md")).toBeNull();
+  });
+});
+
+describe("pathTitle", () => {
+  it("returns last segment", () => {
+    expect(pathTitle("Projects/Parachute/README")).toBe("README");
+  });
+
+  it("returns the path itself when no slashes", () => {
+    expect(pathTitle("Grocery List")).toBe("Grocery List");
+  });
+});
+
+describe("hasInvalidChars", () => {
+  it("detects forbidden characters", () => {
+    expect(hasInvalidChars("Note*")).toBe(true);
+    expect(hasInvalidChars("Note<1>")).toBe(true);
+    expect(hasInvalidChars('Note"quoted"')).toBe(true);
+  });
+
+  it("allows valid characters", () => {
+    expect(hasInvalidChars("My Note")).toBe(false);
+    expect(hasInvalidChars("Projects/Parachute/README")).toBe(false);
+    expect(hasInvalidChars("2026-04-06")).toBe(false);
+    expect(hasInvalidChars("note_with-dashes")).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Path uniqueness
+// ---------------------------------------------------------------------------
+
+describe("path uniqueness", () => {
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("allows multiple notes without paths", () => {
+    store.createNote("A");
+    store.createNote("B");
+    // Both should exist
+    const notes = store.queryNotes({ limit: 10 });
+    expect(notes).toHaveLength(2);
+  });
+
+  it("rejects duplicate paths", () => {
+    store.createNote("A", { path: "My Note" });
+    expect(() => store.createNote("B", { path: "My Note" })).toThrow();
+  });
+
+  it("normalizes before checking uniqueness", () => {
+    store.createNote("A", { path: "My Note.md" });
+    // "My Note.md" normalizes to "My Note" — should conflict
+    expect(() => store.createNote("B", { path: "My Note" })).toThrow();
+  });
+
+  it("allows different paths", () => {
+    store.createNote("A", { path: "Note A" });
+    store.createNote("B", { path: "Note B" });
+    expect(store.getNoteByPath("Note A")).toBeTruthy();
+    expect(store.getNoteByPath("Note B")).toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Path normalization in store operations
+// ---------------------------------------------------------------------------
+
+describe("path normalization in store", () => {
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("normalizes path on create", () => {
+    const note = store.createNote("Test", { path: "  Projects//README.md  " });
+    expect(note.path).toBe("Projects/README");
+  });
+
+  it("normalizes path on update", () => {
+    const note = store.createNote("Test", { path: "Old Path" });
+    const updated = store.updateNote(note.id, { path: "New Path.md" });
+    expect(updated.path).toBe("New Path");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Rename cascading
+// ---------------------------------------------------------------------------
+
+describe("rename cascading", () => {
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("updates wikilinks in other notes when path changes", () => {
+    const target = store.createNote("I am the target", { path: "Old Name" });
+    const source = store.createNote("See [[Old Name]] for details.");
+
+    // Verify link exists
+    expect(store.getLinks(source.id, { direction: "outbound" })).toHaveLength(1);
+
+    // Rename the target
+    store.updateNote(target.id, { path: "New Name" });
+
+    // Source content should be updated
+    const updatedSource = store.getNote(source.id)!;
+    expect(updatedSource.content).toBe("See [[New Name]] for details.");
+
+    // Link should still work
+    const links = store.getLinks(source.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0].targetId).toBe(target.id);
+  });
+
+  it("updates aliased wikilinks", () => {
+    const target = store.createNote("Target", { path: "Old" });
+    const source = store.createNote("See [[Old|click here]] for info.");
+
+    store.updateNote(target.id, { path: "New" });
+
+    const updated = store.getNote(source.id)!;
+    expect(updated.content).toBe("See [[New|click here]] for info.");
+  });
+
+  it("updates wikilinks with anchors", () => {
+    const target = store.createNote("Target", { path: "Old" });
+    const source = store.createNote("See [[Old#Section]].");
+
+    store.updateNote(target.id, { path: "New" });
+
+    const updated = store.getNote(source.id)!;
+    expect(updated.content).toBe("See [[New#Section]].");
+  });
+
+  it("does not update unrelated wikilinks", () => {
+    store.createNote("Target", { path: "Old" });
+    const other = store.createNote("Other", { path: "Other" });
+    const source = store.createNote("See [[Other]] and [[Old]].");
+
+    store.updateNote(store.getNoteByPath("Old")!.id, { path: "New" });
+
+    const updated = store.getNote(source.id)!;
+    expect(updated.content).toBe("See [[Other]] and [[New]].");
+  });
+});

package/core/src/paths.ts

@@ -0,0 +1,53 @@
+/**
+ * Path normalization and validation for Obsidian interop.
+ *
+ * Conventions:
+ *   - No .md extension (stored without, added on export)
+ *   - No leading/trailing slashes
+ *   - Forward slashes only (no backslash)
+ *   - Collapse multiple slashes
+ *   - Trim whitespace
+ *   - Paths are nullable (not all notes need them)
+ *   - Paths are unique when set (enforced at DB level)
+ */
+
+/**
+ * Normalize a note path for storage.
+ * Returns null if the path is empty after normalization.
+ */
+export function normalizePath(path: string | null | undefined): string | null {
+  if (path === null || path === undefined) return null;
+
+  let p = path
+    .trim()
+    .replace(/\\/g, "/")          // backslash → forward slash
+    .replace(/\.md$/i, "")         // strip .md extension
+    .replace(/\/+/g, "/")          // collapse multiple slashes
+    .replace(/^\//, "")            // no leading slash
+    .replace(/\/$/, "");           // no trailing slash
+
+  if (p === "") return null;
+  return p;
+}
+
+/**
+ * Extract the display title from a path.
+ * Returns the last segment (filename without folders).
+ *
+ * "Projects/Parachute/README" → "README"
+ * "Grocery List" → "Grocery List"
+ */
+export function pathTitle(path: string): string {
+  const segments = path.split("/");
+  return segments[segments.length - 1];
+}
+
+/**
+ * Characters forbidden in Obsidian filenames.
+ * We don't enforce this strictly — just provide a check for import/export.
+ */
+const FORBIDDEN_CHARS = /[*"<>:|?]/;
+
+export function hasInvalidChars(path: string): boolean {
+  return FORBIDDEN_CHARS.test(path);
+}

package/core/src/schema.ts

@@ -0,0 +1,331 @@
+import { Database } from "bun:sqlite";
+import { normalizePath } from "./paths.js";
+
+export const SCHEMA_VERSION = 8;
+
+export const SCHEMA_SQL = `
+-- Notes: the universal record
+CREATE TABLE IF NOT EXISTS notes (
+  id TEXT PRIMARY KEY,
+  content TEXT DEFAULT '',
+  path TEXT,
+  metadata TEXT DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT
+);
+
+-- Tags: flat labels
+CREATE TABLE IF NOT EXISTS tags (
+  name TEXT PRIMARY KEY
+);
+
+-- Note-Tag join
+CREATE TABLE IF NOT EXISTS note_tags (
+  note_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+  tag_name TEXT NOT NULL REFERENCES tags(name),
+  PRIMARY KEY (note_id, tag_name)
+);
+
+-- Attachments: files associated with notes
+CREATE TABLE IF NOT EXISTS attachments (
+  id TEXT PRIMARY KEY,
+  note_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+  path TEXT NOT NULL,
+  mime_type TEXT NOT NULL,
+  metadata TEXT DEFAULT '{}',
+  created_at TEXT NOT NULL
+);
+
+-- Links: directed relationships between notes
+CREATE TABLE IF NOT EXISTS links (
+  source_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+  target_id TEXT NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
+  relationship TEXT NOT NULL,
+  metadata TEXT DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  UNIQUE(source_id, target_id, relationship)
+);
+
+-- Tag schemas: optional metadata schema per tag
+CREATE TABLE IF NOT EXISTS tag_schemas (
+  tag_name TEXT PRIMARY KEY REFERENCES tags(name) ON DELETE CASCADE,
+  description TEXT,
+  fields TEXT -- JSON: { "field_name": { "type": "string", "description": "..." }, ... }
+);
+
+-- Tokens: API authentication with scoped permissions
+CREATE TABLE IF NOT EXISTS tokens (
+  token_hash TEXT PRIMARY KEY,
+  label TEXT NOT NULL,
+  permission TEXT NOT NULL DEFAULT 'admin',
+  scope_tag TEXT,
+  scope_path_prefix TEXT,
+  expires_at TEXT,
+  created_at TEXT NOT NULL,
+  last_used_at TEXT
+);
+
+-- OAuth: registered clients (Dynamic Client Registration)
+CREATE TABLE IF NOT EXISTS oauth_clients (
+  client_id TEXT PRIMARY KEY,
+  client_name TEXT,
+  redirect_uris TEXT,
+  created_at TEXT NOT NULL
+);
+
+-- OAuth: authorization codes (single-use, short-lived)
+CREATE TABLE IF NOT EXISTS oauth_codes (
+  code TEXT PRIMARY KEY,
+  client_id TEXT NOT NULL,
+  code_challenge TEXT NOT NULL,
+  code_challenge_method TEXT NOT NULL DEFAULT 'S256',
+  scope TEXT NOT NULL DEFAULT 'full',
+  redirect_uri TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  used INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL
+);
+
+-- Schema version tracking
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY,
+  applied_at TEXT NOT NULL
+);
+
+-- Full-text search on note content
+CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
+  content,
+  content='notes',
+  content_rowid='rowid'
+);
+
+-- FTS triggers
+CREATE TRIGGER IF NOT EXISTS notes_fts_insert AFTER INSERT ON notes BEGIN
+  INSERT INTO notes_fts(rowid, content) VALUES (new.rowid, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS notes_fts_delete AFTER DELETE ON notes BEGIN
+  INSERT INTO notes_fts(notes_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS notes_fts_update AFTER UPDATE OF content ON notes BEGIN
+  INSERT INTO notes_fts(notes_fts, rowid, content) VALUES('delete', old.rowid, old.content);
+  INSERT INTO notes_fts(rowid, content) VALUES (new.rowid, new.content);
+END;
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_notes_created ON notes(created_at);
+CREATE INDEX IF NOT EXISTS idx_notes_path ON notes(path) WHERE path IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_note_tags_note ON note_tags(note_id, tag_name);
+CREATE INDEX IF NOT EXISTS idx_note_tags_tag ON note_tags(tag_name, note_id);
+CREATE INDEX IF NOT EXISTS idx_attachments_note ON attachments(note_id);
+CREATE INDEX IF NOT EXISTS idx_links_source ON links(source_id);
+CREATE INDEX IF NOT EXISTS idx_links_target ON links(target_id);
+`;
+
+/**
+ * Initialize database schema. Idempotent — safe to call on every startup.
+ */
+export function initSchema(db: Database): void {
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+
+  // Check if we need to migrate from v2
+  const hasOldTables = hasTable(db, "things");
+  if (hasOldTables) {
+    migrateFromV2(db);
+  }
+
+  db.exec(SCHEMA_SQL);
+
+  // Migrate v3 → v4: add metadata columns
+  migrateToV4(db);
+
+  // Migrate v4 → v5: unique path constraint
+  migrateToV5(db);
+
+  // Migrate v5 → v6: tag_schemas table (created by SCHEMA_SQL above,
+  // this just ensures the table exists for databases created before v6)
+  migrateToV6(db);
+
+  // Migrate v6 → v7: tokens table (created by SCHEMA_SQL above,
+  // this just ensures the table exists for databases created before v7)
+  migrateToV7(db);
+
+  // Migrate v7 → v8: OAuth tables (created by SCHEMA_SQL above,
+  // this just ensures the tables exist for databases created before v8)
+  migrateToV8(db);
+
+  // Record schema version
+  db.prepare("INSERT OR REPLACE INTO schema_version (version, applied_at) VALUES (?, ?)").run(
+    SCHEMA_VERSION,
+    new Date().toISOString(),
+  );
+}
+
+function hasColumn(db: Database, table: string, column: string): boolean {
+  const rows = db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[];
+  return rows.some((r) => r.name === column);
+}
+
+/**
+ * Migrate v3 → v4: add metadata JSON columns to notes and links.
+ */
+function migrateToV4(db: Database): void {
+  if (hasTable(db, "notes") && !hasColumn(db, "notes", "metadata")) {
+    db.exec("ALTER TABLE notes ADD COLUMN metadata TEXT DEFAULT '{}'");
+  }
+  if (hasTable(db, "links") && !hasColumn(db, "links", "metadata")) {
+    db.exec("ALTER TABLE links ADD COLUMN metadata TEXT DEFAULT '{}'");
+  }
+  if (hasTable(db, "attachments") && !hasColumn(db, "attachments", "metadata")) {
+    db.exec("ALTER TABLE attachments ADD COLUMN metadata TEXT DEFAULT '{}'");
+  }
+}
+
+/**
+ * Migrate v4 → v5: add UNIQUE constraint on path, normalize existing paths.
+ */
+function migrateToV5(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+
+  // Check if the unique index already exists
+  const indexes = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='index' AND name='idx_notes_path_unique'",
+  ).all();
+  if (indexes.length > 0) return;
+
+  // Normalize existing paths
+  const rows = db.prepare("SELECT id, path FROM notes WHERE path IS NOT NULL").all() as { id: string; path: string }[];
+  for (const row of rows) {
+    const normalized = normalizePath(row.path);
+    if (normalized !== row.path) {
+      db.prepare("UPDATE notes SET path = ? WHERE id = ?").run(normalized, row.id);
+    }
+  }
+
+  // Handle duplicate paths (can happen after normalization) — append note ID suffix
+  const dupes = db.prepare(`
+    SELECT path, GROUP_CONCAT(id) as ids FROM notes
+    WHERE path IS NOT NULL
+    GROUP BY path COLLATE NOCASE
+    HAVING COUNT(*) > 1
+  `).all() as { path: string; ids: string }[];
+  for (const dupe of dupes) {
+    const ids = dupe.ids.split(",");
+    // Keep first, rename the rest
+    for (let i = 1; i < ids.length; i++) {
+      const newPath = `${dupe.path}-${i}`;
+      db.prepare("UPDATE notes SET path = ? WHERE id = ?").run(newPath, ids[i]);
+    }
+  }
+
+  // Drop the old non-unique partial index and create a unique one
+  db.exec("DROP INDEX IF EXISTS idx_notes_path");
+  db.exec("CREATE UNIQUE INDEX idx_notes_path_unique ON notes(path) WHERE path IS NOT NULL");
+}
+
+/**
+ * Migrate v5 → v6: create tag_schemas table.
+ * The table is already in SCHEMA_SQL so it's created for new vaults.
+ * This migration handles existing vaults that were created before v6.
+ */
+function migrateToV6(db: Database): void {
+  // SCHEMA_SQL already creates the table via CREATE TABLE IF NOT EXISTS,
+  // so this is a no-op for new vaults. For existing vaults where SCHEMA_SQL
+  // ran above, the table now exists. Nothing extra needed here — the
+  // vault.yaml → DB migration happens at the server level (see server.ts),
+  // not at the core schema level, because core doesn't know about config files.
+}
+
+/**
+ * Migrate v6 → v7: create tokens table.
+ * The table is already in SCHEMA_SQL so it's created for new vaults.
+ * This migration handles existing vaults that were created before v7.
+ */
+function migrateToV7(db: Database): void {
+  // SCHEMA_SQL already creates the table via CREATE TABLE IF NOT EXISTS,
+  // so this is a no-op for new vaults. For existing vaults where SCHEMA_SQL
+  // ran above, the table now exists. Nothing extra needed here.
+}
+
+function migrateToV8(db: Database): void {
+  // SCHEMA_SQL already creates oauth_clients and oauth_codes via
+  // CREATE TABLE IF NOT EXISTS. Nothing extra needed here.
+}
+
+function hasTable(db: Database, name: string): boolean {
+  const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
+  return !!row;
+}
+
+/**
+ * Migrate from v2 (things/thing_tags/edges/tools) to v3 (notes/note_tags/links).
+ */
+function migrateFromV2(db: Database): void {
+  const alreadyMigrated = hasTable(db, "notes");
+  if (alreadyMigrated) return;
+
+  // Disable FK checks during migration to allow dropping tables freely
+  db.exec("PRAGMA foreign_keys = OFF");
+
+  // Drop old FTS, triggers, and tables that will be recreated with new schema
+  db.exec("DROP TRIGGER IF EXISTS things_fts_insert");
+  db.exec("DROP TRIGGER IF EXISTS things_fts_delete");
+  db.exec("DROP TRIGGER IF EXISTS things_fts_update");
+  db.exec("DROP TABLE IF EXISTS things_fts");
+
+  // Rename old tags table so we can create the new simplified one
+  // (old tags has display_name, schema_json, etc. — new one is just name)
+  db.exec("ALTER TABLE tags RENAME TO _old_tags");
+
+  // Create new tables
+  db.exec(SCHEMA_SQL);
+
+  // Migrate things → notes
+  db.exec(`
+    INSERT INTO notes (id, content, created_at, updated_at)
+    SELECT id, content, created_at, updated_at FROM things WHERE status = 'active'
+  `);
+
+  // Collect tag names from thing_tags, renaming known ones
+  // We insert into the new tags table (which only has a 'name' column)
+  db.exec(`
+    INSERT OR IGNORE INTO tags (name)
+    SELECT DISTINCT CASE
+      WHEN tag_name = 'note' THEN 'daily'
+      WHEN tag_name = 'daily-note' THEN 'daily'
+      ELSE tag_name
+    END
+    FROM thing_tags
+  `);
+
+  // Migrate thing_tags → note_tags
+  db.exec(`
+    INSERT OR IGNORE INTO note_tags (note_id, tag_name)
+    SELECT tt.thing_id, CASE
+      WHEN tt.tag_name = 'note' THEN 'daily'
+      WHEN tt.tag_name = 'daily-note' THEN 'daily'
+      ELSE tt.tag_name
+    END
+    FROM thing_tags tt
+    WHERE tt.thing_id IN (SELECT id FROM notes)
+  `);
+
+  // Migrate edges → links
+  db.exec(`
+    INSERT OR IGNORE INTO links (source_id, target_id, relationship, created_at)
+    SELECT source_id, target_id, relationship, created_at FROM edges
+    WHERE source_id IN (SELECT id FROM notes) AND target_id IN (SELECT id FROM notes)
+  `);
+
+  // Drop old tables
+  db.exec("DROP TABLE IF EXISTS thing_tags");
+  db.exec("DROP TABLE IF EXISTS edges");
+  db.exec("DROP TABLE IF EXISTS tools");
+  db.exec("DROP TABLE IF EXISTS things");
+  db.exec("DROP TABLE IF EXISTS _old_tags");
+
+  // Re-enable FK checks
+  db.exec("PRAGMA foreign_keys = ON");
+}