session-collab-mcp 0.4.7 → 0.5.0

package/migrations/0004_symbols.sql

@@ -0,0 +1,18 @@
+-- Symbol-level claim tracking for fine-grained conflict detection
+-- Allows claiming specific functions/classes instead of entire files
+
+CREATE TABLE IF NOT EXISTS claim_symbols (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    claim_id TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    symbol_name TEXT NOT NULL,
+    symbol_type TEXT DEFAULT 'function' CHECK (symbol_type IN ('function', 'class', 'method', 'variable', 'block', 'other')),
+    created_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (claim_id) REFERENCES claims(id) ON DELETE CASCADE,
+    UNIQUE(claim_id, file_path, symbol_name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_claim_symbols_path ON claim_symbols(file_path);
+CREATE INDEX IF NOT EXISTS idx_claim_symbols_name ON claim_symbols(symbol_name);
+CREATE INDEX IF NOT EXISTS idx_claim_symbols_claim ON claim_symbols(claim_id);
+CREATE INDEX IF NOT EXISTS idx_claim_symbols_lookup ON claim_symbols(file_path, symbol_name);

package/migrations/0005_references.sql

@@ -0,0 +1,19 @@
+-- Symbol reference tracking for impact analysis
+-- Stores which symbols are referenced by which files
+
+CREATE TABLE IF NOT EXISTS symbol_references (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_file TEXT NOT NULL,
+    source_symbol TEXT NOT NULL,
+    ref_file TEXT NOT NULL,
+    ref_line INTEGER,
+    ref_context TEXT,
+    session_id TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE,
+    UNIQUE(source_file, source_symbol, ref_file, ref_line)
+);
+
+CREATE INDEX IF NOT EXISTS idx_symbol_refs_source ON symbol_references(source_file, source_symbol);
+CREATE INDEX IF NOT EXISTS idx_symbol_refs_ref_file ON symbol_references(ref_file);
+CREATE INDEX IF NOT EXISTS idx_symbol_refs_session ON symbol_references(session_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-collab-mcp",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "MCP server for Claude Code session collaboration - prevents conflicts between parallel sessions",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -19,6 +19,8 @@ function loadMigrations(): string[] {
     readFileSync(join(migrationsDir, '0001_init.sql'), 'utf-8'),
     readFileSync(join(migrationsDir, '0002_auth.sql'), 'utf-8'),
     readFileSync(join(migrationsDir, '0003_config.sql'), 'utf-8'),
+    readFileSync(join(migrationsDir, '0004_symbols.sql'), 'utf-8'),
+    readFileSync(join(migrationsDir, '0005_references.sql'), 'utf-8'),
   ];
 }
 

package/src/constants.ts

@@ -32,44 +32,179 @@ This MCP server coordinates multiple Claude Code sessions working on the same co
 
 2. **Before editing any file**: Call \`collab_check\` with the file path to verify no conflicts
 
-3. **If conflicts detected** (DEFAULT: coordinate):
-   - Show warning to user with options:
-     a) **Coordinate** (default): Send message to other session via \`collab_message_send\`, wait for response
-     b) **Bypass**: Proceed anyway (warn about potential conflicts)
-     c) **Request release**: Ask owner to release if claim seems stale
-   - NEVER auto-release another session's claim without explicit user permission
+3. **Follow the \`recommendation\` from collab_check automatically**:
+   - \`proceed_all\`: All files/symbols safe. Edit them without asking user.
+   - \`proceed_safe_only\`: Some content blocked. Edit ONLY safe files/symbols, skip blocked. No need to ask user.
+   - \`abort\`: All content blocked. Inform user and suggest coordination.
 
-4. **For significant changes**: Call \`collab_claim\` before starting work on files
+4. **For significant changes**: Call \`collab_claim\` before starting work
 
-5. **When done with files**: Call \`collab_release\` with YOUR session_id to free them
+5. **When done**: Call \`collab_release\` with YOUR session_id to free them
 
 6. **On conversation end**: Call \`collab_session_end\` to clean up
 
+## Symbol-Level Claims (Fine-Grained)
+
+Use symbol-level claims when modifying specific functions/classes, allowing other sessions to work on different parts of the same file.
+
+**Claim specific symbols:**
+\`\`\`json
+{
+  "symbols": [
+    { "file": "src/auth.ts", "symbols": ["validateToken", "refreshToken"] }
+  ],
+  "intent": "Refactoring token validation"
+}
+\`\`\`
+
+**Check specific symbols:**
+\`\`\`json
+{
+  "files": ["src/auth.ts"],
+  "symbols": [
+    { "file": "src/auth.ts", "symbols": ["validateToken"] }
+  ]
+}
+\`\`\`
+
+**Conflict levels:**
+- \`file\`: Whole file is claimed (no symbols specified)
+- \`symbol\`: Only specific functions/classes are claimed
+
+**Example scenario:**
+- Session A claims \`validateToken\` in auth.ts
+- Session B wants to modify \`refreshToken\` in auth.ts
+- → No conflict! Session B can proceed.
+
+## Auto-Decision Rules
+
+When \`collab_check\` returns:
+- \`can_edit: true\` → Proceed with safe content automatically
+- \`can_edit: false\` → Stop and inform user about blocked content
+
+For symbol-level checks, use \`symbol_status.safe\` and \`symbol_status.blocked\`.
+
 ## Permission Rules
 
 - You can ONLY release claims that belong to YOUR session
 - To release another session's claim, you must ask the user and they must explicitly confirm
 - Use \`force=true\` in \`collab_release\` only after user explicitly confirms
-- When user chooses "coordinate", send a message first and suggest waiting
 
 ## Conflict Handling Modes
 
 Configure your session behavior with \`collab_config\`:
 
 - **"strict"**: Always ask user, never bypass or auto-release
-- **"smart"** (default): Ask user, but suggest auto-release for stale claims (>2hr old)
+- **"smart"** (default): Auto-proceed with safe content, ask for blocked
 - **"bypass"**: Proceed despite conflicts (just warn, don't block)
 
-Config options:
-- \`mode\`: strict | smart | bypass
-- \`allow_release_others\`: Allow releasing other sessions' claims (default: false)
-- \`auto_release_stale\`: Auto-release stale claims (default: false)
-- \`stale_threshold_hours\`: Hours before claim is stale (default: 2)
+## LSP Integration (Advanced)
+
+For precise symbol validation and impact analysis, use LSP tools:
+
+### Workflow with LSP
+
+1. **Get symbols from LSP**: Use \`LSP.documentSymbol\` to get actual symbols in a file
+2. **Validate before claiming**: Use \`collab_validate_symbols\` to verify symbol names
+3. **Analyze conflicts with context**: Use \`collab_analyze_symbols\` for enhanced conflict detection
+
+### collab_validate_symbols
+
+Validate symbol names exist before claiming:
+
+\`\`\`
+1. Claude: LSP.documentSymbol("src/auth.ts")
+2. Claude: collab_validate_symbols({
+     file: "src/auth.ts",
+     symbols: ["validateToken", "refreshTokne"],  // typo!
+     lsp_symbols: [/* LSP output */]
+   })
+3. Response: { invalid_symbols: ["refreshTokne"], suggestions: { "refreshTokne": ["refreshToken"] } }
+\`\`\`
+
+### collab_analyze_symbols
+
+Enhanced conflict detection with LSP data:
+
+\`\`\`
+1. Claude: LSP.documentSymbol("src/auth.ts")
+2. Claude: LSP.findReferences("validateToken")
+3. Claude: collab_analyze_symbols({
+     session_id: "...",
+     files: [{ file: "src/auth.ts", symbols: [/* LSP symbols */] }],
+     references: [{ symbol: "validateToken", file: "src/auth.ts", references: [...] }]
+   })
+4. Response: {
+     can_edit: true,
+     recommendation: "proceed_safe_only",
+     symbols: [
+       { name: "validateToken", conflict_status: "blocked", impact: { references_count: 5, affected_files: [...] } },
+       { name: "refreshToken", conflict_status: "safe" }
+     ]
+   }
+\`\`\`
+
+### Benefits of LSP Integration
+
+- **Accurate symbol names**: No typos in claims
+- **Impact awareness**: Know which files will be affected by changes
+- **Smart prioritization**: Focus on low-impact changes first
+
+## Reference Tracking & Impact Analysis
+
+Store and query symbol references for smart conflict detection:
+
+### collab_store_references
+
+Persist LSP reference data for future impact queries:
+
+\`\`\`
+1. Claude: LSP.findReferences("validateToken")
+2. Claude: collab_store_references({
+     session_id: "...",
+     references: [{
+       source_file: "src/auth.ts",
+       source_symbol: "validateToken",
+       references: [
+         { file: "src/api/users.ts", line: 15 },
+         { file: "src/api/orders.ts", line: 23 }
+       ]
+     }]
+   })
+\`\`\`
+
+### collab_impact_analysis
+
+Check if modifying a symbol would affect files claimed by others:
+
+\`\`\`
+Claude: collab_impact_analysis({
+  session_id: "...",
+  file: "src/auth.ts",
+  symbol: "validateToken"
+})
+
+Response: {
+  risk_level: "high",
+  reference_count: 3,
+  affected_files: ["src/api/users.ts", "src/api/orders.ts"],
+  affected_claims: [{ session_name: "other-session", intent: "..." }],
+  message: "HIGH RISK: 1 active claim on referencing files"
+}
+\`\`\`
+
+### Risk Levels
+
+- **high**: Other sessions have claims on files that reference this symbol
+- **medium**: Many references (>10) but no active claims conflict
+- **low**: Few references, no conflicts
 
 ## Best Practices
 
-- Claim files early, release when done
-- Use descriptive intents when claiming (e.g., "Refactoring auth module")
-- Check for messages periodically with \`collab_message_list\`
-- Record architectural decisions with \`collab_decision_add\`
+- **Prefer symbol-level claims** for focused changes (single function/class)
+- **Use file-level claims** for large refactors affecting many symbols
+- **Use LSP validation** when unsure about symbol names
+- **Check references** before modifying widely-used symbols
+- Claim early, release when done
+- Use descriptive intents (e.g., "Refactoring validateToken for JWT support")
 `.trim();

package/src/db/queries.ts

@@ -14,6 +14,8 @@ import type {
   TodoItem,
   SessionProgress,
   SessionConfig,
+  SymbolClaim,
+  SymbolType,
 } from './types';
 
 // Helper to generate UUID v4
@@ -262,8 +264,9 @@ export async function createClaim(
     files: string[];
     intent: string;
     scope?: ClaimScope;
+    symbols?: SymbolClaim[];
   }
-): Promise<{ claim: Claim; files: string[] }> {
+): Promise<{ claim: Claim; files: string[]; symbols?: SymbolClaim[] }> {
   const id = generateId();
   const now = new Date().toISOString();
   const scope = params.scope ?? 'medium';
@@ -283,7 +286,23 @@ export async function createClaim(
       .bind(id, filePath, isPattern);
   });
 
