opentasks 0.0.1 → 0.0.2

package/dist/storage/file-lock.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Advisory File Lock for JSONL Writes (Phase 2)
+ *
+ * Serializes write access to graph.jsonl across multiple processes.
+ * Uses fs.open with exclusive flag + lockfile pattern.
+ */
+/**
+ * Configuration for file lock
+ */
+export interface FileLockConfig {
+    /** Path to the lock file (e.g., ".opentasks/write.lock") */
+    lockPath: string;
+    /** Timeout for acquiring lock (ms) */
+    timeout?: number;
+    /** Retry interval (ms) */
+    retryInterval?: number;
+    /** Stale lock timeout (ms) — locks older than this are considered abandoned */
+    staleTimeout?: number;
+}
+/**
+ * Advisory file lock for serializing JSONL writes
+ *
+ * Uses a lock file with PID to detect stale locks.
+ */
+export declare class FileLock {
+    private readonly config;
+    private fd;
+    private acquired;
+    constructor(config: FileLockConfig);
+    /**
+     * Acquire the lock
+     *
+     * Blocks (with polling) until the lock is acquired or timeout expires.
+     *
+     * @throws Error if lock cannot be acquired within timeout
+     */
+    acquire(): Promise<void>;
+    /**
+     * Release the lock
+     */
+    release(): void;
+    /**
+     * Check if the current lock file is stale
+     */
+    private isStale;
+    /**
+     * Forcefully break a stale lock
+     */
+    private breakLock;
+    /**
+     * Whether the lock is currently held
+     */
+    get isLocked(): boolean;
+}
+/**
+ * Execute a function while holding a file lock
+ *
+ * Automatically acquires and releases the lock.
+ *
+ * @param lockPath - Path to the lock file
+ * @param fn - Function to execute while holding the lock
+ * @param timeout - Lock acquisition timeout (ms)
+ * @returns The return value of fn
+ */
+export declare function withFileLock<T>(lockPath: string, fn: () => Promise<T>, timeout?: number): Promise<T>;
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/storage/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../../src/storage/file-lock.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;;;GAIG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,EAAE,CAAuB;IACjC,OAAO,CAAC,QAAQ,CAAS;gBAEb,MAAM,EAAE,cAAc;IASlC;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgD9B;;OAEG;IACH,OAAO,IAAI,IAAI;IAqBf;;OAEG;IACH,OAAO,CAAC,OAAO;IAwBf;;OAEG;IACH,OAAO,CAAC,SAAS;IAQjB;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;CACF;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CASZ"}

package/dist/storage/file-lock.js

