opentology 0.2.7 → 0.3.0

package/dist/commands/context.js

@@ -217,6 +217,20 @@ export function registerContext(program) {
             }
             settings.hooks = hooks;
             writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+            // Ensure .opentology/snapshots/ is in .gitignore
+            const gitignorePath = join(process.cwd(), '.gitignore');
+            const snapshotIgnore = '.opentology/snapshots/';
+            if (existsSync(gitignorePath)) {
+                const gitignoreContent = readFileSync(gitignorePath, 'utf-8');
+                if (!gitignoreContent.includes(snapshotIgnore)) {
+                    writeFileSync(gitignorePath, gitignoreContent.trimEnd() + '\n' + snapshotIgnore + '\n', 'utf-8');
+                    console.log(pc.green('  Added .opentology/snapshots/ to .gitignore'));
+                }
+            }
+            else {
+                writeFileSync(gitignorePath, snapshotIgnore + '\n', 'utf-8');
+                console.log(pc.green('  Created .gitignore with .opentology/snapshots/'));
+            }
             console.log('');
             console.log(pc.dim('Consider adding .opentology/hooks/ to version control so team members share the hook.'));
         }

package/dist/commands/drop.js

@@ -1,6 +1,7 @@
 import pc from 'picocolors';
 import { loadConfig, resolveGraphUri, saveConfig } from '../lib/config.js';
 import { createReadyAdapter } from '../lib/store-factory.js';
