studiograph 1.1.2 → 1.2.0-beta.1

package/dist/services/sync/sync-runner.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Sync Runner
+ *
+ * Orchestrates the full sync pipeline:
+ * 1. Load source configs
+ * 2. Connect to each source's MCP server
+ * 3. Extract (structured or unstructured per mapping)
+ * 4. Detect derivation needs, derive secondary entities
+ * 5. Reconcile all records
+ * 6. Write to staging
+ */
+export interface SyncOptions {
+    workspacePath: string;
+    sources?: string[];
+    dryRun?: boolean;
+    incremental?: boolean;
+    schemaExtensions?: Record<string, any>;
+}
+export interface SyncResult {
+    sources_processed: number;
+    records_extracted: number;
+    records_derived: number;
+    records_reconciled: number;
+    records_graph_matched: number;
+    staging_written: number;
+    by_source: Record<string, {
+        extracted: number;
+        errors: number;
+    }>;
+    by_entity_type: Record<string, number>;
+}
+export declare function runSync(options: SyncOptions, onProgress?: (msg: string) => void): Promise<SyncResult>;

package/dist/services/sync/sync-runner.js

@@ -0,0 +1,195 @@
+/**
+ * Sync Runner
+ *
+ * Orchestrates the full sync pipeline:
+ * 1. Load source configs
+ * 2. Connect to each source's MCP server
+ * 3. Extract (structured or unstructured per mapping)
+ * 4. Detect derivation needs, derive secondary entities
+ * 5. Reconcile all records
+ * 6. Write to staging
+ */
+import { ConnectorManager } from '../../mcp/connector-manager.js';
+import { SchemaRegistry } from '../../core/schema-registry.js';
+import { SourceConfigManager } from './source-config.js';
+import { SyncStateManager } from './sync-state.js';
+import { SyncMCPClient } from './mcp-client.js';
+import { StructuredExtractor } from './structured-extractor.js';
+import { UnstructuredExtractor } from './unstructured-extractor.js';
+import { FrontmatterExtractor } from './frontmatter-extractor.js';
+import { DerivationEngine } from './derive.js';
+import { Reconciler } from './reconciler.js';
+import { graphMatch, formatGraphMatchEvent } from './graph-match.js';
+import { StagingManager } from './staging.js';
+import { loadGraphRAGConfig, isGraphRAGEnabled } from './graphrag-config.js';
+import { GraphRAGClient } from './graphrag-client.js';
+export async function runSync(options, onProgress) {
+    const log = onProgress ?? (() => { });
+    const { workspacePath } = options;
+    // Load source configs
+    const configMgr = new SourceConfigManager(workspacePath);
+    let allConfigs = configMgr.getAll().filter(c => c.enabled);
+    if (options.sources && options.sources.length > 0) {
+        allConfigs = allConfigs.filter(c => options.sources.includes(c.name));
+    }
+    if (allConfigs.length === 0) {
+        log('No enabled sources found.');
+        return emptyResult();
+    }
+    // Load connectors
+    const connectors = ConnectorManager.loadConfigs();
+    // Initialize managers
+    const syncState = new SyncStateManager(workspacePath);
+    const schemaRegistry = new SchemaRegistry(options.schemaExtensions);
+    const staging = new StagingManager(workspacePath);
+    // Initialize GraphRAG client if enabled
+    let graphrag;
+    if (isGraphRAGEnabled()) {
+        const graphragConfig = loadGraphRAGConfig();
+        graphrag = new GraphRAGClient(graphragConfig);
+        const available = await graphrag.isAvailable();
+        if (available) {
+            const stats = graphrag.getStats();
+            log(`GraphRAG enabled: ${stats.nodes} nodes, ${stats.edges} edges`);
+        }
+        else {
+            log('GraphRAG enabled but graph is empty — run: studiograph graphrag index <path>');
+            graphrag = undefined;
+        }
+    }
+    const result = {
+        sources_processed: 0,
+        records_extracted: 0,
+        records_derived: 0,
+        records_reconciled: 0,
+        records_graph_matched: 0,
+        staging_written: 0,
+        by_source: {},
+        by_entity_type: {},
+    };
+    const allRecords = [];
+    // Phase 1: Extract from all sources
+    for (const sourceConfig of allConfigs) {
+        log(`Extracting from ${sourceConfig.name}...`);
+        const sourceResult = { extracted: 0, errors: 0 };
+        const connector = connectors.find(c => c.name === sourceConfig.connector);
+        if (!connector) {
+            log(`  Connector "${sourceConfig.connector}" not found — skipping`);
+            sourceResult.errors++;
+            result.by_source[sourceConfig.name] = sourceResult;
+            continue;
+        }
+        const client = new SyncMCPClient(connector);
+        try {
+            await client.connect();
+            log(`  Connected to ${sourceConfig.connector}`);
+            for (const mapping of sourceConfig.entity_mappings) {
+                log(`  Extracting ${mapping.source_type} → ${mapping.entity_type}...`);
+                try {
+                    let records;
+                    if (mapping.extraction_mode === 'structured') {
+                        const extractor = new StructuredExtractor(client, sourceConfig, syncState);
+                        records = await extractor.extract(mapping, options.incremental, log);
+                    }
+                    else if (mapping.extraction_mode === 'frontmatter') {
+                        const extractor = new FrontmatterExtractor(client, sourceConfig);
+                        records = await extractor.extract(mapping, log);
+                    }
+                    else {
+                        const extractor = new UnstructuredExtractor(client, sourceConfig, schemaRegistry, graphrag);
+                        records = await extractor.extract(mapping, log);
+                    }
+                    allRecords.push(...records);
+                    sourceResult.extracted += records.length;
+                    log(`    Extracted ${records.length} ${mapping.entity_type} records`);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    log(`    Error: ${msg}`);
+                    sourceResult.errors++;
+                }
+            }
+            // Update last sync timestamp
+            syncState.setLastSync(sourceConfig.name, new Date().toISOString());
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log(`  Connection failed: ${msg}`);
+            sourceResult.errors++;
+        }
+        finally {
+            await client.close();
+        }
+        result.by_source[sourceConfig.name] = sourceResult;
+        result.sources_processed++;
+    }
+    result.records_extracted = allRecords.length;
+    log(`\nExtracted ${allRecords.length} total records from ${result.sources_processed} sources`);
+    // Phase 2: Derivation
+    log('Detecting derivation needs...');
+    const allMappings = allConfigs.flatMap(c => c.entity_mappings);
+    const derivationEngine = new DerivationEngine(schemaRegistry);
+    const rules = derivationEngine.detectDerivationNeeds(allMappings);
+    let derivedRecords = [];
+    if (rules.length > 0) {
+        log(`  Deriving: ${rules.map(r => r.entity_type).join(', ')}`);
+        derivedRecords = derivationEngine.derive(allRecords, rules);
+        allRecords.push(...derivedRecords);
+        log(`  Derived ${derivedRecords.length} secondary entities`);
+    }
+    else {
+        log('  No derivation needed');
+    }
+    result.records_derived = derivedRecords.length;
+    // Phase 3: Reconciliation
+    log('Reconciling records...');
+    const reconciler = new Reconciler(workspacePath, schemaRegistry, syncState, allConfigs);
+    const matches = reconciler.reconcile(allRecords);
+    result.records_reconciled = matches.length;
+    log(`  ${matches.length} unique entities after reconciliation`);
+    // Phase 3.5: Graph matching
+    log('Matching against existing graph...');
+    const graphResults = await graphMatch(matches, {
+        workspacePath,
+        schemaExtensions: options.schemaExtensions,
+    }, (event) => log(formatGraphMatchEvent(event)));
+    const finalMatches = graphResults.map(r => r.match);
+    result.records_graph_matched = graphResults.filter(r => r.matched_to).length;
+    // Count by entity type
+    for (const match of finalMatches) {
+        result.by_entity_type[match.entity_type] = (result.by_entity_type[match.entity_type] ?? 0) + 1;
+    }
+    // Phase 4: Write staging
+    if (options.dryRun) {
+        log('\nDry run — skipping staging write');
+        result.staging_written = 0;
+    }
+    else {
+        log('Writing staging files...');
+        staging.clear();
+        const { written } = staging.writeStaging(finalMatches);
+        result.staging_written = written;
+        log(`  ${written} files written to .studiograph/staging/`);
+    }
+    // Persist provenance mappings
+    for (const match of finalMatches) {
+        for (const record of match.records) {
+            syncState.setEntityMapping(record.source_name, match.entity_id, record.source_ref);
+        }
+    }
+    log('\nSync complete.');
+    return result;
+}
+function emptyResult() {
+    return {
+        sources_processed: 0,
+        records_extracted: 0,
+        records_derived: 0,
+        records_reconciled: 0,
+        records_graph_matched: 0,
+        staging_written: 0,
+        by_source: {},
+        by_entity_type: {},
+    };
+}
+//# sourceMappingURL=sync-runner.js.map

