opentasks 0.0.1 → 0.0.2

package/dist/materialization/snapshot.js

@@ -0,0 +1,177 @@
+/**
+ * Snapshot Assembly
+ *
+ * Builds self-contained MaterializationSnapshots from GraphStore nodes and edges.
+ * Snapshots contain everything needed to reconstruct the node in a fresh graph.
+ */
+import { resolveGitDir, getGitRemoteUrl, getGitBranch, getGitHead, } from './graph-id.js';
+// ============================================================================
+// Provenance Resolution
+// ============================================================================
+/**
+ * Build provenance metadata for a snapshot
+ */
+export function buildProvenance(options) {
+    const { graphId, opentasksPath } = options;
+    const gitDir = resolveGitDir(opentasksPath);
+    return {
+        graphId,
+        graphPath: opentasksPath,
+        gitRemote: gitDir ? (getGitRemoteUrl(gitDir) ?? undefined) : undefined,
+        gitBranch: gitDir ? (getGitBranch(gitDir) ?? undefined) : undefined,
+        gitHead: gitDir ? (getGitHead(gitDir) ?? undefined) : undefined,
+    };
+}
+// ============================================================================
+// Node URI Resolution
+// ============================================================================
+/**
+ * Resolve a graph node ID to its URI.
+ * External nodes have a URI directly; internal nodes use opentasks:// scheme.
+ */
+async function resolveNodeUri(nodeId, store) {
+    try {
+        const nodes = await store.query.nodes({
+            search: nodeId,
+            limit: 1,
+        });
+        if (nodes.length > 0) {
+            const node = nodes[0];
+            if (node.type === 'external' && node.uri) {
+                return node.uri;
+            }
+            return `opentasks://${node.id}`;
+        }
+    }
+    catch {
+        // Fall through
+    }
+    return `opentasks://${nodeId}`;
+}
+// ============================================================================
+// Edge Snapshot Building
+// ============================================================================
+/**
+ * Build portable edge snapshots from graph edges.
+ * Converts internal node IDs to URIs for cross-graph portability.
+ */
+export async function buildEdgeSnapshots(nodeId, store) {
+    const snapshots = [];
+    try {
+        // Get all edges involving this node (both directions)
+        const edges = await store.query.edges({ from_id: nodeId });
+        const incomingEdges = await store.query.edges({ to_id: nodeId });
+        const allEdges = [...edges, ...incomingEdges];
+        // Deduplicate by edge ID
+        const seen = new Set();
+        for (const edge of allEdges) {
+            if (seen.has(edge.id))
+                continue;
+            seen.add(edge.id);
+            const fromUri = await resolveNodeUri(edge.from_id, store);
+            const toUri = await resolveNodeUri(edge.to_id, store);
+            snapshots.push({
+                fromUri,
+                toUri,
+                edgeType: edge.type,
+                metadata: edge.metadata,
+            });
+        }
+    }
+    catch {
+        // Best-effort edge capture
+    }
+    return snapshots;
+}
+// ============================================================================
+// Snapshot Builders
+// ============================================================================
+/**
+ * Build a session snapshot from a session ExternalNode
+ */
+export async function buildSessionSnapshot(node, store, provenance) {
+    const edges = await buildEdgeSnapshots(node.id, store);
+    // Extract checkpoint IDs from 'contains' edges
+    const checkpointIds = edges
+        .filter((e) => e.edgeType === 'contains')
+        .map((e) => {
+        const match = e.toUri.match(/entire:\/\/checkpoint\/(.+)/);
+        return match ? match[1] : e.toUri;
+    });
+    return {
+        version: 1,
+        uri: node.uri,
+        source: node.source ?? 'entire',
+        entityType: 'session',
+        createdAt: node.created_at,
+        archivedAt: new Date().toISOString(),
+        node: {
+            title: node.title,
+            content: node.content,
+            status: node.status,
+            external_status: node.external_status,
+            external_data: node.external_data ?? node.metadata ?? {},
+            tags: node.tags,
+        },
+        provenance,
+        edges,
+        checkpointIds,
+    };
+}
+/**
+ * Build a checkpoint snapshot from a checkpoint ExternalNode
+ */
+export async function buildCheckpointSnapshot(node, store, provenance) {
+    const externalData = node.external_data ?? node.metadata ?? {};
+    return {
+        version: 1,
+        uri: node.uri,
+        source: node.source ?? 'entire',
+        entityType: 'checkpoint',
+        createdAt: node.created_at,
+        archivedAt: new Date().toISOString(),
+        node: {
+            title: node.title,
+            content: node.content,
+            status: node.status,
+            external_status: node.external_status,
+            external_data: externalData,
+            tags: node.tags,
+        },
+        provenance,
+        codeCommit: externalData.commitHash,
+        sessionUri: externalData.sessionId ? `entire://session/${externalData.sessionId}` : '',
+    };
+}
+/**
+ * Build a generic snapshot for any ExternalNode
+ */
+export async function buildSnapshot(node, store, provenance) {
+    const metadata = node.metadata;
+    const entityType = metadata?.entityType;
+    if (entityType === 'session') {
+        return buildSessionSnapshot(node, store, provenance);
+    }
+    if (entityType === 'checkpoint') {
+        return buildCheckpointSnapshot(node, store, provenance);
+    }
+    // Generic external node snapshot
+    return {
+        version: 1,
+        uri: node.uri,
+        source: node.source ?? 'unknown',
+        entityType: entityType ?? 'unknown',
+        createdAt: node.created_at,
+        archivedAt: new Date().toISOString(),
+        node: {
+            title: node.title,
+            content: node.content,
+            status: node.status,
+            external_status: node.external_status,
+            external_data: node.external_data ?? metadata ?? {},
+            tags: node.tags,
+        },
+        provenance,
+    };
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/materialization/snapshot.js.map

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

package/dist/materialization/types.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Materialization Store Types
+ *
+ * Type definitions for the pluggable archival layer that captures
+ * materialized external node snapshots to durable storage.
+ */
+/**
+ * Provenance — where a snapshot's data originated
+ */
+export interface SnapshotProvenance {
+    /** Configured graph ID (namespace in archive) */
+    graphId: string;
+    /** Absolute path to .opentasks/ directory at archive time */
+    graphPath: string;
+    /** Git remote URL (if available) */
+    gitRemote?: string;
+    /** Git branch the session operated on */
+    gitBranch?: string;
+    /** Git commit SHA at archive time */
+    gitHead?: string;
+}
+/**
+ * Edge snapshot — portable URI-based edge representation
+ */
+export interface EdgeSnapshot {
+    fromUri: string;
+    toUri: string;
+    edgeType: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Base materialization snapshot.
+ * Self-contained — everything needed to reconstruct the node.
+ */
+export interface MaterializationSnapshot {
+    /** Schema version for forward compatibility */
+    version: 1;
+    /** Canonical URI of the archived entity */
+    uri: string;
+    /** Provider source */
+    source: string;
+    /** Entity type within the source */
+    entityType: string;
+    /** When the original entity was created */
+    createdAt: string;
+    /** When this snapshot was captured */
+    archivedAt: string;
+    /** Complete node data for reconstruction */
+    node: {
+        title: string;
+        content?: string;
+        status?: string;
+        external_status?: string;
+        external_data: Record<string, unknown>;
+        tags?: string[];
+    };
+    /** Provenance — where this data came from */
+    provenance: SnapshotProvenance;
+}
+/**
+ * Session snapshot — extends base with relationships and checkpoints
+ */
+export interface SessionSnapshot extends MaterializationSnapshot {
+    entityType: 'session';
+    /** Related edges at archive time */
+    edges: EdgeSnapshot[];
+    /** Checkpoint IDs that belong to this session */
+    checkpointIds: string[];
+}
+/**
+ * Checkpoint snapshot — extends base with code commit correlation
+ */
+export interface CheckpointSnapshot extends MaterializationSnapshot {
+    entityType: 'checkpoint';
+    /** The code commit this checkpoint corresponds to */
+    codeCommit?: string;
+    /** The session this checkpoint belongs to */
+    sessionUri: string;
+}
+/**
+ * Controls when archival happens
+ */
+export interface ArchivePolicy {
+    /** Archive when a session starts (default: false) */
+    archiveOnStart: boolean;
+    /** Archive on each checkpoint (default: true when eager) */
+    archiveOnCheckpoint: boolean;
+    /** Archive when a session ends (default: true) */
+    archiveOnEnd: boolean;
+    /**
+     * Full materialization before archiving.
+     * When true, captures all available data from external_data.
+     * When false, archives only what's already in the graph node.
+     */
+    materializeBeforeArchive: boolean;
+}
+export declare const DEFAULT_ARCHIVE_POLICY: ArchivePolicy;
+/**
+ * Configuration for the git archive store
+ */
+export interface GitArchiveStoreConfig {
+    /** Branch name for archive commits (default: 'opentasks/archive') */
+    branch: string;
+    /** Git remote name to push to (default: none — local only) */
+    remote?: string;
+    /**
+     * Path to a separate git repo for the archive.
+     * If not set, uses the source repo's git dir.
+     */
+    repoPath?: string;
+    /** When to push to remote */
+    pushPolicy: 'immediate' | 'on-session-end' | 'manual';
+    /** Path to the source repo's .opentasks directory */
+    sourceRepoPath: string;
+}
+export declare const DEFAULT_GIT_ARCHIVE_CONFIG: Omit<GitArchiveStoreConfig, 'sourceRepoPath'>;
+/**
+ * Result of archiving a snapshot
+ */
+export interface ArchiveResult {
+    stored: boolean;
+    uri: string;
+    error?: string;
+}
+/**
+ * Result of archiving multiple snapshots
+ */
+export interface BatchArchiveResult {
+    results: ArchiveResult[];
+    successCount: number;
+    failureCount: number;
+}
+/**
+ * Filter for listing/querying archived snapshots
+ */
+export interface ArchiveFilter {
+    source?: string;
+    graphId?: string;
+    entityType?: string;
+    archivedAfter?: string;
+    archivedBefore?: string;
+    uriPattern?: string;
+}
+/**
+ * Entry in an archive listing
+ */
+export interface ArchiveListEntry {
+    uri: string;
+    entityType: string;
+    graphId: string;
+    archivedAt: string;
+    title?: string;
+    status?: string;
+}
+/**
+ * Health status of a store
+ */
+export interface StoreStatus {
+    healthy: boolean;
+    message?: string;
+    lastArchiveAt?: string;
+    lastError?: string;
+}
+/**
+ * Base materialization store interface.
+ * Both GitArchiveStore and RemoteStore implement this.
+ */
+export interface MaterializationStore {
+    /** Store identifier */
+    readonly name: string;
+    /** Store type */
+    readonly type: string;
+    /** Whether this store is currently enabled */
+    readonly enabled: boolean;
+    /** Archive a single snapshot */
+    archive(snapshot: MaterializationSnapshot): Promise<ArchiveResult>;
+    /** Archive multiple snapshots */
+    archiveBatch(snapshots: MaterializationSnapshot[]): Promise<BatchArchiveResult>;
+    /** Retrieve a snapshot by URI */
+    retrieve(uri: string): Promise<MaterializationSnapshot | null>;
+    /** List available snapshots */
+    list(filter?: ArchiveFilter): Promise<ArchiveListEntry[]>;
+    /** Initialize the store */
+    initialize(): Promise<void>;
+    /** Gracefully shut down */
+    close(): Promise<void>;
+    /** Health check */
+    status(): Promise<StoreStatus>;
+}
+/**
+ * Extended interface for git archive stores with point-in-time queries.
+ */
+export interface GitArchiveStoreExtended extends MaterializationStore {
+    /** Find a checkpoint by its associated code commit SHA */
+    findByCodeCommit(commitSha: string): Promise<CheckpointSnapshot | null>;
+    /** Get the session state at a specific checkpoint */
+    getSessionAt(sessionId: string, options: {
+        afterCheckpoint: string;
+    }): Promise<SessionSnapshot | null>;
+    /** List all graphId namespaces in the archive */
+    listGraphs(): Promise<string[]>;
+    /** Get the git log for a specific session's archive history */
+    getSessionHistory(sessionId: string, graphId: string): Promise<Array<{
+        commitSha: string;
+        message: string;
+        timestamp: string;
+    }>>;
+}
+/**
+ * Remote store configuration (from config file)
+ */
+export interface RemoteStoreConfig {
+    type: string;
+    name: string;
+    enabled: boolean;
+    config: Record<string, unknown>;
+    events: string[];
+}
+/**
+ * Interface that remote (non-git) storage backends must implement.
+ * Extends the base MaterializationStore with remote-specific concerns.
+ */
+export interface RemoteStore extends MaterializationStore {
+    /** Which events this store should receive */
+    readonly events: string[];
+}
+/**
+ * Result of an archive event (fan-out across all stores)
+ */
+export interface ArchiveEventResult {
+    uri: string;
+    stores: Array<{
+        storeName: string;
+        stored: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Result of bulk rematerialization
+ */
+export interface RematerializeAllResult {
+    restored: number;
+    failed: number;
+    skipped: number;
+    errors: Array<{
+        uri: string;
+        error: string;
+    }>;
+}
+/**
+ * The MaterializationArchiver coordinates between event sources
+ * (auto-linker) and stores (git, remote).
+ */
+export interface MaterializationArchiver {
+    /** Called by the auto-linker when a session lifecycle event occurs */
+    onSessionEvent(eventType: string, sessionUri: string, store: import('../graph/store.js').GraphStore): Promise<ArchiveEventResult>;
+    /** Manually archive a specific node by URI */
+    archiveNode(uri: string, store: import('../graph/store.js').GraphStore): Promise<ArchiveEventResult>;
+    /** Rematerialize a node from the archive into the graph */
+    rematerialize(uri: string, store: import('../graph/store.js').GraphStore): Promise<boolean>;
+    /** Rematerialize all missing nodes */
+    rematerializeAll(store: import('../graph/store.js').GraphStore): Promise<RematerializeAllResult>;
+    /** List all archived sessions */
+    listArchived(filter?: ArchiveFilter): Promise<ArchiveListEntry[]>;
+    /** Set the materialization provider (for materializeBeforeArchive) */
+    setMaterializationProvider(provider: MaterializationProvider): void;
+    /** Initialize all stores */
+    initialize(): Promise<void>;
+    /** Shut down all stores */
+    close(): Promise<void>;
+}
+/**
+ * Interface for triggering full materialization (fetching from provider).
+ * Matches the materializeNode method on ProviderAwareStore.
+ */
+export interface MaterializationProvider {
+    materializeNode(uri: string): Promise<import('../schema/nodes.js').ExternalNode>;
+}
+/**
+ * Configuration for the MaterializationArchiver
+ */
+export interface MaterializationArchiverConfig {
+    /** The git archive store (primary, always present when archival is enabled) */
+    gitStore: MaterializationStore;
+    /** Additional remote stores */
+    remoteStores: RemoteStore[];
+    /** Archive policy */
+    policy: ArchivePolicy;
+    /** Graph ID for namespacing */
+    graphId: string;
+    /** Path to .opentasks/ directory */
+    graphPath: string;
+    /**
+     * Optional materialization provider for materializeBeforeArchive.
+     * When set and policy.materializeBeforeArchive is true, the archiver
+     * will fetch fresh data from the provider before building snapshots.
+     */
+    materializationProvider?: MaterializationProvider;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/materialization/types.d.ts.map

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

package/dist/materialization/types.js

@@ -0,0 +1,17 @@
+/**
+ * Materialization Store Types
+ *
+ * Type definitions for the pluggable archival layer that captures
+ * materialized external node snapshots to durable storage.
+ */
+export const DEFAULT_ARCHIVE_POLICY = {
+    archiveOnStart: false,
+    archiveOnCheckpoint: true,
+    archiveOnEnd: true,
+    materializeBeforeArchive: true,
+};
+export const DEFAULT_GIT_ARCHIVE_CONFIG = {
+    branch: 'opentasks/archive',
+    pushPolicy: 'on-session-end',
+};
+//# sourceMappingURL=types.js.map

package/dist/materialization/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/materialization/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4HH,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACnD,cAAc,EAAE,KAAK;IACrB,mBAAmB,EAAE,IAAI;IACzB,YAAY,EAAE,IAAI;IAClB,wBAAwB,EAAE,IAAI;CAC/B,CAAC;AA6BF,MAAM,CAAC,MAAM,0BAA0B,GAAkD;IACvF,MAAM,EAAE,mBAAmB;IAC3B,UAAU,EAAE,gBAAgB;CAC7B,CAAC"}

package/dist/providers/__tests__/beads.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for Beads Provider
+ */
+export {};
+//# sourceMappingURL=beads.test.d.ts.map

package/dist/providers/__tests__/beads.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beads.test.d.ts","sourceRoot":"","sources":["../../../src/providers/__tests__/beads.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}