-  await db.batch([claimStatement, ...fileStatements]);
+  // Add symbol claims if provided
+  const symbolStatements: ReturnType<typeof db.prepare>[] = [];
+  if (params.symbols && params.symbols.length > 0) {
+    for (const symbolClaim of params.symbols) {
+      for (const symbolName of symbolClaim.symbols) {
+        symbolStatements.push(
+          db
+            .prepare(
+              'INSERT INTO claim_symbols (claim_id, file_path, symbol_name, symbol_type, created_at) VALUES (?, ?, ?, ?, ?)'
+            )
+            .bind(id, symbolClaim.file, symbolName, symbolClaim.symbol_type ?? 'function', now)
+        );
+      }
+    }
+  }
+
+  await db.batch([claimStatement, ...fileStatements, ...symbolStatements]);
 
   return {
     claim: {
@@ -297,6 +316,7 @@ export async function createClaim(
       completed_summary: null,
     },
     files: params.files,
+    symbols: params.symbols,
   };
 }
 
@@ -384,47 +404,187 @@ export async function listClaims(
 export async function checkConflicts(
   db: DatabaseAdapter,
   files: string[],
-  excludeSessionId?: string
+  excludeSessionId?: string,
+  symbols?: SymbolClaim[]
 ): Promise<ConflictInfo[]> {
   const conflicts: ConflictInfo[] = [];
 
-  for (const filePath of files) {
-    // Check for exact matches or pattern overlaps
-    let query = `
-      SELECT
-        c.id as claim_id,
-        c.session_id,
-        s.name as session_name,
-        cf.file_path,
-        c.intent,
-        c.scope,
-        c.created_at
-      FROM claim_files cf
-      JOIN claims c ON cf.claim_id = c.id
-      JOIN sessions s ON c.session_id = s.id
-      WHERE c.status = 'active'
-        AND s.status = 'active'
-        AND (cf.file_path = ? OR (cf.is_pattern = 1 AND ? GLOB cf.file_path))
-    `;
-    const bindings: string[] = [filePath, filePath];
-
-    if (excludeSessionId) {
-      query += ' AND c.session_id != ?';
-      bindings.push(excludeSessionId);
+  // Build a map of file -> symbols for quick lookup
+  const symbolsByFile = new Map<string, Set<string>>();
+  if (symbols && symbols.length > 0) {
+    for (const sc of symbols) {
+      const existing = symbolsByFile.get(sc.file) ?? new Set();
+      for (const sym of sc.symbols) {
+        existing.add(sym);
+      }
+      symbolsByFile.set(sc.file, existing);
     }
+  }
 
-    const result = await db
-      .prepare(query)
-      .bind(...bindings)
-      .all<ConflictInfo>();
-
-    conflicts.push(...result.results);
+  for (const filePath of files) {
+    const requestedSymbols = symbolsByFile.get(filePath);
+
+    // First check if there are symbol-level claims for this file
+    if (requestedSymbols && requestedSymbols.size > 0) {
+      // Symbol-level conflict check
+      let symbolQuery = `
+        SELECT
+          c.id as claim_id,
+          c.session_id,
+          s.name as session_name,
+          cs.file_path,
+          c.intent,
+          c.scope,
+          c.created_at,
+          cs.symbol_name,
+          cs.symbol_type
+        FROM claim_symbols cs
+        JOIN claims c ON cs.claim_id = c.id
+        JOIN sessions s ON c.session_id = s.id
+        WHERE c.status = 'active'
+          AND s.status = 'active'
+          AND cs.file_path = ?
+          AND cs.symbol_name IN (${Array.from(requestedSymbols).map(() => '?').join(',')})
+      `;
+      const symbolBindings: string[] = [filePath, ...Array.from(requestedSymbols)];
+
+      if (excludeSessionId) {
+        symbolQuery += ' AND c.session_id != ?';
+        symbolBindings.push(excludeSessionId);
+      }
+
+      const symbolResult = await db
+        .prepare(symbolQuery)
+        .bind(...symbolBindings)
+        .all<ConflictInfo & { symbol_name: string; symbol_type: SymbolType }>();
+
+      for (const r of symbolResult.results) {
+        conflicts.push({
+          ...r,
+          conflict_level: 'symbol',
+        });
+      }
+
+      // Also check if there's a file-level claim (no symbols = whole file claimed)
+      let fileClaimQuery = `
+        SELECT
+          c.id as claim_id,
+          c.session_id,
+          s.name as session_name,
+          cf.file_path,
+          c.intent,
+          c.scope,
+          c.created_at
+        FROM claim_files cf
+        JOIN claims c ON cf.claim_id = c.id
+        JOIN sessions s ON c.session_id = s.id
+        WHERE c.status = 'active'
+          AND s.status = 'active'
+          AND (cf.file_path = ? OR (cf.is_pattern = 1 AND ? GLOB cf.file_path))
+          AND NOT EXISTS (
+            SELECT 1 FROM claim_symbols cs WHERE cs.claim_id = c.id AND cs.file_path = cf.file_path
+          )
+      `;
+      const fileClaimBindings: string[] = [filePath, filePath];
+
+      if (excludeSessionId) {
+        fileClaimQuery += ' AND c.session_id != ?';
+        fileClaimBindings.push(excludeSessionId);
+      }
+
+      const fileClaimResult = await db
+        .prepare(fileClaimQuery)
+        .bind(...fileClaimBindings)
+        .all<Omit<ConflictInfo, 'conflict_level'>>();
+
+      for (const r of fileClaimResult.results) {
+        conflicts.push({
+          ...r,
+          conflict_level: 'file',
+        });
+      }
+    } else {
+      // No symbols specified - check both file-level and symbol-level claims
+      // File-level claims (whole file)
+      let fileQuery = `
+        SELECT
+          c.id as claim_id,
+          c.session_id,
+          s.name as session_name,
+          cf.file_path,
+          c.intent,
+          c.scope,
+          c.created_at
+        FROM claim_files cf
+        JOIN claims c ON cf.claim_id = c.id
+        JOIN sessions s ON c.session_id = s.id
+        WHERE c.status = 'active'
+          AND s.status = 'active'
+          AND (cf.file_path = ? OR (cf.is_pattern = 1 AND ? GLOB cf.file_path))
+      `;
+      const fileBindings: string[] = [filePath, filePath];
+
+      if (excludeSessionId) {
+        fileQuery += ' AND c.session_id != ?';
+        fileBindings.push(excludeSessionId);
+      }
+
+      const fileResult = await db
+        .prepare(fileQuery)
+        .bind(...fileBindings)
+        .all<Omit<ConflictInfo, 'conflict_level'>>();
+
+      for (const r of fileResult.results) {
+        conflicts.push({
+          ...r,
+          conflict_level: 'file',
+        });
+      }
+
+      // Symbol-level claims on this file
+      let symbolOnlyQuery = `
+        SELECT DISTINCT
+          c.id as claim_id,
+          c.session_id,
+          s.name as session_name,
+          cs.file_path,
+          c.intent,
+          c.scope,
+          c.created_at,
+          cs.symbol_name,
+          cs.symbol_type
+        FROM claim_symbols cs
+        JOIN claims c ON cs.claim_id = c.id
+        JOIN sessions s ON c.session_id = s.id
+        WHERE c.status = 'active'
+          AND s.status = 'active'
+          AND cs.file_path = ?
+      `;
+      const symbolOnlyBindings: string[] = [filePath];
+
+      if (excludeSessionId) {
+        symbolOnlyQuery += ' AND c.session_id != ?';
+        symbolOnlyBindings.push(excludeSessionId);
+      }
+
+      const symbolOnlyResult = await db
+        .prepare(symbolOnlyQuery)
+        .bind(...symbolOnlyBindings)
+        .all<ConflictInfo & { symbol_name: string; symbol_type: SymbolType }>();
+
+      for (const r of symbolOnlyResult.results) {
+        conflicts.push({
+          ...r,
+          conflict_level: 'symbol',
+        });
+      }
+    }
   }
 
-  // Deduplicate by claim_id + file_path
+  // Deduplicate by claim_id + file_path + symbol_name
   const seen = new Set<string>();
   return conflicts.filter((c) => {
-    const key = `${c.claim_id}:${c.file_path}`;
+    const key = `${c.claim_id}:${c.file_path}:${c.symbol_name ?? ''}`;
     if (seen.has(key)) return false;
     seen.add(key);
     return true;
@@ -575,3 +735,158 @@ export async function listDecisions(
 
   return result.results;
 }
+
+// ============ Reference Queries ============
+
+import type { ReferenceInput, SymbolReference, ImpactInfo } from './types';
+
+export async function storeReferences(
+  db: DatabaseAdapter,
+  sessionId: string,
+  references: ReferenceInput[]
+): Promise<{ stored: number; skipped: number }> {
+  let stored = 0;
+  let skipped = 0;
+  const now = new Date().toISOString();
+
+  for (const ref of references) {
+    for (const r of ref.references) {
+      try {
+        await db
+          .prepare(
+            `INSERT OR IGNORE INTO symbol_references
+             (source_file, source_symbol, ref_file, ref_line, ref_context, session_id, created_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?)`
+          )
+          .bind(ref.source_file, ref.source_symbol, r.file, r.line, r.context ?? null, sessionId, now)
+          .run();
+        stored++;
+      } catch {
+        skipped++;
+      }
+    }
+  }
+
+  return { stored, skipped };
+}
+
+export async function getReferencesForSymbol(
+  db: DatabaseAdapter,
+  sourceFile: string,
+  sourceSymbol: string
+): Promise<SymbolReference[]> {
+  const result = await db
+    .prepare(
+      `SELECT * FROM symbol_references
+       WHERE source_file = ? AND source_symbol = ?
+       ORDER BY ref_file, ref_line`
+    )
+    .bind(sourceFile, sourceSymbol)
+    .all<SymbolReference>();
+
+  return result.results;
+}
+
+export async function getReferencesToFile(
+  db: DatabaseAdapter,
+  filePath: string
+): Promise<SymbolReference[]> {
+  const result = await db
+    .prepare(
+      `SELECT * FROM symbol_references
+       WHERE ref_file = ?
+       ORDER BY source_file, source_symbol`
+    )
+    .bind(filePath)
+    .all<SymbolReference>();
+
+  return result.results;
+}
+
+export async function analyzeClaimImpact(
+  db: DatabaseAdapter,
+  sourceFile: string,
+  sourceSymbol: string,
+  excludeSessionId?: string
+): Promise<ImpactInfo> {
+  // Get all references to this symbol
+  const refs = await getReferencesForSymbol(db, sourceFile, sourceSymbol);
+
+  // Get unique files that reference this symbol
+  const affectedFiles = [...new Set(refs.map((r) => r.ref_file))];
+
+  // Check if any of these files have active claims
+  const affectedClaims: ImpactInfo['affected_claims'] = [];
+
+  if (affectedFiles.length > 0) {
+    const placeholders = affectedFiles.map(() => '?').join(',');
+    let query = `
+      SELECT DISTINCT
+        c.id as claim_id,
+        s.name as session_name,
+        c.intent,
+        cf.file_path
+      FROM claim_files cf
+      JOIN claims c ON cf.claim_id = c.id
+      JOIN sessions s ON c.session_id = s.id
+      WHERE c.status = 'active'
+        AND s.status = 'active'
+        AND cf.file_path IN (${placeholders})
+    `;
+    const bindings: string[] = [...affectedFiles];
+
+    if (excludeSessionId) {
+      query += ' AND c.session_id != ?';
+      bindings.push(excludeSessionId);
+    }
+
+    const claimResults = await db
+      .prepare(query)
+      .bind(...bindings)
+      .all<{ claim_id: string; session_name: string | null; intent: string; file_path: string }>();
+
+    // Group by claim
+    const claimMap = new Map<string, { session_name: string | null; intent: string; files: string[] }>();
+    for (const r of claimResults.results) {
+      const existing = claimMap.get(r.claim_id);
+      if (existing) {
+        existing.files.push(r.file_path);
+      } else {
+        claimMap.set(r.claim_id, {
+          session_name: r.session_name,
+          intent: r.intent,
+          files: [r.file_path],
+        });
+      }
+    }
+
+    for (const [claimId, data] of claimMap) {
+      affectedClaims.push({
+        claim_id: claimId,
+        session_name: data.session_name,
+        intent: data.intent,
+        affected_symbols: data.files,
+      });
+    }
+  }
+
+  return {
+    symbol: sourceSymbol,
+    file: sourceFile,
+    affected_claims: affectedClaims,
+    reference_count: refs.length,
+    affected_files: affectedFiles,
+  };
+}
+
+export async function clearSessionReferences(
+  db: DatabaseAdapter,
+  sessionId: string
+): Promise<number> {
+  const result = await db
+    .prepare('DELETE FROM symbol_references WHERE session_id = ?')
+    .bind(sessionId)
+    .run();
+
+  return result.meta.changes;
+}