3.0.0 - File-per-thread architecture, bug fixes, and test coverage

Author: thrialectics

README.md

@@ -34,26 +34,31 @@ Checking environment...
   ✓ Claude Code detected
   ✓ ~/.claude directory exists
 
-[1/4] PostToolUse hook (auto-tracks files you create)
+[1/5] PostToolUse hook (auto-tracks files you create)
       Status: Not installed
       Install to ~/.claude/settings.json? (Y/n) y
       ✓ Hook installed
 
-[2/4] SessionStart hook (shows context at session start)
+[2/5] SessionStart hook (shows context at session start)
       Status: Not installed
       Install to ~/.claude/settings.json? (Y/n) y
       ✓ Hook installed
 
-[3/4] MCP Server (gives Claude direct access to threadlinking tools)
+[3/5] MCP Server (gives Claude direct access to threadlinking tools)
       Status: Not configured
-      Add to ~/.claude/settings.json mcpServers? (Y/n) y
+      Add to ~/.claude/mcp.json? (Y/n) y
       ✓ MCP server configured
 
-[4/4] CLAUDE.md instructions (teaches Claude when/how to use threadlinking)
+[4/5] CLAUDE.md instructions (teaches Claude when/how to use threadlinking)
       Status: Not present
       Append to ~/.claude/CLAUDE.md? (Y/n) y
       ✓ Instructions added
 
+[5/5] Ignore file (filters noise from pending files list)
+      Status: Not present
+      Create ~/.threadlinkingignore? (Y/n) y
+      ✓ Ignore file created
+
 Done! Threadlinking is fully configured.
 
 Start a new Claude Code session to begin.
@@ -310,7 +315,7 @@ Everything is stored locally at `~/.threadlinking/thread_index.json`. No cloud,
 
 - All data stored locally at `~/.threadlinking/` with `0600` permissions (owner read/write only)
 - No network calls, no telemetry, no cloud sync (model download is one-time and cached)
