opentasks 0.0.1 → 0.0.2

package/dist/graph/GraphologyAdapter.js

@@ -0,0 +1,209 @@
+/**
+ * Graphology Adapter for OpenTasks
+ *
+ * Provides an in-memory graph layer over SQLite storage using Graphology.
+ * All traversal operations query this graph, while SQLite remains authoritative.
+ */
+import { randomUUID } from 'node:crypto';
+import { MultiDirectedGraph } from 'graphology';
+/**
+ * Implementation of GraphologyAdapter
+ */
+export class GraphologyAdapterImpl {
+    graph;
+    // Track edge IDs to graph edge keys for deletion
+    edgeIdToKey = new Map();
+    constructor() {
+        // Multi-edge directed graph supports multiple edges between same nodes
+        this.graph = new MultiDirectedGraph();
+    }
+    async loadFromStorage(storage) {
+        // Clear any existing data
+        this.clear();
+        // Load all nodes
+        const nodes = await storage.queryNodes({ limit: 10000 });
+        for (const node of nodes) {
+            this.addNodeToGraph(node);
+        }
+        // Load all edges - we need to query edges for all nodes
+        // Since Storage doesn't have a getAllEdges method, we'll query edges for each node
+        const processedEdges = new Set();
+        for (const node of nodes) {
+            const outEdges = await storage.getEdgesFrom(node.id);
+            for (const edge of outEdges) {
+                if (!processedEdges.has(edge.id)) {
+                    processedEdges.add(edge.id);
+                    this.addEdgeToGraph(edge);
+                }
+            }
+        }
+    }
+    onNodeCreated(node) {
+        this.addNodeToGraph(node);
+    }
+    onNodeUpdated(id, updates) {
+        const uri = this.idToUri(id);
+        if (!this.graph.hasNode(uri)) {
+            return;
+        }
+        const current = this.graph.getNodeAttributes(uri);
+        const updatedData = { ...current.data, ...updates };
+        this.graph.mergeNodeAttributes(uri, {
+            ...current,
+            title: updates.title ?? current.title,
+            status: updates.status ?? current.status,
+            priority: updates.priority ?? current.priority,
+            archived: updates.archived ?? current.archived,
+            data: updatedData,
+        });
+    }
+    onNodeDeleted(id) {
+        const uri = this.idToUri(id);
+        if (this.graph.hasNode(uri)) {
+            // Graphology automatically removes edges connected to deleted nodes
+            this.graph.dropNode(uri);
+        }
+    }
+    onEdgeCreated(edge) {
+        this.addEdgeToGraph(edge);
+    }
+    onEdgeDeleted(id) {
+        const graphKey = this.edgeIdToKey.get(id);
+        if (graphKey && this.graph.hasEdge(graphKey)) {
+            this.graph.dropEdge(graphKey);
+            this.edgeIdToKey.delete(id);
+        }
+    }
+    hydrateNode(uri, node) {
+        if (this.graph.hasNode(uri)) {
+            // Update existing node
+            this.graph.mergeNodeAttributes(uri, this.nodeToAttributes(node));
+        }
+        else {
+            // Add new node
+            this.graph.addNode(uri, this.nodeToAttributes(node));
+        }
+    }
+    hydrateEdges(uri, edges) {
+        for (const edge of edges) {
+            if (!this.edgeIdToKey.has(edge.id)) {
+                this.addEdgeToGraph(edge);
+            }
+        }
+    }
+    nodeToUri(node) {
+        // External nodes have their own URI
+        if (node.type === 'external' && node.uri) {
+            return node.uri;
+        }
+        // Native nodes use native:// scheme
+        return `native://${node.id}`;
+    }
+    hasNode(uri) {
+        return this.graph.hasNode(uri);
+    }
+    getNode(uri) {
+        if (!this.graph.hasNode(uri)) {
+            return null;
+        }
+        return this.graph.getNodeAttributes(uri);
+    }
+    getEdges(uri, direction = 'both') {
+        if (!this.graph.hasNode(uri)) {
+            return [];
+        }
+        const edges = [];
+        if (direction === 'in' || direction === 'both') {
+            for (const edgeKey of this.graph.inEdges(uri)) {
+                edges.push(this.graph.getEdgeAttributes(edgeKey));
+            }
+        }
+        if (direction === 'out' || direction === 'both') {
+            for (const edgeKey of this.graph.outEdges(uri)) {
+                edges.push(this.graph.getEdgeAttributes(edgeKey));
+            }
+        }
+        return edges;
+    }
+    clear() {
+        this.graph.clear();
+        this.edgeIdToKey.clear();
+    }
+    // === Private Helper Methods ===
+    addNodeToGraph(node) {
+        const uri = this.nodeToUri(node);
+        if (!this.graph.hasNode(uri)) {
+            this.graph.addNode(uri, this.nodeToAttributes(node));
+        }
+    }
+    addEdgeToGraph(edge) {
+        const fromUri = this.idToUri(edge.from_id);
+        const toUri = this.idToUri(edge.to_id);
+        // Ensure both nodes exist (create placeholder if needed)
+        if (!this.graph.hasNode(fromUri)) {
+            this.graph.addNode(fromUri, this.placeholderAttributes(edge.from_id));
+        }
+        if (!this.graph.hasNode(toUri)) {
+            this.graph.addNode(toUri, this.placeholderAttributes(edge.to_id));
+        }
+        const attributes = this.edgeToAttributes(edge);
+        const graphKey = this.graph.addEdge(fromUri, toUri, attributes);
+        this.edgeIdToKey.set(edge.id, graphKey);
+    }
+    nodeToAttributes(node) {
+        return {
+            id: node.id,
+            type: node.type,
+            title: node.title,
+            status: node.status,
+            priority: node.priority,
+            archived: node.archived,
+            cached_at: node.cached_at,
+            source: node.source,
+            data: node,
+        };
+    }
+    edgeToAttributes(edge) {
+        return {
+            id: edge.id,
+            type: edge.type,
+            source: edge.source,
+            cached_at: edge.cached_at,
+            metadata: edge.metadata,
+        };
+    }
+    placeholderAttributes(id) {
+        const now = new Date().toISOString();
+        return {
+            id,
+            type: 'external',
+            title: `Unresolved: ${id}`,
+            data: {
+                id,
+                uuid: randomUUID(),
+                type: 'external',
+                title: `Unresolved: ${id}`,
+                created_at: now,
+                updated_at: now,
+            },
+        };
+    }
+    /**
+     * Convert an ID to URI
+     * If it looks like a URI (contains ://), return as-is
+     * Otherwise, wrap in native:// scheme
+     */
+    idToUri(id) {
+        if (id.includes('://')) {
+            return id;
+        }
+        return `native://${id}`;
+    }
+}
+/**
+ * Create a new GraphologyAdapter instance
+ */
+export function createGraphologyAdapter() {
+    return new GraphologyAdapterImpl();
+}
+//# sourceMappingURL=GraphologyAdapter.js.map

