mcp-context-sync 1.0.11 → 1.0.13

package/dist/cli.js

@@ -15,8 +15,7 @@ import { execSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, platform } from 'node:os';
-import { getDatabase, closeDatabase } from './db/connection.js';
-import { upsertProject, getProject, getNextSequenceNumber, insertSnapshot, insertDecision, insertHandoff, updateProjectSyncStats, getLatestSnapshot, getProjectAgents, listProjects, getHandoffsByProject, } from './db/queries.js';
+import { getStorage, closeStorage } from './db/connection.js';
 import { projectIdFromPath, normalizePath, displayNameFromPath, } from './lib/project-id.js';
 import { generateId } from './lib/uuid.js';
 import { renderSnapshotMarkdown, renderSnapshotBrief } from './lib/snapshot-renderer.js';
@@ -60,7 +59,7 @@ function readJsonInput() {
  * Returns the matched normalized path, or null if none found.
  */
 function resolveProjectDir(db, startDir) {
-    const projects = listProjects(db);
+    const projects = db.listProjects();
     if (projects.length === 0)
         return null;
     const knownPaths = new Set(projects.map((p) => p.normalized_path));
@@ -121,14 +120,14 @@ function cmdResume() {
     const wantBrief = argv.includes('--brief');
     // --json and --brief imply --peek (no handoff registration)
     const peek = argv.includes('--peek') || wantJson || wantBrief;
-    const db = getDatabase();
+    const db = getStorage();
     const projectDir = getEffectiveProjectDir(db);
     const projectId = projectIdFromPath(projectDir);
     const displayName = displayNameFromPath(projectDir);
-    const project = getProject(db, projectId);
+    const project = db.getProject(projectId);
     if (!project) {
         if (!peek) {
-            const all = listProjects(db);
+            const all = db.listProjects();
             console.error(`No data found for "${displayName}" (${normalizePath(projectDir)})`);
             if (all.length > 0) {
                 console.error('\nAvailable projects:');
@@ -136,20 +135,20 @@ function cmdResume() {
                     console.error(`  ${p.normalized_path}  (${p.snapshot_count} snapshots)`);
             }
         }
-        closeDatabase();
+        closeStorage();
         process.exit(peek ? 0 : 1);
     }
-    const snapshot = getLatestSnapshot(db, projectId);
+    const snapshot = db.getLatestSnapshot(projectId);
     if (!snapshot) {
         if (!peek)
             console.error(`Project "${displayName}" exists but has no snapshots.`);
-        closeDatabase();
+        closeStorage();
         process.exit(peek ? 0 : 1);
     }
     if (!peek) {
         const now = new Date().toISOString();
         db.transaction(() => {
-            insertHandoff(db, {
+            db.insertHandoff({
                 id: generateId(),
                 project_id: projectId,
                 snapshot_id: snapshot.id,
@@ -159,7 +158,7 @@ function cmdResume() {
                 to_timestamp: now,
                 created_at: now,
             });
-            updateProjectSyncStats(db, projectId);
+            db.updateProjectSyncStats(projectId);
         })();
     }
     // Output priority: --json > --brief > default (full markdown)
@@ -170,14 +169,14 @@ function cmdResume() {
         console.log(renderSnapshotBrief(snapshot, displayName));
     }
     else {
-        const agents = getProjectAgents(db, projectId);
+        const agents = db.getProjectAgents(projectId);
         console.log(renderSnapshotMarkdown(snapshot, displayName, {
             totalSnapshots: project.snapshot_count,
             totalHandoffs: project.handoff_count + (peek ? 0 : 1),
             agents,
         }));
     }
-    closeDatabase();
+    closeStorage();
 }
 // ---------------------------------------------------------------------------
 // sync
@@ -186,16 +185,16 @@ function cmdResume() {
  * Save the snapshot to the database (shared by cmdSync and cmdSyncInteractive).
  */
 function saveSnapshot(projectDir, agent, summary, tasksCompleted, tasksRemaining, decisions, filesModified, blockers, nextSteps, tags) {
-    const db = getDatabase();
+    const db = getStorage();
     const projectId = projectIdFromPath(projectDir);
     const normalized = normalizePath(projectDir);
     const displayName = displayNameFromPath(projectDir);
     const now = new Date().toISOString();
     const { snapshotId, seqNum } = db.transaction(() => {
-        upsertProject(db, projectId, normalized, displayName);
-        const seqNum = getNextSequenceNumber(db, projectId);
+        db.upsertProject(projectId, normalized, displayName);
+        const seqNum = db.getNextSequenceNumber(projectId);
         const snapshotId = generateId();
-        insertSnapshot(db, {
+        db.insertSnapshot({
             id: snapshotId,
             project_id: projectId,
             sequence_number: seqNum,
@@ -211,7 +210,7 @@ function saveSnapshot(projectDir, agent, summary, tasksCompleted, tasksRemaining
             created_at: now,
         });
         for (const d of decisions) {
-            insertDecision(db, {
+            db.insertDecision({
                 id: generateId(),
                 project_id: projectId,
                 snapshot_id: snapshotId,
@@ -224,10 +223,10 @@ function saveSnapshot(projectDir, agent, summary, tasksCompleted, tasksRemaining
                 created_at: now,
             });
         }
-        updateProjectSyncStats(db, projectId);
+        db.updateProjectSyncStats(projectId);
         return { snapshotId, seqNum };
     })();
-    closeDatabase();
+    closeStorage();
     return { snapshotId, seqNum, displayName, normalized };
 }
 function cmdSync() {
@@ -296,9 +295,9 @@ function cmdSyncInteractive() {
         return input.split(',').map((s) => s.trim()).filter(Boolean);
     }
     async function run() {
-        const db = getDatabase();
+        const db = getStorage();
         const projectDir = getEffectiveProjectDir(db);
-        closeDatabase();
+        closeStorage();
         const agent = getFlag('agent') ?? 'claude-code';
         const displayName = displayNameFromPath(projectDir);
         console.log('');
@@ -349,8 +348,8 @@ function cmdSyncInteractive() {
 // list
 // ---------------------------------------------------------------------------
 function cmdList() {
-    const db = getDatabase();
-    const projects = listProjects(db);
+    const db = getStorage();
+    const projects = db.listProjects();
     if (projects.length === 0) {
         console.log('No projects synced yet.');
     }
@@ -363,17 +362,17 @@ function cmdList() {
             console.log();
         }
     }
-    closeDatabase();
+    closeStorage();
 }
 // ---------------------------------------------------------------------------
 // history
 // ---------------------------------------------------------------------------
 function cmdHistory() {
     const limit = parseInt(getFlag('limit') ?? '10', 10);
-    const db = getDatabase();
+    const db = getStorage();
     const projectDir = getEffectiveProjectDir(db);
     const projectId = projectIdFromPath(projectDir);
-    const handoffs = getHandoffsByProject(db, projectId, limit);
+    const handoffs = db.getHandoffsByProject(projectId, limit);
     if (handoffs.length === 0) {
         console.log('No handoff history for this project.');
     }
@@ -382,7 +381,7 @@ function cmdHistory() {
             console.log(`${h.from_agent} -> ${h.to_agent}  (${h.created_at})`);
         }
     }
-    closeDatabase();
+    closeStorage();
 }
 // ---------------------------------------------------------------------------
 // auto-sync
@@ -391,7 +390,7 @@ function cmdAutoSync() {
     const agent = getFlag('agent') ?? 'claude-code';
     let db;
     try {
-        db = getDatabase();
+        db = getStorage();
     }
     catch {
         // DB not accessible — exit silently
@@ -399,13 +398,13 @@ function cmdAutoSync() {
     }
     const projectDir = getEffectiveProjectDir(db);
     const projectId = projectIdFromPath(projectDir);
-    const project = getProject(db, projectId);
+    const project = db.getProject(projectId);
     if (!project) {
         // No existing project — exit silently, don't create one
-        closeDatabase();
+        closeStorage();
         process.exit(0);
     }
-    const latestSnapshot = getLatestSnapshot(db, projectId);
+    const latestSnapshot = db.getLatestSnapshot(projectId);
     // Carry over remaining tasks from the latest snapshot
     let tasksRemaining = '[]';
     if (latestSnapshot) {
@@ -414,9 +413,9 @@ function cmdAutoSync() {
     const now = new Date().toISOString();
     try {
         db.transaction(() => {
-            const seqNum = getNextSequenceNumber(db, projectId);
+            const seqNum = db.getNextSequenceNumber(projectId);
             const snapshotId = generateId();
-            insertSnapshot(db, {
+            db.insertSnapshot({
                 id: snapshotId,
                 project_id: projectId,
                 sequence_number: seqNum,
@@ -431,13 +430,13 @@ function cmdAutoSync() {
                 tags: '["auto-sync"]',
                 created_at: now,
             });
-            updateProjectSyncStats(db, projectId);
+            db.updateProjectSyncStats(projectId);
         })();
     }
     catch {
         // Swallow errors — must not fail on session exit
     }
-    closeDatabase();
+    closeStorage();
 }
 // ---------------------------------------------------------------------------
 // doctor
@@ -472,19 +471,28 @@ function cmdDoctor() {
     catch {
         console.log('Node.js:          unknown \u26A0');
     }
-    // 2. better-sqlite3 — test by opening the database
-    let sqliteOk = false;
+    // 2. Storage backend
+    let storageOk = false;
+    let backendName = 'unknown';
     try {
-        const db = getDatabase();
-        closeDatabase();
-        void db;
-        sqliteOk = true;
-        console.log('better-sqlite3:   loaded \u2713');
+        const db = getStorage();
+        backendName = db.backend;
+        storageOk = true;
+        if (backendName === 'sqlite') {
+            console.log('Storage backend:  SQLite (better-sqlite3) \u2713');
+        }
+        else {
+            console.log('Storage backend:  JSON files (fallback) \u26A0');
+            issues.push('\u26A0 Using JSON fallback storage. better-sqlite3 is not available.\n' +
+                '    SQLite is faster and supports FTS search. To enable it:\n' +
+                '    Fix: Reinstall with Node 20-22 LTS, or install Visual Studio Build Tools on Windows.');
+        }
+        closeStorage();
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        console.log('better-sqlite3:   FAILED \u2717');
-        issues.push(`\u2717 better-sqlite3 failed to load: ${msg}\n    Fix: npm i -g mcp-context-sync (with Node 20-22), or install Visual Studio Build Tools on Windows.`);
+        console.log('Storage backend:  FAILED \u2717');
+        issues.push(`\u2717 Storage failed to initialize: ${msg}`);
     }
     // 3. SQLite DB
     const dbPath = join(homedir(), '.agents', 'context-sync', 'data', 'context-sync.sqlite');
@@ -650,14 +658,14 @@ function cmdDoctor() {
     }
     // 7. Projects synced
     console.log('\nData:');
-    if (sqliteOk) {
+    if (storageOk) {
         try {
-            const db = getDatabase();
-            const projects = listProjects(db);
+            const db = getStorage();
+            const projects = db.listProjects();
             const totalSnapshots = projects.reduce((sum, p) => sum + p.snapshot_count, 0);
             const totalHandoffs = projects.reduce((sum, p) => sum + p.handoff_count, 0);
             console.log(`  Projects: ${projects.length} | Snapshots: ${totalSnapshots} | Handoffs: ${totalHandoffs}`);
-            closeDatabase();
+            closeStorage();
         }
         catch {
             console.log('  (unable to read database)');
@@ -690,17 +698,201 @@ function hasMcpServer(obj, serverName) {
     const servers = obj.mcpServers;
     return !!servers && serverName in servers;
 }
+// ---------------------------------------------------------------------------
+// Skill templates for /resume-project and /sync-project
+// ---------------------------------------------------------------------------
+function getResumeSkill(agent, mcpStyle) {
+    if (mcpStyle === 'direct') {
+        // Claude Code — can call MCP tools directly
+        return `---
+name: resume-project
+description: Load previous work context from context-sync. Use when starting a session, switching from another agent, or wanting to see what was previously worked on.
+disable-model-invocation: true
+---
+
+Load previous work context so you can continue where another agent left off.
+
+## Steps
+
+1. **Detect environment:**
+   - \`projectDir\`: Primary working directory (absolute path to project root)
+   - \`agent\`: \`"${agent}"\`
+
+2. **Call \`mcp__context-sync__resume\`** with \`{ "projectDir": "<path>", "agent": "${agent}" }\`
+
+3. **Present results conversationally:**
+   - Short header: project name, previous agent, date, snapshot number
+   - Top 5 completed tasks (mention total if more)
+   - Remaining tasks (top 5)
+   - 1-2 recent decisions
+   - \`next_steps\` as the suggested starting point
+
+4. **If error** (project not found): relay the error directly — it already lists available projects and suggestions.
+
+5. **If MCP tool fails** (connection error): fall back to CLI: \`context-sync resume --agent ${agent}\`
+`;
+    }
+    // Codex/Gemini — MCP + CLI fallback
+    return `---
+name: resume-project
+description: Load previous work context from context-sync. Use when starting a session, switching from another agent, or wanting to see what was previously worked on.
+metadata:
+  short-description: Resume context from previous session
+---
+
+# Resume Project
+
+Load previous work context so you can continue where another agent left off.
+
+## Method 1: MCP Tool (preferred)
+
+Call the MCP tool named **\`resume\`** from the **\`context-sync\`** server:
+\`\`\`json
+{ "projectDir": "<absolute path to project root>", "agent": "${agent}" }
+\`\`\`
+
+## Method 2: CLI (fallback if MCP tool call fails)
+
+\`\`\`bash
+context-sync resume --project "<absolute path to project root>" --agent ${agent}
+\`\`\`
+
+If \`--project\` is omitted, the current working directory is used automatically.
+
+## After loading
+
+Present results conversationally:
+- Project name, previous agent, date, snapshot number
+- Completed and remaining tasks (top 5 each)
+- Key decisions
+- \`next_steps\` as suggested starting point
+
+If project not found, the output will list available projects.
+`;
+}
+function getSyncSkill(agent, mcpStyle) {
+    if (mcpStyle === 'direct') {
+        // Claude Code — can call MCP tools directly
+        return `---
+name: sync-project
+description: Save a structured context snapshot for handoff to another agent. Use when finishing a session, switching agents, or reaching a checkpoint.
+disable-model-invocation: true
+---
+
+Analyze the current session and save a structured snapshot for another agent to resume from.
+
+## Steps
+
+1. **Detect environment:**
+   - \`projectDir\`: Primary working directory (absolute path to project root, not a subdirectory)
+   - \`agent\`: \`"${agent}"\`
+
+2. **Analyze conversation and extract:**
+   - \`summary\`: 1-2 sentences on what was accomplished
+   - \`tasksCompleted\`: Specific tasks finished (be precise)
+   - \`tasksRemaining\`: Pending work, TODOs, known issues
+   - \`decisions\`: Technical choices with \`decision\`, \`reasoning\`, \`alternatives\`
+   - \`filesModified\`: Files touched with \`path\`, \`action\` (created/modified/deleted), \`description\`
+   - \`blockers\`: Unresolved issues (empty array if none)
+   - \`nextSteps\`: Specific actionable instructions for the next agent
+   - \`tags\`: Lowercase categories (e.g., \`feature\`, \`backend\`, \`typescript\`)
+
+3. **Show compact draft and ask for confirmation:**
+   \`\`\`
+   Ready to save snapshot for: [project]
+   Summary: [summary]
+   Completed: [count] | Remaining: [count] | Decisions: [count] | Files: [count]
+   Next steps: [brief]
+   Save? (yes / no / edit)
+   \`\`\`
+
+4. **Once confirmed, call \`mcp__context-sync__sync\`** with all extracted data.
+
+5. **Confirm** snapshot number, timestamp, and that another agent can use \`/resume-project\` to continue.
+`;
+    }
+    // Codex/Gemini — MCP + CLI fallback
+    return `---
+name: sync-project
+description: Save a structured context snapshot for handoff to another agent. Use when finishing a session, switching agents, or reaching a checkpoint.
+metadata:
+  short-description: Save context for agent handoff
+---
+
+# Sync Project
+
+Analyze the current session and save a structured snapshot for another agent to resume from.
+
+## Step 1: Gather data
+
+- \`projectDir\`: Current working directory (absolute path to project **root**, not a subdirectory)
+- \`agent\`: \`"${agent}"\`
+- \`summary\`: 1-2 sentences on what was accomplished
+- \`tasksCompleted\`: Specific finished tasks
+- \`tasksRemaining\`: Pending work, TODOs, known issues
+- \`decisions\`: Technical choices with \`decision\`, \`reasoning\`, \`alternatives\`
+- \`filesModified\`: Files touched with \`path\`, \`action\` (created/modified/deleted), \`description\`
+- \`blockers\`: Unresolved issues (empty array if none)
+- \`nextSteps\`: Specific actionable instructions for the next agent
+- \`tags\`: Lowercase categories (e.g., \`feature\`, \`backend\`, \`typescript\`)
+
+Show a compact draft and ask for confirmation before saving.
+
+## Step 2: Save (pick one method)
+
+### Method 1: MCP Tool (preferred)
+
+Call the MCP tool named **\`sync\`** from the **\`context-sync\`** server with the JSON above.
+
+### Method 2: CLI (fallback if MCP tool call fails)
+
+Write the JSON to a temp file first:
+\`\`\`bash
+cat > /tmp/sync.json << 'EOF'
+{"projectDir":"<path>","agent":"${agent}","summary":"...","tasksCompleted":[...],"tasksRemaining":[...],"nextSteps":"..."}
+EOF
+
+context-sync sync --file /tmp/sync.json
+\`\`\`
+
+## Step 3: Confirm
+
+Report the snapshot number and confirm another agent can resume.
+`;
+}
+/**
+ * Install skill files for an agent. Returns paths created.
+ */
+function installSkills(skillsDir, agent, mcpStyle) {
+    const created = [];
+    const skills = [
+        { name: 'resume-project', content: getResumeSkill(agent, mcpStyle) },
+        { name: 'sync-project', content: getSyncSkill(agent, mcpStyle) },
+    ];
+    for (const skill of skills) {
+        const dir = join(skillsDir, skill.name);
+        const file = join(dir, 'SKILL.md');
+        if (existsSync(file))
+            continue; // don't overwrite
+        ensureDir(dir);
+        writeFileSync(file, skill.content, 'utf-8');
+        created.push(file);
+    }
+    return created;
+}
 function installClaude() {
     const label = 'Claude Code';
     // Claude Code can store MCP config in ~/.claude.json OR ~/.claude/settings.json
     const claudeJson = join(homedir(), '.claude.json');
     const settingsJson = join(homedir(), '.claude', 'settings.json');
+    const skillsDir = join(homedir(), '.claude', 'skills');
     // Check if already configured in either location
     for (const p of [claudeJson, settingsJson]) {
         try {
             if (existsSync(p)) {
                 const cfg = readJsonFile(p);
                 if (hasMcpServer(cfg, 'context-sync')) {
+                    installSkills(skillsDir, 'claude-code', 'direct'); // ensure skills even if MCP skipped
                     return { label, path: p, status: 'skipped' };
                 }
             }
@@ -720,6 +912,9 @@ function installClaude() {
             env: {},
         };
         writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        // Install skills
+        const skillsDir = join(homedir(), '.claude', 'skills');
+        installSkills(skillsDir, 'claude-code', 'direct');
         return { label, path: configPath, status: 'configured' };
     }
     catch (err) {
@@ -730,12 +925,15 @@ function installCodex() {
     const codexDir = join(homedir(), '.codex');
     const mcpJsonPath = join(codexDir, 'mcp.json');
     const configTomlPath = join(codexDir, 'config.toml');
+    const skillsDir = join(codexDir, 'skills');
     const label = 'Codex';
     try {
+        const doSkills = () => installSkills(skillsDir, 'codex', 'cli');
         // Check mcp.json first
         if (existsSync(mcpJsonPath)) {
             const config = readJsonFile(mcpJsonPath);
             if (hasMcpServer(config, 'context-sync')) {
+                doSkills(); // ensure skills even if MCP already configured
                 return { label, path: mcpJsonPath, status: 'skipped' };
             }
             if (!config.mcpServers)
@@ -744,16 +942,19 @@ function installCodex() {
                 command: 'mcp-context-sync',
             };
             writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+            doSkills();
             return { label, path: mcpJsonPath, status: 'configured' };
         }
         // Check config.toml
         if (existsSync(configTomlPath)) {
             const tomlContent = readFileSync(configTomlPath, 'utf-8');
             if (tomlContent.includes('[mcp_servers.context-sync]')) {
+                doSkills();
                 return { label, path: configTomlPath, status: 'skipped' };
             }
             const appendBlock = '\n[mcp_servers.context-sync]\ncommand = "mcp-context-sync"\n';
             writeFileSync(configTomlPath, tomlContent + appendBlock, 'utf-8');
+            doSkills();
             return { label, path: configTomlPath, status: 'configured' };
         }
         // Neither exists — create mcp.json
@@ -764,6 +965,7 @@ function installCodex() {
             },
         };
         writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        doSkills();
         return { label, path: mcpJsonPath, status: 'configured' };
     }
     catch (err) {
@@ -772,9 +974,11 @@ function installCodex() {
 }
 function installGemini() {
     const configPath = join(homedir(), '.gemini', 'antigravity', 'mcp_config.json');
+    const skillsDir = join(homedir(), '.gemini', 'skills');
     const label = 'Gemini';
     try {
         ensureDir(dirname(configPath));
+        installSkills(skillsDir, 'gemini-cli', 'cli');
         const config = existsSync(configPath) ? readJsonFile(configPath) : {};
         if (hasMcpServer(config, 'context-sync')) {
             return { label, path: configPath, status: 'skipped' };