@@ -0,0 +1,176 @@
+/**
+ * Advisory File Lock for JSONL Writes (Phase 2)
+ *
+ * Serializes write access to graph.jsonl across multiple processes.
+ * Uses fs.open with exclusive flag + lockfile pattern.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_RETRY_INTERVAL = 50;
+const DEFAULT_STALE_TIMEOUT = 30000;
+/**
+ * Advisory file lock for serializing JSONL writes
+ *
+ * Uses a lock file with PID to detect stale locks.
+ */
+export class FileLock {
+    config;
+    fd = null;
+    acquired = false;
+    constructor(config) {
+        this.config = {
+            lockPath: config.lockPath,
+            timeout: config.timeout ?? DEFAULT_TIMEOUT,
+            retryInterval: config.retryInterval ?? DEFAULT_RETRY_INTERVAL,
+            staleTimeout: config.staleTimeout ?? DEFAULT_STALE_TIMEOUT,
+        };
+    }
+    /**
+     * Acquire the lock
+     *
+     * Blocks (with polling) until the lock is acquired or timeout expires.
+     *
+     * @throws Error if lock cannot be acquired within timeout
+     */
+    async acquire() {
+        if (this.acquired) {
+            throw new Error('Lock already acquired');
+        }
+        const dir = path.dirname(this.config.lockPath);
+        fs.mkdirSync(dir, { recursive: true });
+        const startTime = Date.now();
+        while (true) {
+            try {
+                // Try to create lock file exclusively
+                this.fd = fs.openSync(this.config.lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
+                // Write PID for stale detection
+                const content = `${process.pid}\n${Date.now()}\n`;
+                fs.writeSync(this.fd, content);
+                this.acquired = true;
+                return;
+            }
+            catch (error) {
+                if (error.code === 'EEXIST') {
+                    // Lock exists — check if it's stale
+                    if (this.isStale()) {
+                        this.breakLock();
+                        continue;
+                    }
+                    // Check timeout
+                    if (Date.now() - startTime >= this.config.timeout) {
+                        throw new Error(`Failed to acquire lock within ${this.config.timeout}ms: ${this.config.lockPath}`);
+                    }
+                    // Wait and retry
+                    await sleep(this.config.retryInterval);
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+    }
+    /**
+     * Release the lock
+     */
+    release() {
+        if (!this.acquired)
+            return;
+        try {
+            if (this.fd !== null) {
+                fs.closeSync(this.fd);
+                this.fd = null;
+            }
+        }
+        catch {
+            // Ignore close errors
+        }
+        try {
+            fs.unlinkSync(this.config.lockPath);
+        }
+        catch {
+            // Ignore unlink errors (file may already be removed)
+        }
+        this.acquired = false;
+    }
+    /**
+     * Check if the current lock file is stale
+     */
+    isStale() {
+        try {
+            const content = fs.readFileSync(this.config.lockPath, 'utf-8');
+            const lines = content.trim().split('\n');
+            const pid = parseInt(lines[0], 10);
+            const timestamp = parseInt(lines[1], 10);
+            // Check if the process is still running
+            if (pid && !isProcessRunning(pid)) {
+                return true;
+            }
+            // Check if the lock is too old
+            if (timestamp && Date.now() - timestamp > this.config.staleTimeout) {
+                return true;
+            }
+            return false;
+        }
+        catch {
+            // If we can't read the lock file, treat as stale
+            return true;
+        }
+    }
+    /**
+     * Forcefully break a stale lock
+     */
+    breakLock() {
+        try {
+            fs.unlinkSync(this.config.lockPath);
+        }
+        catch {
+            // Ignore
+        }
+    }
+    /**
+     * Whether the lock is currently held
+     */
+    get isLocked() {
+        return this.acquired;
+    }
+}
+/**
+ * Execute a function while holding a file lock
+ *
+ * Automatically acquires and releases the lock.
+ *
+ * @param lockPath - Path to the lock file
+ * @param fn - Function to execute while holding the lock
+ * @param timeout - Lock acquisition timeout (ms)
+ * @returns The return value of fn
+ */
+export async function withFileLock(lockPath, fn, timeout) {
+    const lock = new FileLock({ lockPath, timeout });
+    await lock.acquire();
+    try {
+        return await fn();
+    }
+    finally {
+        lock.release();
+    }
+}
+/**
+ * Check if a process is running
+ */
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=file-lock.js.map

package/dist/storage/file-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.js","sourceRoot":"","sources":["../../src/storage/file-lock.ts"],"names":[],"mappings":"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"}

package/dist/storage/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * OpenTasks Storage - Persistence interfaces and implementations
+ *
+ * @packageDocumentation
+ */
+export type { Storage, Transaction, NodeFilter, ResolvedNodeFilter } from './interface.js';
+export { resolveNodeFilter } from './interface.js';
+export { JSONLPersister, createJSONLPersister, type JSONLPersisterConfig, type LoadResult, } from './jsonl.js';
+export { SQLitePersister, createSQLitePersister, type SQLitePersisterConfig } from './sqlite.js';
+export { atomicWrite, appendToFile, fileExists, readFileOrEmpty } from './atomic-write.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGjG,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/storage/index.js

@@ -0,0 +1,13 @@
+/**
+ * OpenTasks Storage - Persistence interfaces and implementations
+ *
+ * @packageDocumentation
+ */
+export { resolveNodeFilter } from './interface.js';
+// JSONL Persister
+export { JSONLPersister, createJSONLPersister, } from './jsonl.js';
+// SQLite Persister
+export { SQLitePersister, createSQLitePersister } from './sqlite.js';
+// Utilities
+export { atomicWrite, appendToFile, fileExists, readFileOrEmpty } from './atomic-write.js';
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,kBAAkB;AAClB,OAAO,EACL,cAAc,EACd,oBAAoB,GAGrB,MAAM,YAAY,CAAC;AAEpB,mBAAmB;AACnB,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAA8B,MAAM,aAAa,CAAC;AAEjG,YAAY;AACZ,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/storage/interface.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Storage interface for OpenTasks
+ *
+ * Domain-driven storage interface following beads pattern.
+ * Defines operations for nodes, edges, tags, and queries.
+ */
+import type { StoredNode, StoredEdge } from '../schema/storage.js';
+import type { EdgeType } from '../schema/edges.js';
+/**
+ * Filter criteria for querying nodes
+ */
+export interface NodeFilter {
+    /** Filter by node type (single or multiple) */
+    type?: string | string[];
+    /** Filter by status (single or multiple) */
+    status?: string | string[];
+    /** Filter by tags (AND semantics - must have all) */
+    tags?: string[];
+    /** Filter by parent node */
+    parent_id?: string;
+    /** Filter by archived status */
+    archived?: boolean;
+    /** Full-text search in title and content */
+    search?: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Transaction interface for atomic operations
+ *
+ * Includes both read and write methods that work within a transaction context.
+ * Reads within a transaction see uncommitted writes from the same transaction.
+ */
+export interface Transaction {
+    /** Get a node by ID within transaction */
+    getNode(id: string): Promise<StoredNode | null>;
+    /** Get an edge by ID within transaction */
+    getEdge(id: string): Promise<StoredEdge | null>;
+    /** Get all tags for a node within transaction */
+    getTags(nodeId: string): Promise<string[]>;
+    /** Get all edges from a node within transaction */
+    getEdgesFrom(nodeId: string, type?: EdgeType): Promise<StoredEdge[]>;
+    /** Create a new node within transaction */
+    createNode(node: StoredNode, actor?: string): Promise<void>;
+    /** Update an existing node within transaction */
+    updateNode(id: string, updates: Partial<StoredNode>, actor?: string): Promise<void>;
+    /** Create a new edge within transaction */
+    createEdge(edge: StoredEdge, actor?: string): Promise<void>;
+    /** Delete an edge within transaction */
+    deleteEdge(id: string, actor?: string): Promise<void>;
+    /** Add a tag to a node within transaction */
+    addTag(nodeId: string, tag: string, actor?: string): Promise<void>;
+    /** Remove a tag from a node within transaction */
+    removeTag(nodeId: string, tag: string, actor?: string): Promise<void>;
+}
+/**
+ * Core storage interface for OpenTasks
+ *
+ * Provides domain-driven operations for nodes, edges, tags, and queries.
+ * Implementations: SQLitePersister (primary), JSONLPersister (for import/export)
+ */
+export interface Storage {
+    /**
+     * Create a new node
+     * @param node - The node to create (must include id, uuid, type, title)
+     * @param actor - Optional actor identifier for audit trail
+     */
+    createNode(node: StoredNode, actor?: string): Promise<void>;
+    /**
+     * Get a node by ID
+     * @param id - The node ID (e.g., "s-a2b3")
+     * @returns The node or null if not found
+     */
+    getNode(id: string): Promise<StoredNode | null>;
+    /**
+     * Update an existing node
+     * @param id - The node ID to update
+     * @param updates - Partial node with fields to update
+     * @param actor - Optional actor identifier for audit trail
+     */
+    updateNode(id: string, updates: Partial<StoredNode>, actor?: string): Promise<void>;
+    /**
+     * Delete a node
+     * @param id - The node ID to delete
+     * @param actor - Optional actor identifier for audit trail
+     */
+    deleteNode(id: string, actor?: string): Promise<void>;
+    /**
+     * Query nodes with filtering
+     * @param filter - Filter criteria
+     * @returns Matching nodes
+     */
+    queryNodes(filter: NodeFilter): Promise<StoredNode[]>;
+    /**
+     * Create a new edge
+     * @param edge - The edge to create
+     * @param actor - Optional actor identifier for audit trail
+     */
+    createEdge(edge: StoredEdge, actor?: string): Promise<void>;
+    /**
+     * Get an edge by ID
+     * @param id - The edge ID (e.g., "x-r8s9")
+     * @returns The edge or null if not found
+     */
+    getEdge(id: string): Promise<StoredEdge | null>;
+    /**
+     * Delete an edge
+     * @param id - The edge ID to delete
+     * @param actor - Optional actor identifier for audit trail
+     */
+    deleteEdge(id: string, actor?: string): Promise<void>;
+    /**
+     * Get all edges from a node
+     * @param nodeId - The source node ID
+     * @param type - Optional edge type filter
+     * @returns Edges where from_id matches
+     */
+    getEdgesFrom(nodeId: string, type?: EdgeType): Promise<StoredEdge[]>;
+    /**
+     * Get all edges to a node
+     * @param nodeId - The target node ID
+     * @param type - Optional edge type filter
+     * @returns Edges where to_id matches
+     */
+    getEdgesTo(nodeId: string, type?: EdgeType): Promise<StoredEdge[]>;
+    /**
+     * Add a tag to a node
+     * @param nodeId - The node ID
+     * @param tag - The tag to add
+     * @param actor - Optional actor identifier for audit trail
+     */
+    addTag(nodeId: string, tag: string, actor?: string): Promise<void>;
+    /**
+     * Remove a tag from a node
+     * @param nodeId - The node ID
+     * @param tag - The tag to remove
+     * @param actor - Optional actor identifier for audit trail
+     */
+    removeTag(nodeId: string, tag: string, actor?: string): Promise<void>;
+    /**
+     * Get all tags for a node
+     * @param nodeId - The node ID
+     * @returns Array of tag strings
+     */
+    getTags(nodeId: string): Promise<string[]>;
+    /**
+     * Get tags for multiple nodes (batch operation)
+     * @param nodeIds - Array of node IDs
+     * @returns Map of node ID to tags array
+     */
+    getTagsForNodes(nodeIds: string[]): Promise<Map<string, string[]>>;
+    /**
+     * Get all nodes with a specific tag
+     * @param tag - The tag to search for
+     * @returns Nodes that have this tag
+     */
+    getNodesByTag(tag: string): Promise<StoredNode[]>;
+    /**
+     * Get tasks that are ready to work on (no active blockers)
+     *
+     * A task is ready if:
+     * - type = 'task'
+     * - status = 'open'
+     * - not archived
+     * - no blocking tasks that are not closed
+     *
+     * @returns Ready tasks
+     */
+    getReady(): Promise<StoredNode[]>;
+    /**
+     * Execute a function within a transaction
+     *
+     * If the function throws, the transaction is rolled back.
+     * If the function completes, the transaction is committed.
+     *
+     * @param fn - Function to execute within transaction
+     * @returns The result of the function
+     */
+    runInTransaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    /**
+     * Mark a node as dirty (changed, needs export)
+     * @param nodeId - The node ID to mark
+     */
+    markDirty(nodeId: string): Promise<void>;
+    /**
+     * Get all dirty node IDs
+     * @returns Array of node IDs that have been modified
+     */
+    getDirtyNodes(): Promise<string[]>;
+    /**
+     * Clear dirty status for nodes (after export)
+     * @param nodeIds - Node IDs to clear
+     */
+    clearDirty(nodeIds: string[]): Promise<void>;
+    /**
+     * Close the storage connection and release resources
+     */
+    close(): Promise<void>;
+}
+/**
+ * Configuration for node filter with defaults applied
+ */
+export interface ResolvedNodeFilter {
+    type: string[] | null;
+    status: string[] | null;
+    tags: string[] | null;
+    parent_id: string | null;
+    archived: boolean | null;
+    search: string | null;
+    limit: number;
+    offset: number;
+}
+/**
+ * Resolve a NodeFilter to have consistent types and defaults
+ */
+export declare function resolveNodeFilter(filter: NodeFilter): ResolvedNodeFilter;
+//# sourceMappingURL=interface.d.ts.map

package/dist/storage/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/storage/interface.ts"],"names":[],"mappings":"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"}

package/dist/storage/interface.js

@@ -0,0 +1,22 @@
+/**
+ * Storage interface for OpenTasks
+ *
+ * Domain-driven storage interface following beads pattern.
+ * Defines operations for nodes, edges, tags, and queries.
+ */
+/**
+ * Resolve a NodeFilter to have consistent types and defaults
+ */
+export function resolveNodeFilter(filter) {
+    return {
+        type: filter.type ? (Array.isArray(filter.type) ? filter.type : [filter.type]) : null,
+        status: filter.status ? (Array.isArray(filter.status) ? filter.status : [filter.status]) : null,
+        tags: filter.tags || null,
+        parent_id: filter.parent_id || null,
+        archived: filter.archived ?? null,
+        search: filter.search || null,
+        limit: filter.limit || 100,
+        offset: filter.offset || 0,
+    };
+}
+//# sourceMappingURL=interface.js.map

package/dist/storage/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/storage/interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA6QH;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAkB;IAClD,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QACrF,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QAC/F,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI;QACzB,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;QACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,IAAI;QAC7B,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,GAAG;QAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC;KAC3B,CAAC;AACJ,CAAC"}

package/dist/storage/jsonl.d.ts

@@ -0,0 +1,106 @@
+/**
+ * JSONL Persister for OpenTasks
+ *
+ * Git-friendly JSONL storage as source of truth.
+ * Each line is a JSON object (node or edge).
+ */
+import type { StoredNode, StoredEdge } from '../schema/storage.js';
+/**
+ * Configuration for JSONL Persister
+ */
+export interface JSONLPersisterConfig {
+    /** Path to the JSONL file (e.g., ".opentasks/graph.jsonl") */
+    path: string;
+    /** Optional path for tombstones (soft deletes) */
+    tombstonesPath?: string;
+    /** Use atomic writes (default: true) */
+    atomicWrite?: boolean;
+}
+/**
+ * Result of loading a JSONL file
+ */
+export interface LoadResult {
+    nodes: StoredNode[];
+    edges: StoredEdge[];
+}
+/**
+ * JSONL Persister
+ *
+ * Handles reading/writing graph data to JSONL files.
+ * Source of truth for OpenTasks data.
+ */
+export declare class JSONLPersister {
+    private readonly config;
+    private watcher;
+    constructor(config: JSONLPersisterConfig);
+    /**
+     * Get the file path
+     */
+    get filePath(): string;
+    /**
+     * Check if the JSONL file exists
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Load the entire graph from JSONL
+     *
+     * Parses each line as JSON and separates nodes from edges.
+     * Invalid lines are skipped with a warning.
+     *
+     * @returns Object with nodes and edges arrays
+     */
+    load(): Promise<LoadResult>;
+    /**
+     * Save the entire graph to JSONL
+     *
+     * Overwrites the file with all nodes and edges.
+     * Uses atomic write by default (temp file + rename).
+     *
+     * @param nodes - All nodes to save
+     * @param edges - All edges to save
+     */
+    save(nodes: StoredNode[], edges: StoredEdge[]): Promise<void>;
+    /**
+     * Append a single entry to the JSONL file
+     *
+     * Useful for incremental writes without rewriting the entire file.
+     * Note: This can lead to duplicate entries; use save() for clean state.
+     *
+     * @param entry - Node or edge to append
+     */
+    append(entry: StoredNode | StoredEdge): Promise<void>;
+    /**
+     * Append multiple entries to the JSONL file
+     *
+     * @param entries - Nodes or edges to append
+     */
+    appendMany(entries: Array<StoredNode | StoredEdge>): Promise<void>;
+    /**
+     * Watch the JSONL file for external changes
+     *
+     * Calls the callback when the file is modified.
+     * Uses debouncing to avoid multiple calls for rapid changes.
+     *
+     * @param callback - Function to call on file change
+     * @returns Unsubscribe function
+     */
+    watch(callback: () => void): () => void;
+    /**
+     * Stop watching the file
+     */
+    stopWatching(): void;
+    /**
+     * Delete the JSONL file
+     *
+     * Use with caution - this removes all data.
+     */
+    delete(): Promise<void>;
+}
+/**
+ * Create a JSONL persister with default configuration
+ *
+ * @param basePath - Base directory (e.g., ".opentasks")
+ * @returns Configured JSONLPersister
+ */
+export declare function createJSONLPersister(basePath: string): JSONLPersister;
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/storage/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../../src/storage/jsonl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGnE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,wCAAwC;IACxC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAaD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,OAAO,CAA6B;gBAEhC,MAAM,EAAE,oBAAoB;IAQxC;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAIhC;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IA+BjC;;;;;;;;OAQG;IACG,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBnE;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3D;;;;OAIG;IACG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxE;;;;;;;;OAQG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IA0CvC;;OAEG;IACH,YAAY,IAAI,IAAI;IAOpB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAS9B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAMrE"}