+import { snapshotGraph } from '../lib/snapshot.js';
 export function registerDrop(program) {
     program
         .command('drop')
@@ -23,6 +24,7 @@ export function registerDrop(program) {
         }
         try {
             const adapter = await createReadyAdapter(config);
+            await snapshotGraph(adapter, config, graphUri);
             await adapter.dropGraph(graphUri);
             // In embedded mode, clear tracked files for this graph
             if (config.mode === 'embedded') {

package/dist/commands/rollback.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerRollback(program: Command): void;

package/dist/commands/rollback.js

@@ -0,0 +1,75 @@
+import pc from 'picocolors';
+import { loadConfig, resolveGraphUri } from '../lib/config.js';
+import { createReadyAdapter } from '../lib/store-factory.js';
+import { listSnapshots, restoreSnapshot } from '../lib/snapshot.js';
+import { createInterface } from 'node:readline';
+function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase());
+        });
+    });
+}
+export function registerRollback(program) {
+    program
+        .command('rollback')
+        .description('List or restore graph snapshots')
+        .option('--list', 'List available snapshots')
+        .option('--to <timestamp>', 'Restore to a specific snapshot timestamp')
+        .option('--graph <name>', 'Target a specific named graph')
+        .action(async (opts) => {
+        let config;
+        try {
+            config = loadConfig();
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        const graphUri = opts.graph ? resolveGraphUri(config, opts.graph) : config.graphUri;
+        if (opts.list) {
+            const snapshots = listSnapshots(graphUri);
+            if (snapshots.length === 0) {
+                console.log(pc.dim('No snapshots found for this graph.'));
+                return;
+            }
+            console.log(pc.bold(`Snapshots for ${graphUri}:`));
+            console.log('');
+            for (const s of snapshots) {
+                const sizeKb = (s.sizeBytes / 1024).toFixed(1);
+                const label = s.isPreRollback ? pc.yellow(' (pre-rollback)') : '';
+                console.log(`  ${pc.dim(s.timestamp)}  ${sizeKb} KB${label}`);
+            }
+            return;
+        }
+        try {
+            const adapter = await createReadyAdapter(config);
+            if (opts.to) {
+                await restoreSnapshot(adapter, config, graphUri, opts.to);
+                console.log(pc.green(`Restored graph to snapshot: ${opts.to}`));
+                return;
+            }
+            // No flags: restore latest snapshot with confirmation
+            const snapshots = listSnapshots(graphUri).filter((s) => !s.isPreRollback);
+            if (snapshots.length === 0) {
+                console.log(pc.dim('No snapshots found for this graph.'));
+                return;
+            }
+            const latest = snapshots[0];
+            const answer = await ask(`Restore to latest snapshot ${pc.bold(latest.timestamp)}? [y/N] `);
+            if (answer === 'y' || answer === 'yes') {
+                await restoreSnapshot(adapter, config, graphUri, latest.timestamp);
+                console.log(pc.green(`Restored graph to snapshot: ${latest.timestamp}`));
+            }
+            else {
+                console.log(pc.dim('Rollback cancelled.'));
+            }
+        }
+        catch (err) {
+            console.error(pc.red(`Error: ${err.message}`));
+            process.exit(1);
+        }
+    });
+}

package/dist/index.js

@@ -17,6 +17,7 @@ import { registerPrefix } from './commands/prefix.js';
 import { registerContext } from './commands/context.js';
 import { registerViz } from './commands/viz.js';
 import { registerDoctor } from './commands/doctor.js';
+import { registerRollback } from './commands/rollback.js';
 const program = new Command();
 program
     .name('opentology')
@@ -39,4 +40,5 @@ registerPrefix(program);
 registerContext(program);
 registerViz(program);
 registerDoctor(program);
+registerRollback(program);
 program.parse(process.argv);

package/dist/lib/snapshot.d.ts

@@ -0,0 +1,40 @@
+import type { StoreAdapter } from './store-adapter.js';
+import type { OpenTologyConfig } from './config.js';
+/**
+ * Derive a filesystem-safe slug from a graph URI.
+ * Reuses the same pattern as persistGraph().
+ */
+export declare function graphSlug(graphUri: string): string;
+/**
+ * Generate an ISO timestamp suitable for filenames.
+ * Format: 2026-04-05T14-30-22-123Z (colons replaced with dashes, ms included).
+ */
+export declare function toFilenameTimestamp(date?: Date): string;
+/**
+ * Snapshot a named graph before a destructive operation.
+ * No-op if not embedded mode or if the graph is empty.
+ * Automatically prunes old snapshots after saving.
+ */
+export declare function snapshotGraph(adapter: StoreAdapter, config: OpenTologyConfig, graphUri: string, retention?: number): Promise<string | null>;
+export interface SnapshotInfo {
+    timestamp: string;
+    path: string;
+    sizeBytes: number;
+    isPreRollback: boolean;
+}
+/**
+ * List snapshots for a graph, sorted by timestamp descending (newest first).
+ */
+export declare function listSnapshots(graphUri: string): SnapshotInfo[];
+/**
+ * Restore a graph to a specific snapshot.
+ * 1. Saves current state as {timestamp}_pre-rollback.ttl (snapshot-before-rollback)
+ * 2. Drops the graph and loads the snapshot
+ * 3. Persists the restored state to .opentology/data/
+ */
+export declare function restoreSnapshot(adapter: StoreAdapter, config: OpenTologyConfig, graphUri: string, timestamp: string): Promise<void>;
+/**
+ * Prune old snapshots, keeping only the most recent `keep` count.
+ * Pre-rollback snapshots are pruned separately (keep 2).
+ */
+export declare function pruneSnapshots(graphUri: string, keep?: number): Promise<number>;

package/dist/lib/snapshot.js

@@ -0,0 +1,136 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { persistGraph } from '../mcp/server.js';
+const DEFAULT_RETENTION = 5;
+/**
+ * Derive a filesystem-safe slug from a graph URI.
+ * Reuses the same pattern as persistGraph().
+ */
+export function graphSlug(graphUri) {
+    return graphUri.replace(/[^a-zA-Z0-9-]/g, '_').replace(/_+/g, '_');
+}
+/**
+ * Generate an ISO timestamp suitable for filenames.
+ * Format: 2026-04-05T14-30-22-123Z (colons replaced with dashes, ms included).
+ */
+export function toFilenameTimestamp(date = new Date()) {
+    return date.toISOString().replace(/:/g, '-').replace(/\./g, '-');
+}
+/**
+ * Parse a filename timestamp back to a Date.
+ */
+function parseFilenameTimestamp(filename) {
+    // Remove .ttl suffix and _pre-rollback suffix
+    const base = filename.replace(/\.ttl$/, '').replace(/_pre-rollback$/, '');
+    // Reverse the filename encoding: dashes back to colons/dots
+    // Format: 2026-04-05T14-30-22-123Z → 2026-04-05T14:30:22.123Z
+    const parts = base.match(/^(\d{4}-\d{2}-\d{2}T)(\d{2})-(\d{2})-(\d{2})-(\d{3}Z)$/);
+    if (!parts)
+        return null;
+    const iso = `${parts[1]}${parts[2]}:${parts[3]}:${parts[4]}.${parts[5]}`;
+    const d = new Date(iso);
+    return isNaN(d.getTime()) ? null : d;
+}
+function snapshotDir(graphUri) {
+    return join(process.cwd(), '.opentology', 'snapshots', graphSlug(graphUri));
+}
+/**
+ * Snapshot a named graph before a destructive operation.
+ * No-op if not embedded mode or if the graph is empty.
+ * Automatically prunes old snapshots after saving.
+ */
+export async function snapshotGraph(adapter, config, graphUri, retention = DEFAULT_RETENTION) {
+    if (config.mode !== 'embedded')
+        return null;
+    const exported = await adapter.exportGraph(graphUri);
+    if (!exported.trim())
+        return null;
+    const dir = snapshotDir(graphUri);
+    mkdirSync(dir, { recursive: true });
+    const timestamp = toFilenameTimestamp();
+    const filename = `${timestamp}.ttl`;
+    const filePath = join(dir, filename);
+    writeFileSync(filePath, exported, 'utf-8');
+    // Verify the file was written
+    if (!existsSync(filePath)) {
+        throw new Error(`Snapshot write failed: ${filePath}`);
+    }
+    // Prune old snapshots (create → verify → prune order)
+    await pruneSnapshots(graphUri, retention);
+    return filePath;
+}
+/**
+ * List snapshots for a graph, sorted by timestamp descending (newest first).
+ */
+export function listSnapshots(graphUri) {
+    const dir = snapshotDir(graphUri);
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter((f) => f.endsWith('.ttl'));
+    return files
+        .map((f) => {
+        const fullPath = join(dir, f);
+        const stat = statSync(fullPath);
+        return {
+            timestamp: f.replace(/\.ttl$/, ''),
+            path: fullPath,
+            sizeBytes: stat.size,
+            isPreRollback: f.includes('_pre-rollback'),
+        };
+    })
+        .sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+/**
+ * Restore a graph to a specific snapshot.
+ * 1. Saves current state as {timestamp}_pre-rollback.ttl (snapshot-before-rollback)
+ * 2. Drops the graph and loads the snapshot
+ * 3. Persists the restored state to .opentology/data/
+ */
+export async function restoreSnapshot(adapter, config, graphUri, timestamp) {
+    const dir = snapshotDir(graphUri);
+    const snapshotPath = join(dir, `${timestamp}.ttl`);
+    if (!existsSync(snapshotPath)) {
+        throw new Error(`Snapshot not found: ${timestamp}`);
+    }
+    // Step 1: Snapshot-before-rollback — save current state
+    const currentExport = await adapter.exportGraph(graphUri);
+    if (currentExport.trim()) {
+        mkdirSync(dir, { recursive: true });
+        const preRollbackTimestamp = toFilenameTimestamp();
+        const preRollbackPath = join(dir, `${preRollbackTimestamp}_pre-rollback.ttl`);
+        writeFileSync(preRollbackPath, currentExport, 'utf-8');
+    }
+    // Step 2: Drop and restore
+    const snapshotTurtle = readFileSync(snapshotPath, 'utf-8');
+    await adapter.dropGraph(graphUri);
+    await adapter.insertTurtle(graphUri, snapshotTurtle);
+    // Step 3: Persist restored state
+    await persistGraph(adapter, config, graphUri);
+}
+/**
+ * Prune old snapshots, keeping only the most recent `keep` count.
+ * Pre-rollback snapshots are pruned separately (keep 2).
+ */
+export async function pruneSnapshots(graphUri, keep = DEFAULT_RETENTION) {
+    const dir = snapshotDir(graphUri);
+    if (!existsSync(dir))
+        return 0;
+    const files = readdirSync(dir).filter((f) => f.endsWith('.ttl'));
+    // Separate regular snapshots and pre-rollback snapshots
+    const regular = files.filter((f) => !f.includes('_pre-rollback')).sort();
+    const preRollback = files.filter((f) => f.includes('_pre-rollback')).sort();
+    let deleted = 0;
+    // Prune regular snapshots
+    while (regular.length > keep) {
+        const oldest = regular.shift();
+        unlinkSync(join(dir, oldest));
+        deleted++;
+    }
+    // Prune pre-rollback snapshots (keep max 2)
+    while (preRollback.length > 2) {
+        const oldest = preRollback.shift();
+        unlinkSync(join(dir, oldest));
+        deleted++;
+    }
+    return deleted;
+}

package/dist/mcp/server.d.ts

@@ -1,3 +1,11 @@
+import type { OpenTologyConfig } from '../lib/config.js';
+import type { StoreAdapter } from '../lib/store-adapter.js';
 export declare const MAX_TRIPLES_PER_PUSH = 100;
 export declare function assertTripleLimit(tripleCount: number): void;
+/**
+ * Persist a named graph to a .ttl file in embedded mode.
+ * Exports the full graph, writes to .opentology/data/{slug}.ttl, and tracks
+ * the file in config — mirroring CLI push behavior.
+ */
+export declare function persistGraph(adapter: StoreAdapter, config: OpenTologyConfig, graphUri: string): Promise<void>;
 export declare function startMcpServer(): Promise<void>;

package/dist/mcp/server.js

@@ -1,11 +1,12 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { loadConfig, saveConfig, configExists, resolveGraphUri } from '../lib/config.js';
+import { loadConfig, saveConfig, configExists, resolveGraphUri, addTrackedFile } from '../lib/config.js';
 import { deepScan } from '../lib/deep-scanner.js';
 import { pushSymbolTriples } from '../lib/deep-scan-triples.js';
 import { createReadyAdapter } from '../lib/store-factory.js';
 import { normalizeModuleUri } from '../lib/module-uri.js';
+import { snapshotGraph, listSnapshots, restoreSnapshot } from '../lib/snapshot.js';
 import { hasGraphScope, autoScopeQuery, getInferenceGraphUri } from '../lib/sparql-utils.js';
 import { validateTurtle } from '../lib/validator.js';
 import { discoverShapes, validateWithShacl, hasShapes } from '../lib/shacl.js';
@@ -41,6 +42,26 @@ function resolveConfig(params) {
         throw new Error('No config found. Run opentology init first.');
     }
 }
+/**
+ * Persist a named graph to a .ttl file in embedded mode.
+ * Exports the full graph, writes to .opentology/data/{slug}.ttl, and tracks
+ * the file in config — mirroring CLI push behavior.
+ */
+export async function persistGraph(adapter, config, graphUri) {
+    if (config.mode !== 'embedded')
+        return;
+    const exported = await adapter.exportGraph(graphUri);
+    if (!exported.trim())
+        return;
+    // Derive a filename slug from the graph URI
+    const slug = graphUri.replace(/[^a-zA-Z0-9-]/g, '_').replace(/_+/g, '_');
+    const dataDir = join(process.cwd(), '.opentology', 'data');
+    const filePath = join(dataDir, `${slug}.ttl`);
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(filePath, exported, 'utf-8');
+    addTrackedFile(config, graphUri, filePath);
+    saveConfig(config);
+}
 async function handleInit(args) {
     const projectId = args.projectId;
     const mode = args.mode || 'http';
@@ -100,6 +121,7 @@ async function handlePush(args) {
     });
     const adapter = await createReadyAdapter(config);
     if (replace) {
+        await snapshotGraph(adapter, config, graphUri);
         await adapter.dropGraph(graphUri);
     }
     await adapter.insertTurtle(graphUri, content);
@@ -108,6 +130,7 @@ async function handlePush(args) {
     if (infer !== false) {
         inference = await materializeInferences(adapter, graphUri);
     }
+    await persistGraph(adapter, config, graphUri);
     return {
         success: true,
         tripleCount: validation.tripleCount,
@@ -199,7 +222,9 @@ async function handleDrop(args) {
         graph: args.graph,
     });
     const adapter = await createReadyAdapter(config);
+    await snapshotGraph(adapter, config, graphUri);
     await adapter.dropGraph(graphUri);
+    await persistGraph(adapter, config, graphUri);
     return { success: true, graphUri };
 }
 async function handleDelete(args) {
@@ -213,9 +238,32 @@ async function handleDelete(args) {
         graph: args.graph,
     });
     const adapter = await createReadyAdapter(config);
+    await snapshotGraph(adapter, config, graphUri);
     await adapter.deleteTriples(graphUri, { turtle: content, where });
+    await persistGraph(adapter, config, graphUri);
     return { success: true };
 }