-- Minimal dependencies: [commander](https://www.npmjs.com/package/commander), [@xenova/transformers](https://github.com/xenova/transformers.js), [vectra](https://github.com/Stevenic/vectra)
+- Focused dependencies: [commander](https://www.npmjs.com/package/commander), [@xenova/transformers](https://github.com/xenova/transformers.js), [vectra](https://github.com/Stevenic/vectra), [zod](https://github.com/colinhacks/zod), [proper-lockfile](https://github.com/moxystudio/node-proper-lockfile), [ignore](https://github.com/kaelzhang/node-ignore), [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
 - Atomic file writes to prevent corruption
 - Input sanitization on all user-provided strings
 

ROADMAP.md

@@ -8,41 +8,34 @@ The goal: When you ask "why did we build it this way?", the answer should be a c
 
 ---
 
-## Current State (v2.0.0)
-
-### Version Status
-- **GitHub**: v2.0.0 (main branch)
-- **npm**: v1.1.1 (needs publishing)
+## Current State (v2.0.x)
 
 ### All Features (Free)
 - Thread-based context preservation
 - Snippets with source, timestamp, and tags
 - File attachments with explain command
 - Cross-session, cross-repo persistence
 - Keyword search
-- Semantic search (local embeddings via wink-nlp)
+- Semantic search (local embeddings via @xenova/transformers)
 - Analytics (usage stats)
 - Export (markdown/JSON/timeline formats)
 - MCP server integration with Claude Code
+- `.threadlinkingignore` support with prune command
+- Guided setup via `threadlinking init`
 
 ---
 
-## Phase 1: Publish v2.0.0 to npm
+## Phase 1: Publish & CI
 
 **Priority: HIGH**
 
-The main blocker for wider adoption.
-
-- [ ] Add basic test suite
-  - Core: thread CRUD, snippet operations
-  - CLI: smoke tests for main commands
-- [ ] Set up GitHub Actions CI
-  - Run tests on push
-  - Lint check
-  - Build verification
-- [ ] Update README with v2.0 features
+- [x] Publish v2.0.x to npm
+- [x] Set up GitHub Actions CI (ubuntu/macos/windows, Node 20 & 22)
+- [ ] Add comprehensive test suite
+  - Core operation unit tests
+  - Storage layer tests
+  - Integration/lifecycle tests
 - [ ] Verify Windows compatibility (path separators)
-- [ ] **Publish v2.0.0 to npm**
 
 ---
 
@@ -52,27 +45,25 @@ The main blocker for wider adoption.
 
 - [ ] Submit to official MCP Registry
 - [ ] Add `mcp.json` manifest file
-- [ ] Create setup instructions for Claude Code users
-  - **Recommend `~/.claude/mcp.json`** (dedicated MCP config, not settings.json)
-  - Document the difference: mcp.json is for MCP servers only, settings.json mixes personal config
-  - Provide simple copy-paste config:
-    ```json
-    {
-      "mcpServers": {
-        "threadlinking": {
-          "command": "npx",
-          "args": ["threadlinking-mcp"]
-        }
-      }
-    }
-    ```
-  - Note: Users can also use settings.json → mcpServers if they prefer single-file config
+- [x] Create setup instructions for Claude Code users (`threadlinking init`)
 - [ ] List on directories: Smithery, Glama, MCP.so
 - [ ] Submit PR to awesome-mcp-servers
 
 ---
 
-## Phase 3: IDE Integration
+## Phase 3: File-Per-Thread Architecture
+
+Split `thread_index.json` into one file per thread for better concurrency and inspectability.
+
+- [ ] Design migration strategy
+- [ ] New `loadThread(id)` / `saveThread(id)` / `updateThread(id, fn)` storage layer
+- [ ] Per-thread locking (instead of global lock)
+- [ ] Automatic migration from monolithic to file-per-thread
+- [ ] Update all operations to use new storage layer
+
+---
+
+## Phase 4: IDE Integration
 
 - [ ] VSCode extension
   - Right-click file → "Show Threadlinking Context"
@@ -82,12 +73,14 @@ The main blocker for wider adoption.
 
 ---
 
-## Phase 4: Future Enhancements
+## Phase 5: Future Enhancements
 
 - [ ] Thread relationships (link related threads)
 - [ ] Context summarization (AI-generated thread summaries)
 - [ ] Team/org features (optional, shared threads)
 - [ ] Cloud sync (optional, remains local-first by default)
+- [ ] Command syntax redesign for power users
+- [ ] Flat/nested attribute system
 
 ---
 
@@ -105,4 +98,4 @@ Ideas and PRs welcome. Open an issue to discuss before implementing major featur
 
 ---
 
-*Last updated: 2026-01-24*
+*Last updated: 2026-03-04*

package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadlinking",
-  "version": "2.0.13",
+  "version": "3.0.0",
   "description": "Preserve the decisions behind your code",
   "type": "module",
   "main": "dist/index.js",

src/commands/attach.ts

@@ -10,6 +10,7 @@ export const attachCommand = new Command('attach')
 
     if (!result.success) {
       console.error(`Error: ${result.message}`);
+      process.exitCode = 1;
       return;
     }
 

src/commands/audit.ts

@@ -81,5 +81,6 @@ export const auditCommand = new Command('audit')
       console.log(`Duplicates: ${actualDuplicates.size}`);
     } catch (error) {
       console.error(`Error: ${error instanceof Error ? error.message : error}`);
+      process.exitCode = 1;
     }
   });

src/commands/clear.ts

@@ -1,29 +1,15 @@
 import { Command } from 'commander';
