@openparachute/vault 0.1.0

package/core/src/store.ts

@@ -0,0 +1,303 @@
+import { Database } from "bun:sqlite";
+import type { Store, Note, Link, Attachment, QueryOpts } from "./types.js";
+import { initSchema } from "./schema.js";
+import * as noteOps from "./notes.js";
+import * as linkOps from "./links.js";
+import * as tagSchemaOps from "./tag-schemas.js";
+import { syncWikilinks, resolveUnresolvedWikilinks } from "./wikilinks.js";
+import { normalizePath, pathTitle } from "./paths.js";
+import { HookRegistry } from "./hooks.js";
+
+/**
+ * SQLite-backed Store implementation.
+ */
+export class SqliteStore implements Store {
+  public readonly hooks: HookRegistry;
+
+  constructor(public readonly db: Database, opts?: { hooks?: HookRegistry }) {
+    initSchema(db);
+    this.hooks = opts?.hooks ?? new HookRegistry();
+  }
+
+  // ---- Notes ----
+
+  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Note {
+    const note = noteOps.createNote(this.db, content, opts);
+
+    // Auto-sync wikilinks from content
+    if (content) {
+      syncWikilinks(this.db, note.id, content);
+    }
+
+    // If this note has a path, resolve any pending wikilinks targeting it
+    if (note.path) {
+      resolveUnresolvedWikilinks(this.db, note.path, note.id);
+    }
+
+    // Dispatch async hooks post-commit. Never blocks the caller.
+    this.hooks.dispatch("created", note, this);
+
+    return note;
+  }
+
+  getNote(id: string): Note | null {
+    return noteOps.getNote(this.db, id);
+  }
+
+  getNoteByPath(path: string): Note | null {
+    return noteOps.getNoteByPath(this.db, path);
+  }
+
+  getNotes(ids: string[]): Note[] {
+    return noteOps.getNotes(this.db, ids);
+  }
+
+  updateNote(id: string, updates: { content?: string; path?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean }): Note {
+    // Capture old path before update for rename cascading
+    let oldPath: string | undefined;
+    if (updates.path !== undefined) {
+      const existing = noteOps.getNote(this.db, id);
+      oldPath = existing?.path;
+    }
+
+    const note = noteOps.updateNote(this.db, id, updates);
+
+    // Re-sync wikilinks if content changed
+    if (updates.content !== undefined) {
+      syncWikilinks(this.db, id, updates.content);
+    }
+
+    // If path changed, cascade rename through wikilinks in other notes
+    if (updates.path !== undefined && note.path) {
+      if (oldPath && oldPath !== note.path) {
+        this.cascadeRename(oldPath, note.path);
+      }
+      resolveUnresolvedWikilinks(this.db, note.path, id);
+    }
+
+    // Dispatch async hooks post-commit. Never blocks the caller.
+    this.hooks.dispatch("updated", note, this);
+
+    return note;
+  }
+
+  /**
+   * When a note is renamed, update [[wikilinks]] in other notes that referenced the old path.
+   * Matches both full path and basename references.
+   */
+  private cascadeRename(oldPath: string, newPath: string): void {
+    const oldTitle = pathTitle(oldPath);
+    const newTitle = pathTitle(newPath);
+
+    // Find notes whose content contains a likely wikilink to the old path
+    // Search for both the full old path and just the old basename
+    const candidates = this.db.prepare(`
+      SELECT id, content FROM notes
+      WHERE content LIKE ? OR content LIKE ?
+    `).all(`%[[${oldPath}%`, `%[[${oldTitle}%`) as { id: string; content: string }[];
+
+    for (const row of candidates) {
+      let updated = row.content;
+
+      // Replace [[OldPath...]] with [[NewPath...]] (preserving aliases and anchors)
+      updated = updated.replace(
+        new RegExp(`\\[\\[${escapeRegex(oldPath)}([#|\\]])`, "g"),
+        `[[${newPath}$1`,
+      );
+
+      // Replace [[OldTitle...]] with [[NewTitle...]] (basename references)
+      // Only if old title !== new title and old title !== old path (avoid double-replace)
+      if (oldTitle !== newTitle && oldTitle !== oldPath) {
+        updated = updated.replace(
+          new RegExp(`\\[\\[${escapeRegex(oldTitle)}([#|\\]])`, "g"),
+          `[[${newTitle}$1`,
+        );
+      }
+
+      if (updated !== row.content) {
+        // Call noteOps directly (not this.updateNote) to avoid recursive cascading.
+        // Only content changes here, so path normalization/cascading aren't needed.
+        noteOps.updateNote(this.db, row.id, { content: updated });
+        syncWikilinks(this.db, row.id, updated);
+      }
+    }
+  }
+
+  deleteNote(id: string): void {
+    noteOps.deleteNote(this.db, id);
+  }
+
+  queryNotes(opts: QueryOpts): Note[] {
+    return noteOps.queryNotes(this.db, opts);
+  }
+
+  searchNotes(query: string, opts?: { tags?: string[]; limit?: number }): Note[] {
+    return noteOps.searchNotes(this.db, query, opts);
+  }
+
+  // ---- Tags ----
+
+  tagNote(noteId: string, tags: string[]): void {
+    noteOps.tagNote(this.db, noteId, tags);
+  }
+
+  untagNote(noteId: string, tags: string[]): void {
+    noteOps.untagNote(this.db, noteId, tags);
+  }
+
+  listTags(): { name: string; count: number }[] {
+    return noteOps.listTags(this.db);
+  }
+
+  deleteTag(name: string): { deleted: boolean; notes_untagged: number } {
+    return noteOps.deleteTag(this.db, name);
+  }
+
+  // ---- Vault Stats ----
+
+  getVaultStats(opts?: { topTagsLimit?: number }) {
+    return noteOps.getVaultStats(this.db, opts);
+  }
+
+  // ---- Links ----
+
+  createLink(sourceId: string, targetId: string, relationship: string, metadata?: Record<string, unknown>): Link {
+    return linkOps.createLink(this.db, sourceId, targetId, relationship, metadata);
+  }
+
+  deleteLink(sourceId: string, targetId: string, relationship: string): void {
+    linkOps.deleteLink(this.db, sourceId, targetId, relationship);
+  }
+
+  getLinks(noteId: string, opts?: { direction?: "outbound" | "inbound" | "both" }): Link[] {
+    return linkOps.getLinks(this.db, noteId, opts);
+  }
+
+  listLinks(opts?: { noteId?: string; direction?: "outbound" | "inbound" | "both"; relationship?: string }): Link[] {
+    return linkOps.listLinks(this.db, opts);
+  }
+
+  // ---- Bulk Operations ----
+
+  createNotes(inputs: noteOps.BulkNoteInput[]): Note[] {
+    const notes = noteOps.createNotes(this.db, inputs);
+    // Dispatch hooks for each created note — AFTER the bulk transaction
+    // commits inside noteOps.createNotes. Dispatch itself is async-safe
+    // (queueMicrotask), so the loop returns immediately.
+    for (const note of notes) {
+      this.hooks.dispatch("created", note, this);
+    }
+    return notes;
+  }
+
+  batchTag(noteIds: string[], tags: string[]): number {
+    return noteOps.batchTag(this.db, noteIds, tags);
+  }
+
+  batchUntag(noteIds: string[], tags: string[]): number {
+    return noteOps.batchUntag(this.db, noteIds, tags);
+  }
+
+  // ---- Deeper Link Queries ----
+
+  traverseLinks(noteId: string, opts?: { max_depth?: number; relationship?: string }) {
+    return linkOps.traverseLinks(this.db, noteId, opts);
+  }
+
+  findPath(sourceId: string, targetId: string, opts?: { max_depth?: number }) {
+    return linkOps.findPath(this.db, sourceId, targetId, opts);
+  }
+
+  // ---- Tag Schemas ----
+
+  listTagSchemas() {
+    return tagSchemaOps.listTagSchemas(this.db);
+  }
+
+  getTagSchema(tag: string) {
+    return tagSchemaOps.getTagSchema(this.db, tag);
+  }
+
+  upsertTagSchema(tag: string, schema: { description?: string; fields?: Record<string, tagSchemaOps.TagFieldSchema> }) {
+    return tagSchemaOps.upsertTagSchema(this.db, tag, schema);
+  }
+
+  deleteTagSchema(tag: string) {
+    return tagSchemaOps.deleteTagSchema(this.db, tag);
+  }
+
+  getTagSchemaMap() {
+    return tagSchemaOps.getTagSchemaMap(this.db);
+  }
+
+  // ---- Batch Wikilink Sync ----
+
+  /**
+   * Create a note without triggering wikilink sync.
+   * Use this during bulk imports, then call syncAllWikilinks() after.
+   */
+  createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Note {
+    return noteOps.createNote(this.db, content, opts);
+  }
+
+  /**
+   * Sync wikilinks for all notes in the vault.
+   * Efficient for bulk imports — call once after importing all notes.
+   */
+  syncAllWikilinks(): { synced: number; totalAdded: number; totalRemoved: number } {
+    const allNotes = noteOps.queryNotes(this.db, { limit: 1000000 });
+    let synced = 0;
+    let totalAdded = 0;
+    let totalRemoved = 0;
+
+    for (const note of allNotes) {
+      if (!note.content) continue;
+      const result = syncWikilinks(this.db, note.id, note.content);
+      if (result.added > 0 || result.removed > 0) {
+        synced++;
+        totalAdded += result.added;
+        totalRemoved += result.removed;
+      }
+    }
+
+    return { synced, totalAdded, totalRemoved };
+  }
+
+  // ---- Attachments ----
+
+  addAttachment(noteId: string, filePath: string, mimeType: string, metadata?: Record<string, unknown>): Attachment {
+    const id = noteOps.generateId();
+    const now = new Date().toISOString();
+    const metadataJson = metadata ? JSON.stringify(metadata) : "{}";
+    this.db.prepare(
+      "INSERT INTO attachments (id, note_id, path, mime_type, metadata, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+    ).run(id, noteId, filePath, mimeType, metadataJson, now);
+
+    return { id, noteId, path: filePath, mimeType, metadata, createdAt: now };
+  }
+
+  getAttachments(noteId: string): Attachment[] {
+    const rows = this.db.prepare(
+      "SELECT * FROM attachments WHERE note_id = ? ORDER BY created_at",
+    ).all(noteId) as { id: string; note_id: string; path: string; mime_type: string; metadata: string | null; created_at: string }[];
+
+    return rows.map((r) => {
+      let metadata: Record<string, unknown> | undefined;
+      if (r.metadata && r.metadata !== "{}") {
+        try { metadata = JSON.parse(r.metadata); } catch {}
+      }
+      return {
+        id: r.id,
+        noteId: r.note_id,
+        path: r.path,
+        mimeType: r.mime_type,
+        metadata,
+        createdAt: r.created_at,
+      };
+    });
+  }
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/core/src/tag-schemas.ts

@@ -0,0 +1,104 @@
+/**
+ * Tag schema CRUD — DB-backed storage for tag metadata schemas.
+ *
+ * Each tag can optionally have a schema that describes expected metadata
+ * fields for notes with that tag. Schemas drive auto-population of defaults
+ * and soft warnings on create/tag operations.
+ */
+
+import { Database } from "bun:sqlite";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface TagFieldSchema {
+  type: string;
+  description?: string;
+  enum?: string[];
+}
+
+export interface TagSchema {
+  tag: string;
+  description?: string;
+  fields?: Record<string, TagFieldSchema>;
+}
+
+// DB row shape
+interface TagSchemaRow {
+  tag_name: string;
+  description: string | null;
+  fields: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// CRUD
+// ---------------------------------------------------------------------------
+
+/** List all tag schemas. */
+export function listTagSchemas(db: Database): TagSchema[] {
+  const rows = db.prepare("SELECT * FROM tag_schemas ORDER BY tag_name").all() as TagSchemaRow[];
+  return rows.map(rowToSchema);
+}
+
+/** Get a single tag's schema, or null if none defined. */
+export function getTagSchema(db: Database, tag: string): TagSchema | null {
+  const row = db.prepare("SELECT * FROM tag_schemas WHERE tag_name = ?").get(tag) as TagSchemaRow | undefined;
+  return row ? rowToSchema(row) : null;
+}
+
+/** Get all schemas as a lookup map (tag → schema). Used by schema effects. */
+export function getTagSchemaMap(db: Database): Record<string, { description?: string; fields?: Record<string, TagFieldSchema> }> {
+  const schemas = listTagSchemas(db);
+  const map: Record<string, { description?: string; fields?: Record<string, TagFieldSchema> }> = {};
+  for (const s of schemas) {
+    map[s.tag] = { description: s.description, fields: s.fields };
+  }
+  return map;
+}
+
+/**
+ * Create or replace a tag schema (upsert).
+ * Ensures the tag exists in the tags table first.
+ */
+export function upsertTagSchema(
+  db: Database,
+  tag: string,
+  schema: { description?: string; fields?: Record<string, TagFieldSchema> },
+): TagSchema {
+  // Ensure tag exists
+  db.prepare("INSERT OR IGNORE INTO tags (name) VALUES (?)").run(tag);
+
+  const fieldsJson = schema.fields ? JSON.stringify(schema.fields) : null;
+  db.prepare(`
+    INSERT INTO tag_schemas (tag_name, description, fields)
+    VALUES (?, ?, ?)
+    ON CONFLICT(tag_name) DO UPDATE SET
+      description = excluded.description,
+      fields = excluded.fields
+  `).run(tag, schema.description ?? null, fieldsJson);
+
+  return getTagSchema(db, tag)!;
+}
+
+/** Delete a tag's schema. Returns true if a schema was deleted. */
+export function deleteTagSchema(db: Database, tag: string): boolean {
+  const result = db.prepare("DELETE FROM tag_schemas WHERE tag_name = ?").run(tag);
+  return result.changes > 0;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToSchema(row: TagSchemaRow): TagSchema {
+  let fields: Record<string, TagFieldSchema> | undefined;
+  if (row.fields) {
+    try { fields = JSON.parse(row.fields); } catch {}
+  }
+  return {
+    tag: row.tag_name,
+    description: row.description ?? undefined,
+    fields,
+  };
+}

package/core/src/test-preload.ts

@@ -0,0 +1,8 @@
+// Isolate PARACHUTE_HOME so tests never touch the real ~/.parachute directory.
+// This must run before any `./config.ts` import resolves CONFIG_DIR.
+import { mkdtempSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+if (!process.env.PARACHUTE_HOME) {
+  process.env.PARACHUTE_HOME = mkdtempSync(join(tmpdir(), "parachute-test-home-"));
+}

package/core/src/types.ts

@@ -0,0 +1,140 @@
+// ---- Note ----
+
+export interface Note {
+  id: string;
+  content: string;
+  path?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string; // ISO-8601
+  updatedAt?: string;
+  tags?: string[];
+  links?: Link[];
+}
+
+// ---- Link ----
+
+export interface Link {
+  sourceId: string;
+  targetId: string;
+  relationship: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}
+
+// ---- Attachment ----
+
+export interface Attachment {
+  id: string;
+  noteId: string;
+  path: string;
+  mimeType: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}
+
+// ---- Vault Stats ----
+
+export interface VaultStats {
+  totalNotes: number;
+  earliestNote: { id: string; createdAt: string } | null;
+  latestNote: { id: string; createdAt: string } | null;
+  notesByMonth: { month: string; count: number }[];
+  topTags: { tag: string; count: number }[];
+  tagCount: number;
+}
+
+// ---- Query Options ----
+
+export interface QueryOpts {
+  tags?: string[];
+  tagMatch?: "all" | "any"; // "all" = must have ALL tags (default), "any" = must have ANY tag
+  excludeTags?: string[];
+  path?: string;        // exact path match (case-insensitive)
+  pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
+  metadata?: Record<string, unknown>; // filter by metadata values (exact match on each key)
+  dateFrom?: string;    // ISO date
+  dateTo?: string;      // ISO date
+  sort?: "asc" | "desc";
+  limit?: number;
+  offset?: number;
+}
+
+/** Note summary — everything except content. Used in link results. */
+export interface NoteSummary {
+  id: string;
+  path?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt?: string;
+  tags?: string[];
+}
+
+/**
+ * Lean note index entry — summary + byteSize + single-line preview.
+ * Used by query-notes (index mode), GET /notes (list default), and /graph.
+ */
+export interface NoteIndex {
+  id: string;
+  path?: string;
+  createdAt: string;
+  updatedAt?: string;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  byteSize: number;
+  preview: string;
+}
+
+/** Link with hydrated note summaries. */
+export interface HydratedLink extends Link {
+  sourceNote?: NoteSummary;
+  targetNote?: NoteSummary;
+}
+
+// ---- Store Interface ----
+
+export interface Store {
+  // Notes
+  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Note;
+  getNote(id: string): Note | null;
+  getNoteByPath(path: string): Note | null;
+  getNotes(ids: string[]): Note[];
+  updateNote(id: string, updates: { content?: string; path?: string; metadata?: Record<string, unknown>; skipUpdatedAt?: boolean }): Note;
+  deleteNote(id: string): void;
+  queryNotes(opts: QueryOpts): Note[];
+  searchNotes(query: string, opts?: { tags?: string[]; limit?: number }): Note[];
+
+  // Tags
+  tagNote(noteId: string, tags: string[]): void;
+  untagNote(noteId: string, tags: string[]): void;
+  listTags(): { name: string; count: number }[];
+  deleteTag(name: string): { deleted: boolean; notes_untagged: number };
+
+  // Vault stats (aggregate, read-only)
+  getVaultStats(opts?: { topTagsLimit?: number }): VaultStats;
+
+  // Links
+  createLink(sourceId: string, targetId: string, relationship: string, metadata?: Record<string, unknown>): Link;
+  deleteLink(sourceId: string, targetId: string, relationship: string): void;
+  getLinks(noteId: string, opts?: { direction?: "outbound" | "inbound" | "both" }): Link[];
+  listLinks(opts?: { noteId?: string; direction?: "outbound" | "inbound" | "both"; relationship?: string }): Link[];
+
+  // Bulk operations
+  createNotes(inputs: { content: string; id?: string; path?: string; tags?: string[] }[]): Note[];
+  batchTag(noteIds: string[], tags: string[]): number;
+  batchUntag(noteIds: string[], tags: string[]): number;
+
+  // Deeper link queries
+  traverseLinks(noteId: string, opts?: { max_depth?: number; relationship?: string }): { noteId: string; depth: number; relationship: string; direction: "outbound" | "inbound" }[];
+  findPath(sourceId: string, targetId: string, opts?: { max_depth?: number }): { path: string[]; relationships: string[] } | null;
+
+  // Tag schemas
+  listTagSchemas(): { tag: string; description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> }[];
+  getTagSchema(tag: string): { tag: string; description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> } | null;
+  upsertTagSchema(tag: string, schema: { description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> }): { tag: string; description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> };
+  deleteTagSchema(tag: string): boolean;
+  getTagSchemaMap(): Record<string, { description?: string; fields?: Record<string, { type: string; description?: string; enum?: string[] }> }>;
+
+  // Attachments
+  addAttachment(noteId: string, path: string, mimeType: string, metadata?: Record<string, unknown>): Attachment;
+  getAttachments(noteId: string): Attachment[];
+}