+async function handleRollback(args) {
+    const action = args.action;
+    const { config, graphUri } = resolveConfig({
+        graphUri: args.graphUri,
+        graph: args.graph,
+    });
+    if (action === 'list') {
+        const snapshots = listSnapshots(graphUri);
+        return { graphUri, snapshots };
+    }
+    if (action === 'restore') {
+        const to = args.to;
+        if (!to) {
+            throw new Error('timestamp (to) is required for restore action');
+        }
+        const adapter = await createReadyAdapter(config);
+        await restoreSnapshot(adapter, config, graphUri, to);
+        return { success: true, graphUri, restoredTo: to };
+    }
+    throw new Error(`Unknown rollback action: ${action}. Use 'list' or 'restore'.`);
+}
 async function handleDiff(args) {
     const content = args.content;
     if (!content) {
@@ -287,7 +335,9 @@ async function handleGraphDrop(args) {
     const config = loadConfig();
     const graphUri = resolveGraphUri(config, name);
     const adapter = await createReadyAdapter(config);
+    await snapshotGraph(adapter, config, graphUri);
     await adapter.dropGraph(graphUri);
+    await persistGraph(adapter, config, graphUri);
     const graphs = config.graphs ?? {};
     delete graphs[name];
     config.graphs = Object.keys(graphs).length > 0 ? graphs : undefined;
@@ -302,6 +352,7 @@ async function handleInfer(args) {
     });
     const adapter = await createReadyAdapter(config);
     if (clear) {
+        await snapshotGraph(adapter, config, graphUri);
         await clearInferences(adapter, graphUri);
         return { success: true, cleared: true };
     }
@@ -328,6 +379,7 @@ async function handleContextScan(args) {
             const contextUri = `${config.graphUri}/context`;
             const adapter = await createReadyAdapter(config);
             pushStats = await pushSymbolTriples(adapter, contextUri, scanResult);
+            await persistGraph(adapter, config, contextUri);
         }
         catch {
             // Non-fatal: push is best-effort
@@ -351,6 +403,8 @@ async function handleContextScan(args) {
         const adapter = await createReadyAdapter(config);
         if (snapshot.dependencyGraph && snapshot.dependencyGraph.modules.length > 0) {
             const dg = snapshot.dependencyGraph;
+            // Snapshot before destructive scan
+            await snapshotGraph(adapter, config, contextUri);
             // Scoped delete: clear stale module triples before re-insert
             await adapter.sparqlUpdate(`DELETE WHERE { GRAPH <${contextUri}> { ?m a <https://opentology.dev/vocab#Module> . ?m ?p ?o } }`);
             // Insert fresh triples
@@ -363,6 +417,7 @@ async function handleContextScan(args) {
             }
             await adapter.sparqlUpdate(`INSERT DATA { GRAPH <${contextUri}> {\n${sparqlTriples.join('\n')}\n} }`);
             moduleStats = { modules: dg.modules.length, edges: dg.edges.length };
+            await persistGraph(adapter, config, contextUri);
         }
     }
     catch {
@@ -499,6 +554,20 @@ async function handleContextInit(args) {
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
         actions.push('Auto-registered hooks in .claude/settings.json');
     }
+    // Ensure .opentology/snapshots/ is in .gitignore
+    const gitignorePath = join(process.cwd(), '.gitignore');
+    const snapshotIgnore = '.opentology/snapshots/';
+    if (existsSync(gitignorePath)) {
+        const gitignoreContent = readFileSync(gitignorePath, 'utf-8');
+        if (!gitignoreContent.includes(snapshotIgnore)) {
+            writeFileSync(gitignorePath, gitignoreContent.trimEnd() + '\n' + snapshotIgnore + '\n', 'utf-8');
+            actions.push('Added .opentology/snapshots/ to .gitignore');
+        }
+    }
+    else {
+        writeFileSync(gitignorePath, snapshotIgnore + '\n', 'utf-8');
+        actions.push('Created .gitignore with .opentology/snapshots/');
+    }
     // Auto-push Module triples from dependency graph
     let moduleStats = null;
     try {
@@ -515,6 +584,7 @@ async function handleContextInit(args) {
             }
             await adapter.sparqlUpdate(`INSERT DATA { GRAPH <${contextUri}> {\n${sparqlTriples.join('\n')}\n} }`);
             moduleStats = { modules: dg.modules.length, edges: dg.edges.length };
+            await persistGraph(adapter, config, contextUri);
             actions.push(`Pushed ${dg.modules.length} Module triples with ${dg.edges.length} dependsOn edges`);
         }
     }
@@ -1235,6 +1305,33 @@ export async function startMcpServer() {
                     properties: {},
                 },
             },
+            {
+                name: 'rollback',
+                description: 'List or restore graph snapshots. Snapshots are automatically created before destructive operations (drop, delete, scan, etc.). Use action=list to see available snapshots, action=restore with a timestamp to restore.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        action: {
+                            type: 'string',
+                            enum: ['list', 'restore'],
+                            description: 'Action: list available snapshots or restore a specific one',
+                        },
+                        to: {
+                            type: 'string',
+                            description: 'Timestamp of the snapshot to restore (required for action=restore)',
+                        },
+                        graph: {
+                            type: 'string',
+                            description: 'Logical graph name (as created by graph_create). Resolves to a graph URI via config.',
+                        },
+                        graphUri: {
+                            type: 'string',
+                            description: 'Named graph URI (uses config default if omitted)',
+                        },
+                    },
+                    required: ['action'],
+                },
+            },
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1308,8 +1405,16 @@ export async function startMcpServer() {
                 case 'context_impact':
                     result = await handleContextImpact(args);
                     break;
-                case 'context_sync':
-                    result = await syncContext(loadConfig(), process.cwd());
+                case 'context_sync': {
+                    const syncConfig = loadConfig();
+                    const syncContextUri = `${syncConfig.graphUri}/context`;
+                    const syncAdapter = await createReadyAdapter(syncConfig);
+                    await snapshotGraph(syncAdapter, syncConfig, syncContextUri);
+                    result = await syncContext(syncConfig, process.cwd());
+                    break;
+                }
+                case 'rollback':
+                    result = await handleRollback(args);
                     break;
                 case 'doctor':
                     result = await runDoctor();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentology",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "Ontology-powered project memory for AI coding assistants — your codebase as a knowledge graph",
   "type": "module",
   "bin": {