-import { createInterface } from 'readline';
-import { loadIndex, saveIndex } from '../core/index.js';
-
-function prompt(question: string): Promise<string> {
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer);
-    });
-  });
-}
+import { loadMetaIndex, deleteThreadFile, prompt } from '../core/index.js';
 
 export const clearCommand = new Command('clear')
   .description('Delete ALL threads from the index (dangerous)')
   .option('--yes', 'Skip confirmation prompts')
   .action(async (options) => {
     try {
-      const index = loadIndex();
+      const meta = loadMetaIndex();
+      const threadIds = Object.keys(meta.threads);
 
-      if (Object.keys(index).length === 0) {
+      if (threadIds.length === 0) {
         console.log('Index is already empty.');
         return;
       }
@@ -44,9 +30,14 @@ export const clearCommand = new Command('clear')
         }
       }
 
-      saveIndex({});
+      // Delete each thread file
+      for (const id of threadIds) {
+        deleteThreadFile(id);
+      }
+
       console.log('All threads deleted.');
     } catch (error) {
       console.error(`Error: ${error instanceof Error ? error.message : error}`);
+      process.exitCode = 1;
     }
   });

src/commands/delete.ts

@@ -1,32 +1,20 @@
 import { Command } from 'commander';
-import { createInterface } from 'readline';
-import { loadIndex, saveIndex, validateTag } from '../core/index.js';
-
-function prompt(question: string): Promise<string> {
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer);
-    });
-  });
-}
+import { deleteThreadFile, loadMetaIndex, validateTag, prompt } from '../core/index.js';
+import { getSemanticIndex } from '../embeddings/index.js';
 
 export const deleteCommand = new Command('delete')
   .description('Delete a thread')
   .argument('<thread_id>', 'Thread tag or UUID')
-  .option('--yes', 'Skip confirmation')
+  .option('--yes', 'Skip confirmation prompts')
   .action(async (threadId: string, options) => {
     try {
-      const index = loadIndex();
       const validatedId = validateTag(threadId);
 
-      if (!index[validatedId]) {
+      // Check existence via meta index
+      const meta = loadMetaIndex();
+      if (!meta.threads[validatedId]) {
         console.error(`Thread ID '${validatedId}' not found.`);
+        process.exitCode = 1;
         return;
       }
 
@@ -40,10 +28,19 @@ export const deleteCommand = new Command('delete')
         }
       }
 
-      delete index[validatedId];
-      saveIndex(index);
+      deleteThreadFile(validatedId);
+
+      // Clean up semantic index embeddings for the deleted thread
+      try {
+        const semanticIndex = await getSemanticIndex();
+        await semanticIndex.deleteThread(validatedId);
+      } catch {
+        // Non-fatal: semantic index may not exist
+      }
+
       console.log(`Deleted thread '${validatedId}'.`);
     } catch (error) {
       console.error(`Error: ${error instanceof Error ? error.message : error}`);
+      process.exitCode = 1;
     }
   });

src/commands/detach.ts

@@ -10,6 +10,7 @@ export const detachCommand = new Command('detach')
 
     if (!result.success) {
       console.error(`Error: ${result.message}`);
+      process.exitCode = 1;
       return;
     }
 

src/commands/explain.ts

@@ -11,6 +11,7 @@ export const explainCommand = new Command('explain')
 
     if (!result.success) {
       console.error(`Error: ${result.message}`);
+      process.exitCode = 1;
       return;
     }
 

src/commands/init.ts

@@ -2,8 +2,8 @@ import { Command } from 'commander';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync, copyFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
-import { createInterface } from 'readline';
 import { getDefaultIgnoreContent } from '../core/ignore.js';
+import { prompt } from '../core/utils.js';
 
 const CLAUDE_DIR = join(homedir(), '.claude');
 const SETTINGS_PATH = join(CLAUDE_DIR, 'settings.json');
@@ -93,18 +93,9 @@ interface SetupStatus {
   mcpJsonValid: boolean;
 }
 
-function ask(question: string): Promise<string> {
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase());
-    });
-  });
+async function ask(question: string): Promise<string> {
+  const answer = await prompt(question);
+  return answer.trim().toLowerCase();
 }
 
 function loadSettings(): { settings: Record<string, unknown>; valid: boolean } {