@jagilber-org/index-server 1.19.1

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

@@ -0,0 +1,171 @@
+/**
+ * IInstructionStore — Storage abstraction for instruction persistence.
+ *
+ * Implementations:
+ * - JsonFileStore: JSON-file-per-instruction (default, current behavior)
+ * - SqliteStore: SQLite database (experimental, behind feature flag)
+ *
+ * IndexContext delegates all storage I/O through this interface.
+ * Queries, search, and usage tracking are backend-agnostic.
+ */
+import { InstructionEntry } from '../../models/instruction.js';
+/** Options for listing instructions with filters. */
+export interface ListOptions {
+    category?: string;
+    contentType?: string;
+}
+/** Options for complex multi-filter queries. */
+export interface QueryOptions {
+    text?: string;
+    categoriesAny?: string[];
+    categoriesAll?: string[];
+    excludeCategories?: string[];
+    contentType?: string;
+    priorityMin?: number;
+    priorityMax?: number;
+    priorityTiers?: string[];
+    requirements?: string[];
+    offset?: number;
+    limit?: number;
+}
+/** Options for scoped listing (workspace/user/team). */
+export interface ScopedListOptions {
+    userId?: string;
+    workspaceId?: string;
+    teamIds?: string[];
+}
+/** Options for keyword search. */
+export interface SearchOptions {
+    keywords: string[];
+    includeCategories?: boolean;
+    caseSensitive?: boolean;
+    limit?: number;
+}
+/** A single search result with relevance score. */
+export interface SearchResult {
+    id: string;
+    score: number;
+}
+/** Persisted usage record for an instruction. */
+export interface UsagePersistRecord {
+    usageCount?: number;
+    firstSeenTs?: string;
+    lastUsedAt?: string;
+    lastAction?: string;
+    lastSignal?: string;
+    lastComment?: string;
+}
+/** Options for tracking a usage event. */
+export interface UsageTrackOptions {
+    action?: string;
+    signal?: string;
+    comment?: string;
+}
+/** Result of loading the full instruction set. */
+export interface LoadResult {
+    entries: InstructionEntry[];
+    hash: string;
+    errors: {
+        file: string;
+        error: string;
+    }[];
+    debug?: {
+        scanned: number;
+        accepted: number;
+        skipped: number;
+        trace?: {
+            file: string;
+            accepted: boolean;
+            reason?: string;
+        }[];
+    };
+    summary?: {
+        scanned: number;
+        accepted: number;
+        skipped: number;
+        reasons: Record<string, number>;
+        cacheHits?: number;
+        hashHits?: number;
+    };
+}
+/**
+ * Storage backend interface for the instruction index.
+ *
+ * All methods are synchronous unless otherwise noted (matching current
+ * IndexContext behavior). Async methods are marked with Promise return types.
+ *
+ * @remarks
+ * Implementations must ensure:
+ * - `load()` is idempotent and safe to call multiple times
+ * - `write()` is atomic (entry is fully written or not at all)
+ * - `remove()` tolerates missing IDs (no-op, no throw)
+ * - `computeHash()` returns identical hashes for identical entry sets
+ * - `get()` returns null for missing IDs (no throw)
+ */
+export interface IInstructionStore {
+    /**
+     * Load all instructions from the backing store.
+     * @returns Load result with entries, hash, and diagnostics.
+     */
+    load(): LoadResult;
+    /**
+     * Close the store and release resources (e.g., DB connections).
+     * No-op for file-based stores.
+     */
+    close(): void;
+    /**
+     * Get a single instruction by ID.
+     * @param id - Instruction ID.
+     * @returns The entry, or null if not found.
+     */
+    get(id: string): InstructionEntry | null;
+    /**
+     * Write (create or update) an instruction.
+     * @param entry - The instruction to persist.
+     */
+    write(entry: InstructionEntry): void;
+    /**
+     * Remove an instruction by ID. No-op if not found.
+     * @param id - Instruction ID to remove.
+     */
+    remove(id: string): void;
+    /**
+     * List instructions with optional category/contentType filter.
+     * @param opts - Filter options.
+     * @returns Array of matching entries.
+     */
+    list(opts?: ListOptions): InstructionEntry[];
+    /**
+     * Complex multi-filter query with pagination.
+     * @param opts - Query options.
+     * @returns Array of matching entries (paginated).
+     */
+    query(opts: QueryOptions): InstructionEntry[];
+    /**
+     * List instructions scoped to a user, workspace, or team.
+     * @param opts - Scoping options.
+     * @returns Array of matching entries.
+     */
+    listScoped(opts: ScopedListOptions): InstructionEntry[];
+    /**
+     * Search instructions by keywords with relevance scoring.
+     * @param opts - Search options with keywords.
+     * @returns Array of { id, score } sorted by relevance descending.
+     */
+    search(opts: SearchOptions): SearchResult[];
+    /**
+     * Get all unique categories with occurrence counts.
+     * @returns Map of category name → count.
+     */
+    categories(): Map<string, number>;
+    /**
+     * Compute deterministic governance hash over all entries.
+     * Must return identical hash for identical entry sets regardless of backend.
+     * @returns SHA256 hex string.
+     */
+    computeHash(): string;
+    /**
+     * Get the count of loaded instructions.
+     */
+    count(): number;
+}