package/dist/services/sync/sync-runner.js.map

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

package/dist/services/sync/sync-state.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SyncStateManager
+ *
+ * Persistent sync state at .studiograph/sync-state.json.
+ * Tracks cursors for incremental sync, entity provenance mappings,
+ * and tombstones for entities deliberately deleted by the user.
+ */
+import type { SyncState } from './types.js';
+export declare class SyncStateManager {
+    private statePath;
+    private state;
+    constructor(workspacePath: string);
+    /**
+     * Load sync state from disk. Creates empty state if file doesn't exist.
+     */
+    load(): SyncState;
+    /**
+     * Save sync state to disk.
+     */
+    save(state: SyncState): void;
+    getLastSync(source: string): string | null;
+    setLastSync(source: string, timestamp: string): void;
+    getCursor(source: string, entityType: string): string | null;
+    setCursor(source: string, entityType: string, cursor: string): void;
+    setEntityMapping(source: string, entityId: string, sourceRef: string): void;
+    getEntityMapping(source: string, entityId: string): string | null;
+    findBySourceRef(source: string, sourceRef: string): string | null;
+    /**
+     * Record which source wrote each field for an entity.
+     * Stored under state.sources[sourceName].field_origins[entityId].
+     */
+    setFieldOrigins(sourceName: string, entityId: string, fieldSources: Record<string, string>): void;
+    /**
+     * Get aggregated field origins for an entity across all sources.
+     * Returns field_name → source_name map.
+     */
+    getFieldOrigins(entityId: string): Record<string, string>;
+    addTombstone(entityId: string): void;
+    isTombstoned(entityId: string): boolean;
+    removeTombstone(entityId: string): void;
+    private emptyState;
+    private ensureSource;
+}