package/dist/graph/GraphologyAdapter.js.map

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

package/dist/graph/HydratingFederatedGraph.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Hydrating Federated Graph for OpenTasks
+ *
+ * Extends FederatedGraph with provider federation, hydration, and caching.
+ * Fetches missing data on-demand from providers and caches it to SQLite.
+ */
+import type { StoredNode, StoredEdge } from '../schema/storage.js';
+import type { Storage } from '../storage/interface.js';
+import type { ProviderRegistry } from '../providers/types.js';
+import type { GraphologyAdapter, NodeURI } from './GraphologyAdapter.js';
+import type { FederatedGraph } from './FederatedGraph.js';
+import { FederatedGraphImpl } from './FederatedGraph.js';
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+    /** Default TTL in milliseconds (default: 5 minutes) */
+    defaultTTL: number;
+    /** Return stale data while refreshing in background */
+    staleWhileRevalidate: boolean;
+    /** Per-provider TTL overrides in milliseconds */
+    providerTTL: Record<string, number>;
+}
+/**
+ * Default cache configuration
+ */
+export declare const DEFAULT_CACHE_CONFIG: CacheConfig;
+/**
+ * Options for federated ready() query
+ */
+export interface FederatedReadyOptions {
+    /** Filter by node type */
+    type?: string;
+    /** Filter by status (default: 'open') */
+    status?: string;
+    /** Filter by tags (must have all) */
+    tags?: string[];
+    /** Filter by provider (e.g., 'native', 'beads') */
+    providers?: string[];
+    /** Maximum number of results */
+    limit?: number;
+}
+/**
+ * Resolved node with full data and edges
+ */
+export interface ResolvedNode {
+    /** Node URI */
+    uri: NodeURI;
+    /** Provider that owns this node */
+    provider: string;
+    /** Full node data */
+    data: StoredNode;
+    /** Known edges */
+    edges: {
+        incoming: StoredEdge[];
+        outgoing: StoredEdge[];
+    };
+    /** Was this data from cache? */
+    cached: boolean;
+    /** When the data was cached (ISO 8601) */
+    cachedAt?: string;
+}
+/**
+ * Hydrating Federated Graph Interface
+ *
+ * Extends FederatedGraph with hydration and resolution methods.
+ */
+export interface HydratingFederatedGraph extends FederatedGraph {
+    /**
+     * Ensure a node and its edges are in the graph
+     * Fetches from provider if not present or stale
+     *
+     * @param uri - Node URI to hydrate
+     */
+    hydrate(uri: NodeURI): Promise<void>;
+    /**
+     * Resolve a URI to full node data
+     * Fetches from provider if not cached
+     *
+     * @param uri - Node URI
+     * @returns Resolved node or null if not found
+     */
+    resolve(uri: NodeURI): Promise<ResolvedNode | null>;
+    /**
+     * Batch resolve multiple URIs
+     *
+     * @param uris - Array of node URIs
+     * @returns Map of URI to resolved node
+     */
+    resolveAll(uris: NodeURI[]): Promise<Map<NodeURI, ResolvedNode>>;
+    /**
+     * Invalidate cached data for a provider
+     *
+     * @param providerName - Name of the provider
+     */
+    invalidateCache(providerName: string): Promise<void>;
+    /**
+     * Check if cached data for a node is stale
+     *
+     * @param uri - Node URI
+     * @returns True if the node needs refresh
+     */
+    isStale(uri: NodeURI): boolean;
+    /**
+     * Get nodes that are ready to work on (no active blockers)
+     *
+     * This is a federated query that considers blockers from all providers,
+     * including external systems like Beads or Jira.
+     *
+     * @param options - Query options (type, status, tags, providers, limit)
+     * @returns Array of ready node URIs
+     */
+    ready(options?: FederatedReadyOptions): Promise<NodeURI[]>;
+}
+/**
+ * Configuration for HydratingFederatedGraph
+ */
+export interface HydratingFederatedGraphConfig {
+    /** Storage for caching nodes and edges */
+    storage: Storage;
+    /** Provider registry for resolving URIs */
+    providerRegistry: ProviderRegistry;
+    /** Cache configuration */
+    cacheConfig?: Partial<CacheConfig>;
+}
+/**
+ * Implementation of HydratingFederatedGraph
+ */
+export declare class HydratingFederatedGraphImpl extends FederatedGraphImpl implements HydratingFederatedGraph {
+    private readonly storage;
+    private readonly providerRegistry;
+    private readonly cacheConfig;
+    constructor(adapter: GraphologyAdapter, config: HydratingFederatedGraphConfig);
+    hydrate(uri: NodeURI): Promise<void>;
+    resolve(uri: NodeURI): Promise<ResolvedNode | null>;
+    resolveAll(uris: NodeURI[]): Promise<Map<NodeURI, ResolvedNode>>;
+    invalidateCache(providerName: string): Promise<void>;
+    isStale(uri: NodeURI): boolean;
+    ready(options?: FederatedReadyOptions): Promise<NodeURI[]>;
+    private providerNodeToStoredNode;
+    private providerEdgeToStoredEdge;
+}
+/**
+ * Create a HydratingFederatedGraph instance
+ *
+ * @param adapter - The GraphologyAdapter to use
+ * @param config - Configuration including storage and provider registry
+ * @returns A HydratingFederatedGraph instance
+ */
+export declare function createHydratingFederatedGraph(adapter: GraphologyAdapter, config: HydratingFederatedGraphConfig): HydratingFederatedGraph;
+//# sourceMappingURL=HydratingFederatedGraph.d.ts.map

package/dist/graph/HydratingFederatedGraph.d.ts.map

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