package/dist/services/storage/types.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * IInstructionStore — Storage abstraction for instruction persistence.
+ *
+ * Implementations:
+ * - JsonFileStore: JSON-file-per-instruction (default, current behavior)
+ * - SqliteStore: SQLite database (experimental, behind feature flag)
+ *
+ * IndexContext delegates all storage I/O through this interface.
+ * Queries, search, and usage tracking are backend-agnostic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/services/toolHandlers.d.ts

@@ -0,0 +1,23 @@
+import { computeGovernanceHash, projectGovernance, getIndexState } from './indexContext';
+import './handlers.instructions';
+import './handlers.search';
+import './instructions.dispatcher';
+import './handlers.integrity';
+import './handlers.usage';
+import './handlers.prompt';
+import './handlers.metrics';
+import './handlers.gates';
+import './handlers.testPrimitive';
+import './handlers.diagnostics';
+import './handlers.feedback';
+import './handlers.help';
+import './handlers.instructionSchema';
+import './handlers.bootstrap';
+import './handlers.manifest';
+import './handlers.instructionsDiagnostics';
+import './handlers.graph';
+import './handlers.activation';
+import './handlers.promote';
+import './handlers.messaging';
+import './handlers.trace';
+export { computeGovernanceHash, projectGovernance, getIndexState };

package/dist/services/toolHandlers.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIndexState = exports.projectGovernance = exports.computeGovernanceHash = void 0;
+// Clean shim implementation
+const registry_1 = require("../server/registry");
+const toolRegistry_1 = require("./toolRegistry");
+const indexContext_1 = require("./indexContext");
+Object.defineProperty(exports, "computeGovernanceHash", { enumerable: true, get: function () { return indexContext_1.computeGovernanceHash; } });
+Object.defineProperty(exports, "projectGovernance", { enumerable: true, get: function () { return indexContext_1.projectGovernance; } });
+Object.defineProperty(exports, "getIndexState", { enumerable: true, get: function () { return indexContext_1.getIndexState; } });
+const runtimeConfig_1 = require("../config/runtimeConfig");
+// Side-effect registrations from modular handlers
+// IMPORTANT: Keep in sync with src/server/index-server.ts imports
+require("./handlers.instructions");
+require("./handlers.search");
+require("./instructions.dispatcher"); // ensure dispatcher registered regardless of server entrypoint
+require("./handlers.integrity");
+require("./handlers.usage");
+require("./handlers.prompt");
+require("./handlers.metrics");
+require("./handlers.gates");
+require("./handlers.testPrimitive"); // test helper primitive handler registration
+require("./handlers.diagnostics");
+require("./handlers.feedback");
+require("./handlers.help");
+require("./handlers.instructionSchema");
+require("./handlers.bootstrap");
+require("./handlers.manifest");
+require("./handlers.instructionsDiagnostics");
+require("./handlers.graph");
+require("./handlers.activation"); // VSCode activation guide for tool enablement
+require("./handlers.promote"); // promote_from_repo: scan repo & upsert into index
+require("./handlers.messaging"); // inter-agent messaging (not stored in instruction index)
+require("./handlers.trace"); // trace_dump: write in-memory trace ring buffer to file
+// Rich meta_tools implementation (stable vs dynamic)
+function mutationEnabled() { return (0, runtimeConfig_1.getRuntimeConfig)().mutation.enabled; }
+(0, registry_1.registerHandler)('meta_tools', () => {
+    const MUTATION_ENABLED = mutationEnabled();
+    const methods = (0, registry_1.listRegisteredMethods)();
+    const registry = (0, toolRegistry_1.getToolRegistry)({ tier: 'admin' });
+    const stableTools = new Set(Array.from(toolRegistry_1.STABLE));
+    const mutationSet = new Set(registry.filter(r => r.mutation).map(r => r.name));
+    const all = methods.map(m => ({ method: m, stable: stableTools.has(m), mutation: mutationSet.has(m), disabled: mutationSet.has(m) && !MUTATION_ENABLED }));
+    return {
+        tools: all.map(t => ({ method: t.method, stable: t.stable, mutation: t.mutation, disabled: t.disabled })),
+        stable: { tools: all.map(t => ({ method: t.method, stable: t.stable, mutation: t.mutation })) },
+        dynamic: { generatedAt: new Date().toISOString(), mutationEnabled: MUTATION_ENABLED, disabled: all.filter(t => t.disabled).map(t => ({ method: t.method })) },
+        mcp: { registryVersion: toolRegistry_1.REGISTRY_VERSION, tools: registry.map(r => ({ name: r.name, description: r.description, stable: r.stable, mutation: r.mutation, inputSchema: r.inputSchema, outputSchema: r.outputSchema })) }
+    };
+});

package/dist/services/toolRegistry.d.ts

@@ -0,0 +1,20 @@
+export type ToolTier = 'core' | 'extended' | 'admin';
+export interface ToolRegistryEntry {
+    name: string;
+    description: string;
+    stable: boolean;
+    mutation: boolean;
+    tier: ToolTier;
+    inputSchema: object;
+    outputSchema?: object;
+    zodSchema?: unknown;
+}
+export declare const STABLE: Set<string>;
+export declare const MUTATION: Set<string>;
+export interface ToolRegistryFilter {
+    tier?: ToolTier;
+}
+/** Resolve the maximum visible tier from feature flags. */
+export declare function resolveActiveTier(): ToolTier;
+export declare function getToolRegistry(filter?: ToolRegistryFilter): ToolRegistryEntry[];
+export declare const REGISTRY_VERSION = "2026-03-29";