package/dist/services/sync/sync-state.js

@@ -0,0 +1,154 @@
+/**
+ * SyncStateManager
+ *
+ * Persistent sync state at .studiograph/sync-state.json.
+ * Tracks cursors for incremental sync, entity provenance mappings,
+ * and tombstones for entities deliberately deleted by the user.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+export class SyncStateManager {
+    statePath;
+    state = null;
+    constructor(workspacePath) {
+        this.statePath = join(workspacePath, '.studiograph', 'sync-state.json');
+    }
+    /**
+     * Load sync state from disk. Creates empty state if file doesn't exist.
+     */
+    load() {
+        if (this.state)
+            return this.state;
+        if (existsSync(this.statePath)) {
+            try {
+                this.state = JSON.parse(readFileSync(this.statePath, 'utf-8'));
+            }
+            catch {
+                this.state = this.emptyState();
+            }
+        }
+        else {
+            this.state = this.emptyState();
+        }
+        return this.state;
+    }
+    /**
+     * Save sync state to disk.
+     */
+    save(state) {
+        this.state = state;
+        const dir = dirname(this.statePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(this.statePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    }
+    // ── Source cursor tracking ────────────────────────────────────────────────
+    getLastSync(source) {
+        const state = this.load();
+        return state.sources[source]?.last_sync ?? null;
+    }
+    setLastSync(source, timestamp) {
+        const state = this.load();
+        this.ensureSource(state, source);
+        state.sources[source].last_sync = timestamp;
+        this.save(state);
+    }
+    getCursor(source, entityType) {
+        const state = this.load();
+        return state.sources[source]?.cursors[entityType] ?? null;
+    }
+    setCursor(source, entityType, cursor) {
+        const state = this.load();
+        this.ensureSource(state, source);
+        state.sources[source].cursors[entityType] = cursor;
+        this.save(state);
+    }
+    // ── Provenance mapping ────────────────────────────────────────────────────
+    setEntityMapping(source, entityId, sourceRef) {
+        const state = this.load();
+        this.ensureSource(state, source);
+        state.sources[source].entity_map[entityId] = sourceRef;
+        this.save(state);
+    }
+    getEntityMapping(source, entityId) {
+        const state = this.load();
+        return state.sources[source]?.entity_map[entityId] ?? null;
+    }
+    findBySourceRef(source, sourceRef) {
+        const state = this.load();
+        const entityMap = state.sources[source]?.entity_map;
+        if (!entityMap)
+            return null;
+        for (const [entityId, ref] of Object.entries(entityMap)) {
+            if (ref === sourceRef)
+                return entityId;
+        }
+        return null;
+    }
+    // ── Field Origins ────────────────────────────────────────────────────────────
+    /**
+     * Record which source wrote each field for an entity.
+     * Stored under state.sources[sourceName].field_origins[entityId].
+     */
+    setFieldOrigins(sourceName, entityId, fieldSources) {
+        const state = this.load();
+        this.ensureSource(state, sourceName);
+        const src = state.sources[sourceName];
+        if (!src.field_origins)
+            src.field_origins = {};
+        src.field_origins[entityId] = { ...src.field_origins[entityId], ...fieldSources };
+        this.save(state);
+    }
+    /**
+     * Get aggregated field origins for an entity across all sources.
+     * Returns field_name → source_name map.
+     */
+    getFieldOrigins(entityId) {
+        const state = this.load();
+        const merged = {};
+        for (const [sourceName, srcState] of Object.entries(state.sources)) {
+            const origins = srcState.field_origins?.[entityId];
+            if (origins) {
+                for (const [field, src] of Object.entries(origins)) {
+                    merged[field] = src;
+                }
+            }
+        }
+        return merged;
+    }
+    // ── Tombstones ─────────────────────────────────────────────────────────────
+    addTombstone(entityId) {
+        const state = this.load();
+        if (!state.tombstones.includes(entityId)) {
+            state.tombstones.push(entityId);
+            this.save(state);
+        }
+    }
+    isTombstoned(entityId) {
+        const state = this.load();
+        return state.tombstones.includes(entityId);
+    }
+    removeTombstone(entityId) {
+        const state = this.load();
+        const idx = state.tombstones.indexOf(entityId);
+        if (idx !== -1) {
+            state.tombstones.splice(idx, 1);
+            this.save(state);
+        }
+    }
+    // ── Private helpers ────────────────────────────────────────────────────────
+    emptyState() {
+        return { sources: {}, tombstones: [] };
+    }
+    ensureSource(state, source) {
+        if (!state.sources[source]) {
+            state.sources[source] = {
+                last_sync: '',
+                cursors: {},
+                entity_map: {},
+            };
+        }
+    }
+}
+//# sourceMappingURL=sync-state.js.map

package/dist/services/sync/sync-state.js.map

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

package/dist/services/sync/types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Core types for the entity sync system.
+ *
+ * Defines source configs, extraction records, sync state, reconciliation
+ * results, and staging metadata used across all sync pipeline stages.
+ */
+/**
+ * Source configuration stored at .studiograph/sources/<name>.json.
+ * Defines how to map external data to Studiograph entities.
+ */
+export interface SourceConfig {
+    name: string;
+    /** References a connector in ~/.studiograph/connectors/ */
+    connector: string;
+    enabled: boolean;
+    added_at: string;
+    entity_mappings: EntityMapping[];
+    /**
+     * Field-level merge priority: which source wins for which fields.
+     * e.g. { "email": "pipedrive", "status": "granola" }
+     * Default: structured API sources > derived data.
+     */
+    field_priority?: Record<string, string>;
+}
+/**
+ * Maps one external entity type to a Studiograph entity type.
+ */
+export interface EntityMapping {
+    /** What the source calls it (e.g. "deal", "document") */
+    source_type: string;
+    /** Studiograph entity type (e.g. "project", "meeting") */
+    entity_type: string;
+    /** Repo to write to (e.g. "projects", "meetings") */
+    target_repo: string;
+    /** Structured: field map driven. Unstructured: LLM extraction. */
+    extraction_mode: 'structured' | 'unstructured' | 'frontmatter';
+    /** Maps source field paths to entity field names or transforms */
+    field_map?: Record<string, string | FieldTransform>;
+    /** Maps source status values to entity status values */
+    status_map?: Record<string, string>;
+    /** Source field to slugify for entity_id */
+    id_from?: string;
+    /** Source field whose value becomes the entity markdown body (structured mode) */
+    content_from?: string;
+    /** If true, fetch full record via get tool for each listed ID (for APIs where list is sparse) */
+    fetch_details?: boolean;
+    /** Override the limit param sent to the list tool (e.g. 1000 to get all Granola docs) */
+    list_limit?: number;
+    /** Extra params passed to the list/search tool (e.g. { workspace: "12345" } for Asana).
+     *  Pass an array to make multiple list calls and merge results
+     *  (e.g. [{ archived: false }, { archived: true }]). */
+    list_params?: Record<string, any> | Record<string, any>[];
+    /** How entities are written to disk. 'entity' (default): repo/id/main.md. 'collection': repo/id.md */
+    write_mode?: 'entity' | 'collection';
+    /** Co-locate entities as sub-content inside a parent entity folder. */
+    co_locate?: {
+        /** Frontmatter field that references the parent entity (e.g., "project"). Value is a wikilink like "[[my-project]]". */
+        parent_field: string;
+        /** Subfolder name inside the parent entity folder (e.g., "tasks"). */
+        subfolder: string;
+    };
+    /** Fetch body content per record via a separate MCP tool call (e.g. readGoogleDoc).
+     *  The result text becomes the entity's markdown body. */
+    content_tool?: {
+        /** MCP tool name to call (e.g. "readGoogleDoc") */
+        tool: string;
+        /** Param name for the record ID (e.g. "documentId") */
+        id_param: string;
+        /** Record field to use as the ID value. Default: "id" */
+        id_from?: string;
+        /** Extra args to pass to the tool (e.g. { format: "markdown" }) */
+        extra_args?: Record<string, any>;
+    };
+    /** Directory patterns to match source files */
+    directory_patterns?: string[];
+    /** Explicit MCP tool name for listing files (e.g. "list_vault_files"). Falls back to heuristic matching. */
+    list_tool?: string;
+    /** Explicit MCP tool name for reading a file (e.g. "get_vault_file"). Falls back to heuristic matching. */
+    read_tool?: string;
+    /** Maximum recursion depth for directory listing. 0 = files directly in the pattern dir, 1 = one level of subdirs, etc. Undefined = unlimited. */
+    max_depth?: number;
+    /** Glob pattern matched against filename (without .md extension). Only matching files are included. Supports * and ? wildcards. E.g. "dec-*", "*.project". */
+    file_pattern?: string;
+    /** Match mode for filename. 'folder' = only files whose stem equals parent folder name. */
+    name_match?: 'folder';
+}
+/**
+ * Describes how to transform a source field into an entity field.
+ */
+export interface FieldTransform {
+    /** Target entity field name */
+    field: string;
+    /** Transform type to apply */
+    transform: 'direct' | 'kebab-case' | 'date-iso' | 'wikilink' | 'wikilink-array';
+    /** For array-of-objects: extract this sub-path from each element before transforming */
+    subfield?: string;
+}
+/**
+ * Metadata fields prefixed with _ in staging frontmatter, stripped on commit.
+ */
+export interface StagingMetadata {
+    _action: 'create' | 'update' | 'skip';
+    _confidence: number;
+    _sources: string[];
+    _notes: string;
+    _field_sources?: Record<string, string>;
+    /** Explains how this entity was matched to an existing graph entity */
+    _match_note?: string;
+}
+/**
+ * Internal representation of an extracted record, before reconciliation.
+ */
+export interface ExtractedRecord {
+    entity_type: string;
+    entity_id: string;
+    target_repo: string;
+    frontmatter: Record<string, any>;
+    content: string;
+    source_name: string;
+    source_ref: string;
+    confidence: number;
+    /** Co-location config from the entity mapping, if present. */
+    co_locate?: {
+        parent_field: string;
+        subfolder: string;
+    };
+    /** Write mode from the entity mapping, if present. */
+    write_mode?: 'entity' | 'collection';
+}
+/**
+ * Persistent sync state at .studiograph/sync-state.json.
+ * Survives across sync runs. Tracks cursors, provenance, and tombstones.
+ */
+export interface SyncState {
+    sources: Record<string, SourceSyncState>;
+    /** Entity IDs deliberately deleted by the user */
+    tombstones: string[];
+}
+export interface SourceSyncState {
+    /** ISO timestamp of last successful sync */
+    last_sync: string;
+    /** Per-entity-type pagination cursors */
+    cursors: Record<string, string>;
+    /** Maps local entity_id to external source ref for provenance */
+    entity_map: Record<string, string>;
+    /** Which source wrote each field, per entity. entity_id → field_name → source_name */
+    field_origins?: Record<string, Record<string, string>>;
+}
+/**
+ * Result of reconciling multiple extracted records into one entity.
+ */
+export interface ReconciliationMatch {
+    entity_id: string;
+    entity_type: string;
+    target_repo: string;
+    records: ExtractedRecord[];
+    match_type: 'exact-id' | 'email' | 'name-variant' | 'fuzzy-name' | 'single';
+    action: 'create' | 'update';
+    merged_frontmatter: Record<string, any>;
+    merged_content: string;
+    confidence: number;
+    notes: string;
+    field_sources?: Record<string, string>;
+    /** Co-location config, if this entity should be written as sub-content. */
+    co_locate?: {
+        parent_field: string;
+        subfolder: string;
+    };
+    /** Write mode: 'entity' (default) or 'collection' (loose file). */
+    write_mode?: 'entity' | 'collection';
+}
+/**
+ * Entity type detected from MCP tool inspection during source setup.
+ */
+export interface DetectedEntityType {
+    source_type: string;
+    list_tool: string;
+    get_tool?: string;
+    suggested_entity_type?: string;
+    suggested_repo?: string;
+    count?: number;
+}
+/**
+ * A file discovered from a file-based source (e.g. Obsidian).
+ */
+export interface SourceFile {
+    path: string;
+    name: string;
+    content?: string;
+}
+/**
+ * Rule describing how to derive secondary entities from primary records.
+ */
+export interface DerivationRule {
+    /** The entity type to derive (e.g. "person") */
+    entity_type: string;
+    /** Schema fields that reference this type (e.g. "attendees") */
+    source_fields: string[];
+    /** Entity types whose records contain those fields */
+    from_entity_types: string[];
+    /** Repo to write derived entities to */
+    target_repo: string;
+}

package/dist/services/sync/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core types for the entity sync system.
+ *
+ * Defines source configs, extraction records, sync state, reconciliation
+ * results, and staging metadata used across all sync pipeline stages.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/sync/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/sync/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}