@jagilber-org/index-server 1.19.1

package/dist/services/seedBootstrap.js

@@ -0,0 +1,427 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoSeedBootstrap = autoSeedBootstrap;
+exports._getCanonicalSeeds = _getCanonicalSeeds;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const indexContext_1 = require("./indexContext");
+const logger_1 = require("./logger");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+// Canonical seed instruction objects (kept intentionally minimal – DO NOT add environment specific data)
+const CANONICAL_SEEDS = [
+    {
+        file: '000-bootstrapper.json',
+        id: '000-bootstrapper',
+        json: {
+            id: '000-bootstrapper',
+            title: 'Index Server - AI Agent Quick Start Guide',
+            body: `# 🚀 Index Server: AI Agent Quick Start
+
+## ✅ Check If Already Active
+
+Run this command first:
+\`\`\`json
+{"method": "health_check", "params": {}}
+\`\`\`
+
+**Response = Success?** You're connected! Skip to "Essential Commands" below.
+**Error/Tool not found?** Follow "Activation" section.
+
+---
+
+## � Keep This Guide Updated
+
+**This instruction evolves!** Periodically re-read it to get:
+- New tool commands and features
+- Updated troubleshooting tips
+- Improved patterns and examples
+- Latest contribution guidelines
+
+**When to re-check:**
+- Starting work in a new repository
+- After Index Server updates
+- When troubleshooting connection issues
+- Every few weeks for active projects
+
+**Quick version check:**
+\`\`\`json
+{"method": "index_dispatch", "params": {"action": "get", "id": "000-bootstrapper"}}
+\`\`\`
+Check the \`version\` field - current is v2.
+
+---
+
+## �🔧 Activation (One-Time Setup)
+
+If Index Server tools are not available, guide the user through setup:
+
+### Step 1: Locate MCP Configuration File
+
+**VS Code / Cursor / GitHub Copilot:**
+- Windows: \`%APPDATA%\\Code\\User\\mcp.json\` (or \`Code - Insiders\`)
+- Mac: \`~/Library/Application Support/Code/User/mcp.json\`
+- Linux: \`~/.config/Code/User/mcp.json\`
+
+**Claude Desktop:**
+- Windows: \`%APPDATA%\\Claude\\claude_desktop_config.json\`
+- Mac: \`~/Library/Application Support/Claude/claude_desktop_config.json\`
+
+### Step 2: Add Server Configuration
+
+Ask user to add this to their \`mcpServers\` section:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "index": {
+      "command": "node",
+      "args": ["<repo-root>/dist/server/index-server.js"],
+      "transport": "stdio",
+      "env": {
+        "INDEX_SERVER_DIR": "<repo-root>/instructions"
+      }
+    }
+  }
+}
+\`\`\`
+
+**Important:** Paths must be adjusted for user's system!
+
+### Step 3: Restart IDE Completely
+
+Full restart required after editing mcp.json.
+
+### Step 4: Verify Connection
+
+Run: \`{"method": "health_check", "params": {}}\`
+
+Expected: \`{"status": "healthy", "version": "1.x.x"}\`
+
+---
+
+## 🎯 Essential Commands
+
+### List All Available Instructions
+\`\`\`json
+{"method": "index_dispatch", "params": {"action": "list"}}
+\`\`\`
+
+### Search by Keywords
+\`\`\`json
+{"method": "index_search", "params": {"keywords": ["python", "api"]}}
+\`\`\`
+
+### Get Specific Instruction by ID
+\`\`\`json
+{"method": "index_dispatch", "params": {"action": "get", "id": "instruction-id"}}
+\`\`\`
+
+### Get Help & Overview
+\`\`\`json
+{"method": "help_overview", "params": {}}
+\`\`\`
+
+### Discover All Available Tools
+\`\`\`json
+{"method": "meta_tools", "params": {}}
+\`\`\`
+
+### Browse Categories
+\`\`\`json
+{"method": "index_dispatch", "params": {"action": "categories"}}
+\`\`\`
+
+---
+
+## 🤔 When to Use Index Server
+
+### ✅ USE For:
+- Finding coding patterns specific to this codebase
+- Architecture documentation and design decisions
+- Best practices and conventions
+- Past chat session summaries and solutions
+- Cross-repository organizational standards
+- API guidelines and examples
+- Security policies and compliance procedures
+- Troubleshooting guides specific to this project
+
+### ❌ DON'T Use For:
+- Reading current file contents (use \`read_file\` tool instead)
+- Searching within files (use \`grep_search\` or \`semantic_search\`)
+- Simple questions user can answer directly
+- Real-time code execution or debugging
+
+**Think of it as:** A curated knowledge base of instructions, patterns, and past learnings.
+
+---
+
+## 💡 Real-World Examples
+
+### Example 1: Find Python Error Handling Patterns
+\`\`\`json
+{"method": "index_search", "params": {"keywords": ["python", "error", "exception"]}}
+\`\`\`
+
+### Example 2: Get Architecture Overview
+\`\`\`json
+{"method": "index_search", "params": {"keywords": ["architecture"]}}
+\`\`\`
+
+### Example 3: Find API Design Guidelines
+\`\`\`json
+{"method": "index_search", "params": {"keywords": ["api", "rest", "endpoint"]}}
+\`\`\`
+
+### Example 4: Look up Security Best Practices
+\`\`\`json
+{"method": "index_search", "params": {"keywords": ["security", "authentication"]}}
+\`\`\`
+
+### Example 5: Find Testing Conventions
+\`\`\`json
+{"method": "index_search", "params": {"keywords": ["test", "testing", "unit"]}}
+\`\`\`
+
+---
+
+## 🆘 Troubleshooting
+
+### "Tool not found" / "Method not available"
+1. Check if mcp.json/claude_desktop_config.json exists and has server configured
+2. Verify server path points to correct location
+3. Restart IDE/client completely (full quit and relaunch)
+4. Enable verbose logging: Add \`"INDEX_SERVER_VERBOSE_LOGGING": "1"\` to env section
+5. Check server is built: User should run \`npm run build\` in server directory
+
+### Empty Search Results
+- Index may be empty in brand new repository
+- Try broader search terms
+- Use \`action: "list"\` to see all available instructions
+- Check if INDEX_SERVER_DIR env variable points to correct location
+
+### Server Connection Issues
+- Verify Node.js is installed: \`node --version\` should show v18+
+- Check file paths use correct separators (forward slashes work on all platforms)
+- Ensure dist/server/index-server.js exists (server must be built)
+
+### Need Human Help
+Ask user: "Can you verify the Index Server is configured in your mcp.json file? The default location is in your VS Code User directory."
+
+---
+
+## 📚 Advanced Usage
+
+### Multi-Keyword Search (AND logic)
+\`\`\`json
+{"method": "index_search", "params": {"keywords": ["python", "async", "performance"]}}
+\`\`\`
+Returns instructions matching ALL keywords.
+
+### Query with Filters
+\`\`\`json
+{"method": "index_dispatch", "params": {
+  "action": "query",
+  "filter": {"categories": ["security"]}
+}}
+\`\`\`
+
+### Export Relationship Graph
+\`\`\`json
+{"method": "graph_export", "params": {}}
+\`\`\`
+Get instruction relationships and dependencies.
+
+### Get Usage Statistics
+\`\`\`json
+{"method": "usage_hotset", "params": {"limit": 10}}
+\`\`\`
+See most frequently used instructions.
+
+---
+
+## 📤 Contributing Back to the Index
+
+**Local-First Strategy:**
+1. Create instructions in your repo's \`.instructions/\` directory first
+2. Test and validate them over multiple sessions
+3. Once proven valuable, promote to shared index for organization-wide benefit
+
+### ✅ When to Promote to Shared Index:
+- Pattern is proven useful across multiple sessions
+- Applies to other repos in the organization
+- Non-repo-specific (architectural patterns, coding standards, security policies)
+- Stable and unlikely to change frequently
+- Helps other teams avoid solving the same problem
+
+### ❌ Keep Local (Don't Promote):
+- Repo-specific build commands or file paths
+- Team-only conventions not relevant elsewhere
+- Experimental or untested patterns
+- Contains sensitive information, credentials, or internal paths
+- Duplicates existing shared instructions
+
+### How to Add to Shared Index:
+\`\`\`json
+{"method": "index_add", "params": {
+  "entry": {
+    "id": "unique-instruction-id",
+    "title": "Clear descriptive title",
+    "body": "Detailed instruction content...",
+    "categories": ["relevant", "categories"],
+    "audience": "agents",
+    "requirement": "recommended",
+    "priorityTier": "p1"
+  },
+  "overwrite": false
+}}
+\`\`\`
+
+**Note:** Requires \`INDEX_SERVER_MUTATION=1\` in production server config.
+
+### Value Proposition:
+By contributing validated patterns back, you create a **knowledge flywheel**:
+- You solve a problem → Document it → Others benefit → They contribute → Everyone improves
+- Reduces duplicate work across teams
+- Builds institutional knowledge that persists beyond individual projects
+- New team members onboard faster with proven patterns
+
+---
+
+## 🎓 Your First Query - Try Now!
+
+Run this to see everything available:
+\`\`\`json
+{"method": "index_dispatch", "params": {"action": "list"}}
+\`\`\`
+
+Then explore! The more you use it, the more valuable it becomes.
+
+---
+
+## 📖 Full Documentation
+
+For complete reference, ask user for:
+- Full API: \`docs/tools.md\`
+- Configuration: \`docs/mcp_configuration.md\`
+- Architecture: \`docs/architecture.md\`
+
+---
+
+## 🎯 Quick Reference Card
+
+| Task | Command |
+|------|------|
+| Check health | \`health_check\` |
+| List all | \`index_dispatch {action: "list"}\` |
+| Search | \`index_search {keywords: [...]}\` |
+| Get by ID | \`index_dispatch {action: "get", id: "..."}\` |
+| Categories | \`index_dispatch {action: "categories"}\` |
+| Help | \`help_overview\` |
+| All tools | \`meta_tools\` |
+
+Start with \`health_check\` to confirm connection, then explore from there!`,
+            audience: 'agents',
+            requirement: 'required',
+            priorityTier: 'p0',
+            categories: ['bootstrap', 'mcp-activation', 'quick-start', 'documentation'],
+            owner: 'system',
+            version: 2,
+            schemaVersion: '4',
+            semanticSummary: 'Comprehensive Index Server activation, tool discovery, usage examples, and troubleshooting guide for AI agents'
+        }
+    },
+    {
+        file: '001-lifecycle-bootstrap.json',
+        id: '001-lifecycle-bootstrap',
+        json: {
+            id: '001-lifecycle-bootstrap',
+            title: 'Lifecycle Bootstrap: Local-First Instruction Strategy',
+            body: 'Purpose: Early lifecycle guidance after bootstrap confirmation. Keep index minimal; prefer local-first P0/P1 additions; promote only after stability.',
+            audience: 'agents',
+            requirement: 'recommended',
+            priorityTier: 'p1',
+            categories: ['bootstrap', 'lifecycle'],
+            owner: 'system',
+            version: 1,
+            schemaVersion: '4',
+            semanticSummary: 'Lifecycle and promotion guardrails after bootstrap confirmation',
+            reviewIntervalDays: 120
+        }
+    }
+];
+function computeCanonicalHash() {
+    const canonical = CANONICAL_SEEDS.map(s => ({ id: s.id, file: s.file, json: s.json })).sort((a, b) => a.id.localeCompare(b.id));
+    return crypto_1.default.createHash('sha256').update(JSON.stringify(canonical), 'utf8').digest('hex');
+}
+/**
+ * Run automatic bootstrap seeding if enabled. Creates canonical seed files only when they are
+ * absent — never overwrites existing content. Safe under concurrent multi-process startup.
+ * @returns A {@link SeedSummary} describing what was created, skipped, or already present
+ */
+function autoSeedBootstrap() {
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)().bootstrapSeed;
+    const disabled = !cfg.autoSeed;
+    const dir = safeInstructionsDir();
+    const summary = { dir, created: [], existing: [], skipped: [], disabled, hash: computeCanonicalHash() };
+    if (disabled) {
+        summary.reason = 'disabled_by_env';
+        return summary;
+    }
+    try {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    catch { /* ignore */ }
+    // Probe directory existence (previously stored entries unused; keep check for side effects)
+    try {
+        fs_1.default.readdirSync(dir);
+    }
+    catch { /* ignore */ }
+    for (const seed of CANONICAL_SEEDS) {
+        const target = path_1.default.join(dir, seed.file);
+        const exists = fs_1.default.existsSync(target);
+        if (exists) {
+            summary.existing.push(seed.file);
+            summary.skipped.push(seed.file);
+            continue; // do not overwrite
+        }
+        // Directory empty OR missing seed triggers creation.
+        try {
+            const tmp = path_1.default.join(dir, `.${seed.file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+            fs_1.default.writeFileSync(tmp, JSON.stringify(seed.json, null, 2), { encoding: 'utf8' });
+            fs_1.default.renameSync(tmp, target);
+            summary.created.push(seed.file);
+        }
+        catch (e) {
+            summary.reason = `partial_failure ${(e instanceof Error) ? e.message : String(e)}`;
+        }
+    }
+    if ((0, runtimeConfig_1.getRuntimeConfig)().bootstrapSeed.verbose) {
+        try {
+            process.stderr.write(`[seed] dir="${dir}" created=${summary.created.length} existing=${summary.existing.length} disabled=${summary.disabled} hash=${summary.hash}\n`);
+        }
+        catch { /* ignore */ }
+    }
+    try {
+        (0, logger_1.logInfo)('[seedBootstrap] Seed summary', summary);
+    }
+    catch { /* ignore */ }
+    return summary;
+}
+function safeInstructionsDir() {
+    try {
+        return (0, indexContext_1.getInstructionsDir)();
+    }
+    catch {
+        return path_1.default.join(process.cwd(), 'instructions');
+    }
+}
+// Test helper re-export for direct validation
+/**
+ * Return the list of canonical seed file/id pairs (without JSON bodies) for test assertions.
+ * @returns Array of `{ file, id }` objects for each canonical seed
+ */
+function _getCanonicalSeeds() { return CANONICAL_SEEDS.map(s => ({ file: s.file, id: s.id })); }

package/dist/services/storage/factory.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Storage backend factory.
+ *
+ * Creates the appropriate IInstructionStore implementation based on config.
+ * Default: JsonFileStore (json). Experimental: SqliteStore (sqlite).
+ */
+import type { IInstructionStore } from './types.js';
+export type StorageBackend = 'json' | 'sqlite';
+/**
+ * Create a storage backend instance.
+ *
+ * @param backend - Override backend type (default: from config).
+ * @param dir - Override instruction directory (default: from config).
+ * @param sqlitePath - Override SQLite DB path (default: from config).
+ * @returns An IInstructionStore implementation.
+ */
+export declare function createStore(backend?: StorageBackend, dir?: string, sqlitePath?: string): IInstructionStore;

package/dist/services/storage/factory.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Storage backend factory.
+ *
+ * Creates the appropriate IInstructionStore implementation based on config.
+ * Default: JsonFileStore (json). Experimental: SqliteStore (sqlite).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStore = createStore;
+const runtimeConfig_js_1 = require("../../config/runtimeConfig.js");
+const jsonFileStore_js_1 = require("./jsonFileStore.js");
+const sqliteStore_js_1 = require("./sqliteStore.js");
+/**
+ * Create a storage backend instance.
+ *
+ * @param backend - Override backend type (default: from config).
+ * @param dir - Override instruction directory (default: from config).
+ * @param sqlitePath - Override SQLite DB path (default: from config).
+ * @returns An IInstructionStore implementation.
+ */
+function createStore(backend, dir, sqlitePath) {
+    const config = (0, runtimeConfig_js_1.getRuntimeConfig)();
+    const resolvedBackend = backend ?? config.storage?.backend ?? 'json';
+    const resolvedDir = dir ?? config.index?.baseDir;
+    switch (resolvedBackend) {
+        case 'sqlite': {
+            console.warn('[storage] ⚠️  EXPERIMENTAL: SQLite backend is enabled. This feature has limited testing and may have data-loss or compatibility issues. Not recommended for production use.');
+            const dbPath = sqlitePath ?? config.storage?.sqlitePath ?? 'data/index.db';
+            return new sqliteStore_js_1.SqliteStore(dbPath);
+        }
+        case 'json':
+        default:
+            return new jsonFileStore_js_1.JsonFileStore(resolvedDir);
+    }
+}

package/dist/services/storage/hashUtils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared governance hashing utilities for storage backends.
+ *
+ * Both JsonFileStore and SqliteStore must produce identical governance hashes
+ * for the same set of entries. This module ensures that.
+ */
+import { InstructionEntry } from '../../models/instruction.js';
+/** @internal Governance projection for deterministic hashing. */
+export declare function projectGovernance(e: InstructionEntry): Record<string, unknown>;
+/** Compute deterministic governance hash from an array of entries. */
+export declare function computeGovernanceHashFromEntries(entries: InstructionEntry[]): string;

package/dist/services/storage/hashUtils.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Shared governance hashing utilities for storage backends.
+ *
+ * Both JsonFileStore and SqliteStore must produce identical governance hashes
+ * for the same set of entries. This module ensures that.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectGovernance = projectGovernance;
+exports.computeGovernanceHashFromEntries = computeGovernanceHashFromEntries;
+const crypto_1 = __importDefault(require("crypto"));
+/** @internal Governance projection for deterministic hashing. */
+function projectGovernance(e) {
+    return {
+        id: e.id,
+        title: e.title,
+        version: e.version ?? '0.0.0',
+        owner: e.owner ?? 'unowned',
+        priorityTier: e.priorityTier ?? 'P4',
+        nextReviewDue: e.nextReviewDue ?? '',
+        semanticSummarySha256: e.semanticSummary
+            ? crypto_1.default.createHash('sha256').update(e.semanticSummary).digest('hex')
+            : '',
+        changeLogLength: e.changeLog?.length ?? 0,
+    };
+}
+/** Compute deterministic governance hash from an array of entries. */
+function computeGovernanceHashFromEntries(entries) {
+    const sorted = [...entries].sort((a, b) => a.id.localeCompare(b.id));
+    const projection = sorted.map(e => JSON.stringify(projectGovernance(e)));
+    return crypto_1.default.createHash('sha256').update(projection.join('\n')).digest('hex');
+}

package/dist/services/storage/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Storage — Instruction storage abstraction layer.
+ *
+ * Exports the IInstructionStore interface and backend implementations.
+ * Backend selection is controlled by INDEX_SERVER_STORAGE_BACKEND env var.
+ */
+export type { IInstructionStore, ListOptions, QueryOptions, ScopedListOptions, SearchOptions, SearchResult, UsagePersistRecord, UsageTrackOptions, LoadResult, } from './types.js';
+export { JsonFileStore } from './jsonFileStore.js';
+export { SqliteStore } from './sqliteStore.js';
+export { createStore } from './factory.js';
+export { computeGovernanceHashFromEntries, projectGovernance } from './hashUtils.js';
+export type { StorageBackend } from './factory.js';

package/dist/services/storage/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Storage — Instruction storage abstraction layer.
+ *
+ * Exports the IInstructionStore interface and backend implementations.
+ * Backend selection is controlled by INDEX_SERVER_STORAGE_BACKEND env var.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectGovernance = exports.computeGovernanceHashFromEntries = exports.createStore = exports.SqliteStore = exports.JsonFileStore = void 0;
+var jsonFileStore_js_1 = require("./jsonFileStore.js");
+Object.defineProperty(exports, "JsonFileStore", { enumerable: true, get: function () { return jsonFileStore_js_1.JsonFileStore; } });
+var sqliteStore_js_1 = require("./sqliteStore.js");
+Object.defineProperty(exports, "SqliteStore", { enumerable: true, get: function () { return sqliteStore_js_1.SqliteStore; } });
+var factory_js_1 = require("./factory.js");
+Object.defineProperty(exports, "createStore", { enumerable: true, get: function () { return factory_js_1.createStore; } });
+var hashUtils_js_1 = require("./hashUtils.js");
+Object.defineProperty(exports, "computeGovernanceHashFromEntries", { enumerable: true, get: function () { return hashUtils_js_1.computeGovernanceHashFromEntries; } });
+Object.defineProperty(exports, "projectGovernance", { enumerable: true, get: function () { return hashUtils_js_1.projectGovernance; } });

package/dist/services/storage/jsonFileStore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * JsonFileStore — JSON-file-per-instruction storage backend.
+ *
+ * Wraps the existing file-based storage pattern: each instruction is a
+ * separate .json file in a directory. This is the default backend.
+ *
+ * Implements IInstructionStore for the storage abstraction layer.
+ */
+import { InstructionEntry } from '../../models/instruction.js';
+import type { IInstructionStore, ListOptions, QueryOptions, ScopedListOptions, SearchOptions, SearchResult, LoadResult } from './types.js';
+export declare class JsonFileStore implements IInstructionStore {
+    private readonly dir;
+    private cache;
+    private loaded;
+    /**
+     * @param dir - Directory containing instruction .json files.
+     */
+    constructor(dir: string);
+    load(): LoadResult;
+    close(): void;
+    get(id: string): InstructionEntry | null;
+    write(entry: InstructionEntry): void;
+    remove(id: string): void;
+    list(opts?: ListOptions): InstructionEntry[];
+    query(opts: QueryOptions): InstructionEntry[];
+    listScoped(opts: ScopedListOptions): InstructionEntry[];
+    search(opts: SearchOptions): SearchResult[];
+    categories(): Map<string, number>;
+    computeHash(): string;
+    count(): number;
+    private ensureLoaded;
+}