@jagilber-org/index-server 1.19.1

package/dist/services/bootstrapGating.d.ts

@@ -0,0 +1,123 @@
+/** Returns `true` when the server is running in reference (read-only) mode. */
+export declare function isReferenceMode(): boolean;
+/** Returns `true` if bootstrap confirmation has been persisted or confirmed in memory. */
+export declare function isBootstrapConfirmed(): boolean;
+/**
+ * Returns `true` if the loaded index contains at least one instruction that is not a
+ * canonical bootstrap seed (i.e. the workspace has been customized beyond the defaults).
+ * @returns `true` when non-bootstrap instructions are present, `false` on empty or seed-only index
+ */
+export declare function hasNonBootstrapInstructions(): boolean;
+/**
+ * Returns `true` when the server must ask the operator to confirm before accepting mutations.
+ * Confirmation is required only when: not in reference mode, not already confirmed, and the
+ * index contains only bootstrap seed instructions.
+ * @returns `true` when mutation confirmation is still required, `false` otherwise
+ */
+export declare function shouldRequireConfirmation(): boolean;
+/**
+ * Returns the reason mutations are gated, or `null` when mutations are freely allowed.
+ * @returns A short reason string (`'reference_mode_read_only'` or `'bootstrap_confirmation_required'`),
+ *          or `null` if no gate is active
+ */
+export declare function mutationGatedReason(): string | null;
+/**
+ * Issue a short-lived one-time token that an operator must confirm to unlock mutations.
+ * Safe to call multiple times — returns the existing pending token if still valid.
+ * @param rationale - Optional hint text describing why bootstrap confirmation is being requested
+ * @returns An object with `token` (raw OTP for the operator) or a status flag when already confirmed/reference-mode
+ */
+export declare function requestBootstrapToken(rationale?: string): {
+    readonly referenceMode: true;
+    readonly mutation: false;
+    readonly alreadyConfirmed?: undefined;
+    readonly token?: undefined;
+    readonly hint?: undefined;
+    readonly expiresAt?: undefined;
+    readonly pending?: undefined;
+} | {
+    readonly alreadyConfirmed: true;
+    readonly referenceMode?: undefined;
+    readonly mutation?: undefined;
+    readonly token?: undefined;
+    readonly hint?: undefined;
+    readonly expiresAt?: undefined;
+    readonly pending?: undefined;
+} | {
+    readonly token: "(reissued)";
+    readonly hint: string;
+    readonly expiresAt: number;
+    readonly pending: true;
+    readonly referenceMode?: undefined;
+    readonly mutation?: undefined;
+    readonly alreadyConfirmed?: undefined;
+} | {
+    readonly token: string;
+    readonly expiresAt: number;
+    readonly hint: string;
+    readonly referenceMode?: undefined;
+    readonly mutation?: undefined;
+    readonly alreadyConfirmed?: undefined;
+    readonly pending?: undefined;
+};
+/**
+ * Validate the provided token against the pending OTP and, on success, persist confirmation.
+ * Once confirmed the workspace remains unlocked across process restarts until the file is removed.
+ * @param token - Raw OTP previously issued by {@link requestBootstrapToken}
+ * @returns An object with `confirmed: true` on success, or an `error` key describing the failure
+ */
+export declare function finalizeBootstrapToken(token: string): {
+    readonly referenceMode: true;
+    readonly mutation: false;
+    readonly alreadyConfirmed?: undefined;
+    error?: undefined;
+    readonly confirmed?: undefined;
+} | {
+    readonly alreadyConfirmed: true;
+    readonly referenceMode?: undefined;
+    readonly mutation?: undefined;
+    error?: undefined;
+    readonly confirmed?: undefined;
+} | {
+    readonly error: "no_pending_token";
+    readonly referenceMode?: undefined;
+    readonly mutation?: undefined;
+    readonly alreadyConfirmed?: undefined;
+    readonly confirmed?: undefined;
+} | {
+    readonly error: "token_expired";
+    readonly referenceMode?: undefined;
+    readonly mutation?: undefined;
+    readonly alreadyConfirmed?: undefined;
+    readonly confirmed?: undefined;
+} | {
+    readonly error: "invalid_token";
+    readonly referenceMode?: undefined;
+    readonly mutation?: undefined;
+    readonly alreadyConfirmed?: undefined;
+    readonly confirmed?: undefined;
+} | {
+    readonly confirmed: true;
+    readonly referenceMode?: undefined;
+    readonly mutation?: undefined;
+    readonly alreadyConfirmed?: undefined;
+    error?: undefined;
+};
+/**
+ * Return the current bootstrap gating status as a plain object.
+ * @returns Object with `referenceMode`, `confirmed`, `requireConfirmation`, and `nonBootstrapInstructions` flags
+ */
+export declare function getBootstrapStatus(): {
+    referenceMode: boolean;
+    confirmed: boolean;
+    requireConfirmation: boolean;
+    nonBootstrapInstructions: boolean;
+};
+export declare const BOOTSTRAP_ALLOWLIST: Set<string>;
+/**
+ * Force bootstrap confirmation for test environments. Only runs when
+ * `INDEX_SERVER_BOOTSTRAP_AUTOCONFIRM=1` is set. Has no effect in reference mode.
+ * @param reason - Descriptive label written to the confirmation artifact (default: `'auto-confirm (test)'`)
+ * @returns `true` if confirmation was set successfully, `false` if already confirmed or an error occurred
+ */
+export declare function forceBootstrapConfirmForTests(reason?: string): boolean;

package/dist/services/bootstrapGating.js

@@ -0,0 +1,221 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOOTSTRAP_ALLOWLIST = void 0;
+exports.isReferenceMode = isReferenceMode;
+exports.isBootstrapConfirmed = isBootstrapConfirmed;
+exports.hasNonBootstrapInstructions = hasNonBootstrapInstructions;
+exports.shouldRequireConfirmation = shouldRequireConfirmation;
+exports.mutationGatedReason = mutationGatedReason;
+exports.requestBootstrapToken = requestBootstrapToken;
+exports.finalizeBootstrapToken = finalizeBootstrapToken;
+exports.getBootstrapStatus = getBootstrapStatus;
+exports.forceBootstrapConfirmForTests = forceBootstrapConfirmForTests;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const indexContext_1 = require("./indexContext");
+const runtimeConfig_1 = require("../config/runtimeConfig");
+/**
+ * Bootstrap / confirmation gating logic.
+ * States:
+ *  - reference mode (INDEX_SERVER_REFERENCE_MODE=1): index is read-only, all mutation blocked permanently
+ *  - new workspace: only bootstrap seed instructions present (000-bootstrapper / 001-lifecycle-bootstrap) → require confirmation
+ *  - existing workspace: any non-bootstrap instruction present OR confirmation file exists -> mutation allowed (subject to INDEX_SERVER_MUTATION rules)
+ *  - confirmed: confirmation file created after successful finalize → persists across restarts
+ */
+const BOOTSTRAP_IDS = new Set(['000-bootstrapper', '001-lifecycle-bootstrap']);
+const CONFIRM_FILE = 'bootstrap.confirmed.json';
+const PENDING_FILE = 'bootstrap.pending.json';
+let inMemoryPending = null;
+let confirmed = false;
+let loaded = false;
+function bootstrapConfig() {
+    return (0, runtimeConfig_1.getRuntimeConfig)().server.bootstrap;
+}
+function instructionsDirSafe() {
+    try {
+        return (0, indexContext_1.getInstructionsDir)();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+function loadState() {
+    if (loaded)
+        return;
+    loaded = true;
+    if (isReferenceMode())
+        return; // nothing to load
+    try {
+        const dir = instructionsDirSafe();
+        const file = path_1.default.join(dir, CONFIRM_FILE);
+        if (fs_1.default.existsSync(file)) {
+            confirmed = true; // minimal persistence flag
+        }
+    }
+    catch { /* ignore */ }
+}
+/** Returns `true` when the server is running in reference (read-only) mode. */
+function isReferenceMode() { return bootstrapConfig().referenceMode; }
+/** Returns `true` if bootstrap confirmation has been persisted or confirmed in memory. */
+function isBootstrapConfirmed() { loadState(); return confirmed; }
+/**
+ * Returns `true` if the loaded index contains at least one instruction that is not a
+ * canonical bootstrap seed (i.e. the workspace has been customized beyond the defaults).
+ * @returns `true` when non-bootstrap instructions are present, `false` on empty or seed-only index
+ */
+function hasNonBootstrapInstructions() {
+    try {
+        const st = (0, indexContext_1.ensureLoaded)();
+        for (const e of st.list) {
+            if (!BOOTSTRAP_IDS.has(e.id))
+                return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns `true` when the server must ask the operator to confirm before accepting mutations.
+ * Confirmation is required only when: not in reference mode, not already confirmed, and the
+ * index contains only bootstrap seed instructions.
+ * @returns `true` when mutation confirmation is still required, `false` otherwise
+ */
+function shouldRequireConfirmation() {
+    if (isReferenceMode())
+        return false; // immutable anyway
+    if (isBootstrapConfirmed())
+        return false;
+    if (hasNonBootstrapInstructions())
+        return false; // existing workspace
+    return true; // only seeds present
+}
+/**
+ * Returns the reason mutations are gated, or `null` when mutations are freely allowed.
+ * @returns A short reason string (`'reference_mode_read_only'` or `'bootstrap_confirmation_required'`),
+ *          or `null` if no gate is active
+ */
+function mutationGatedReason() {
+    if (isReferenceMode())
+        return 'reference_mode_read_only';
+    if (shouldRequireConfirmation())
+        return 'bootstrap_confirmation_required';
+    return null;
+}
+/**
+ * Issue a short-lived one-time token that an operator must confirm to unlock mutations.
+ * Safe to call multiple times — returns the existing pending token if still valid.
+ * @param rationale - Optional hint text describing why bootstrap confirmation is being requested
+ * @returns An object with `token` (raw OTP for the operator) or a status flag when already confirmed/reference-mode
+ */
+function requestBootstrapToken(rationale) {
+    if (isReferenceMode())
+        return { referenceMode: true, mutation: false };
+    if (isBootstrapConfirmed())
+        return { alreadyConfirmed: true };
+    // issue or reuse pending if still valid
+    const now = Date.now();
+    if (inMemoryPending && inMemoryPending.expiresAt > now) {
+        return { token: '(reissued)', hint: inMemoryPending.hint, expiresAt: inMemoryPending.expiresAt, pending: true };
+    }
+    const raw = crypto_1.default.randomBytes(6).toString('hex');
+    const hash = crypto_1.default.createHash('sha256').update(raw, 'utf8').digest('hex');
+    const expiresSec = Math.max(1, bootstrapConfig().tokenTtlSec);
+    const rec = { hash, expiresAt: now + (expiresSec * 1000), issuedAt: now, hint: rationale || 'Human operator: review context, then provide token to bootstrap_confirmFinalize.' };
+    inMemoryPending = rec;
+    // Persist (best-effort): do not write the raw token, only its hash
+    try {
+        const dir = instructionsDirSafe();
+        fs_1.default.writeFileSync(path_1.default.join(dir, PENDING_FILE), JSON.stringify({ issuedAt: rec.issuedAt, expiresAt: rec.expiresAt }, null, 2));
+    }
+    catch { /* ignore */ }
+    return { token: raw, expiresAt: rec.expiresAt, hint: rec.hint };
+}
+/**
+ * Validate the provided token against the pending OTP and, on success, persist confirmation.
+ * Once confirmed the workspace remains unlocked across process restarts until the file is removed.
+ * @param token - Raw OTP previously issued by {@link requestBootstrapToken}
+ * @returns An object with `confirmed: true` on success, or an `error` key describing the failure
+ */
+function finalizeBootstrapToken(token) {
+    if (isReferenceMode())
+        return { referenceMode: true, mutation: false };
+    if (isBootstrapConfirmed())
+        return { alreadyConfirmed: true };
+    if (!inMemoryPending)
+        return { error: 'no_pending_token' };
+    const now = Date.now();
+    if (inMemoryPending.expiresAt <= now) {
+        inMemoryPending = null;
+        return { error: 'token_expired' };
+    }
+    const hash = crypto_1.default.createHash('sha256').update(token, 'utf8').digest('hex');
+    const pendingHashBuf = Buffer.from(inMemoryPending.hash, 'hex');
+    const tokenHashBuf = Buffer.from(hash, 'hex');
+    if (pendingHashBuf.length !== tokenHashBuf.length || !crypto_1.default.timingSafeEqual(pendingHashBuf, tokenHashBuf))
+        return { error: 'invalid_token' };
+    confirmed = true;
+    try {
+        const dir = instructionsDirSafe();
+        const rec = { confirmedAt: new Date().toISOString(), tokenHint: inMemoryPending.hint };
+        fs_1.default.writeFileSync(path_1.default.join(dir, CONFIRM_FILE), JSON.stringify(rec, null, 2));
+    }
+    catch { /* ignore */ }
+    inMemoryPending = null;
+    return { confirmed: true };
+}
+/**
+ * Return the current bootstrap gating status as a plain object.
+ * @returns Object with `referenceMode`, `confirmed`, `requireConfirmation`, and `nonBootstrapInstructions` flags
+ */
+function getBootstrapStatus() {
+    return {
+        referenceMode: isReferenceMode(),
+        confirmed: isBootstrapConfirmed(),
+        requireConfirmation: shouldRequireConfirmation(),
+        nonBootstrapInstructions: hasNonBootstrapInstructions()
+    };
+}
+exports.BOOTSTRAP_ALLOWLIST = BOOTSTRAP_IDS; // re-export for risk computation allowlist
+// ----------------------------------------------------------------------------------
+// Test Support: Optional force-confirm path (never used in production flows)
+// ----------------------------------------------------------------------------------
+// Some integration tests pre-date bootstrap confirmation and expect immediate
+// mutation capability. To avoid invasive edits across dozens of tests we expose
+// a narrow helper that marks the workspace as confirmed when an opt‑in
+// environment variable (INDEX_SERVER_BOOTSTRAP_AUTOCONFIRM=1) is set. This writes the
+// same confirmation artifact the manual token flow would create so subsequent
+// real runs still observe the confirmed state. Reference mode intentionally
+// bypasses any force confirmation.
+//
+// IMPORTANT: This function is intentionally not exported via tool surfaces and
+// should only be invoked programmatically by the server on startup when the
+// explicit test environment variable is present. It is safe because it requires
+// direct code execution (cannot be triggered by an MCP client) and mirrors the
+// final persisted shape of a legitimate confirmation.
+/**
+ * Force bootstrap confirmation for test environments. Only runs when
+ * `INDEX_SERVER_BOOTSTRAP_AUTOCONFIRM=1` is set. Has no effect in reference mode.
+ * @param reason - Descriptive label written to the confirmation artifact (default: `'auto-confirm (test)'`)
+ * @returns `true` if confirmation was set successfully, `false` if already confirmed or an error occurred
+ */
+function forceBootstrapConfirmForTests(reason = 'auto-confirm (test)') {
+    if (isReferenceMode())
+        return false;
+    if (confirmed)
+        return true;
+    try {
+        const dir = instructionsDirSafe();
+        const rec = { confirmedAt: new Date().toISOString(), tokenHint: reason };
+        fs_1.default.writeFileSync(path_1.default.join(dir, CONFIRM_FILE), JSON.stringify(rec, null, 2));
+        confirmed = true;
+        return true;
+    }
+    catch { /* ignore */ }
+    return false;
+}

package/dist/services/canonical.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Canonicalize instruction body text for hashing & comparison.
+ * Non-destructive normalization choices are intentionally conservative to avoid
+ * retroactive hash churn across existing index entries while still removing
+ * accidental instability sources (line ending variance, trailing spaces, outer blank lines).
+ *
+ * Rules:
+ *  - Normalize CRLF/CR to LF
+ *  - Strip trailing spaces / tabs from each line
+ *  - Trim leading & trailing blank lines
+ *  - Collapse runs of >2 blank lines to a single blank line (optional; disabled by default)
+ *
+ * NOTE: We do NOT reorder semantic list blocks or collapse internal single blank lines so that
+ * meaningful ordering (e.g., link lists) still produces distinct hashes.
+ * @param body - Raw instruction body text to normalize
+ * @param options - Optional normalization options
+ * @param options.collapseMultipleBlankLines - When `true`, runs of more than one blank line are collapsed to a single blank line
+ * @returns Canonicalized body string
+ */
+export declare function canonicalizeBody(body: string, options?: {
+    collapseMultipleBlankLines?: boolean;
+}): string;
+export declare function hashBody(body: string): string;

package/dist/services/canonical.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalizeBody = canonicalizeBody;
+exports.hashBody = hashBody;
+/**
+ * Canonicalize instruction body text for hashing & comparison.
+ * Non-destructive normalization choices are intentionally conservative to avoid
+ * retroactive hash churn across existing index entries while still removing
+ * accidental instability sources (line ending variance, trailing spaces, outer blank lines).
+ *
+ * Rules:
+ *  - Normalize CRLF/CR to LF
+ *  - Strip trailing spaces / tabs from each line
+ *  - Trim leading & trailing blank lines
+ *  - Collapse runs of >2 blank lines to a single blank line (optional; disabled by default)
+ *
+ * NOTE: We do NOT reorder semantic list blocks or collapse internal single blank lines so that
+ * meaningful ordering (e.g., link lists) still produces distinct hashes.
+ * @param body - Raw instruction body text to normalize
+ * @param options - Optional normalization options
+ * @param options.collapseMultipleBlankLines - When `true`, runs of more than one blank line are collapsed to a single blank line
+ * @returns Canonicalized body string
+ */
+function canonicalizeBody(body, options) {
+    if (typeof body !== 'string')
+        body = String(body || '');
+    // Normalize line endings
+    const text = body.replace(/\r\n?|\u2028|\u2029/g, '\n');
+    // Split & trim right side whitespace
+    const lines = text.split('\n').map(l => l.replace(/[ \t]+$/, ''));
+    // Trim leading blank lines
+    while (lines.length && lines[0].trim() === '')
+        lines.shift();
+    // Trim trailing blank lines
+    while (lines.length && lines[lines.length - 1].trim() === '')
+        lines.pop();
+    if (options?.collapseMultipleBlankLines) {
+        const collapsed = [];
+        let blankRun = 0;
+        for (const l of lines) {
+            if (l.trim() === '') {
+                blankRun++;
+                if (blankRun > 1)
+                    continue; // keep only one
+            }
+            else
+                blankRun = 0;
+            collapsed.push(l);
+        }
+        return collapsed.join('\n');
+    }
+    return lines.join('\n');
+}
+/** Compute stable SHA-256 hash over canonicalized body.
+ * @param body - Raw instruction body text
+ * @returns Hex-encoded SHA-256 digest of the canonicalized body
+ */
+const crypto_1 = __importDefault(require("crypto"));
+function hashBody(body) {
+    const canon = canonicalizeBody(body);
+    return crypto_1.default.createHash('sha256').update(canon, 'utf8').digest('hex');
+}

package/dist/services/categoryRules.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared category derivation rules for instruction classification.
+ * Used by the embeddings dashboard and the groom remapCategories mode.
+ * Order matters — first match wins.
+ */
+export declare const CATEGORY_RULES: [RegExp, string][];
+export declare function deriveCategory(id: string): string;

package/dist/services/categoryRules.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Shared category derivation rules for instruction classification.
+ * Used by the embeddings dashboard and the groom remapCategories mode.
+ * Order matters — first match wins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CATEGORY_RULES = void 0;
+exports.deriveCategory = deriveCategory;
+exports.CATEGORY_RULES = [
+    [/azure|arm-template|apim|batch|vmss/, 'Azure'],
+    [/\bsf[-_]|service-fabric|servicefabric|collectsf|sfrp/, 'Service Fabric'],
+    [/\bagent\b|agent[-_]/, 'Agent'],
+    [/\bmcp\b|mcp[-_]/, 'MCP'],
+    [/powershell|pwsh/, 'PowerShell'],
+    [/vscode|vs-code|copilot/, 'VS Code'],
+    [/\bai[-_]|\bml[-_]|\bllm\b|openai|gpt\d/, 'AI/ML'],
+    [/\bgit[-_]|\brepo[-_]|github/, 'Git/Repo'],
+    [/\btest|\bspec[-_]|vitest|playwright/, 'Testing'],
+    [/kusto|\bkql\b/, 'Kusto'],
+    [/dotnet|csharp/, '.NET'],
+    [/mermaid/, 'Mermaid'],
+    [/debug|troubleshoot/, 'Debugging'],
+    [/docker|container/, 'Containers'],
+    [/security|\bauth[-_]|authentication|secret-protection/, 'Security'],
+    [/runbook|\bguide\b/, 'Runbooks/Guides'],
+    [/\bgov[-_]|governance/, 'Governance'],
+    [/\bicm[-_]|incident/, 'Operations'],
+    [/onenote|markdown/, 'Documentation'],
+];
+function deriveCategory(id) {
+    for (const [pattern, category] of exports.CATEGORY_RULES) {
+        if (pattern.test(id))
+            return category;
+    }
+    return 'Other';
+}

package/dist/services/classificationService.d.ts

@@ -0,0 +1,42 @@
+import { InstructionEntry, RequirementLevel } from '../models/instruction';
+export interface NormalizedInstruction extends InstructionEntry {
+}
+export declare class ClassificationService {
+    /**
+     * Normalize an instruction entry by filling governance defaults, deriving scope fields,
+     * computing hashes, and canonicalizing text fields.
+     * @param entry - Raw instruction entry to normalize
+     * @returns A fully normalized {@link NormalizedInstruction} with all governance defaults applied
+     */
+    normalize(entry: InstructionEntry): NormalizedInstruction;
+    /**
+     * Validate an instruction entry for required fields and logical consistency.
+     * @param entry - Instruction entry to validate
+     * @returns Array of human-readable issue strings; empty when the entry is valid
+     */
+    validate(entry: InstructionEntry): string[];
+    /**
+     * Compute a numeric risk score for an instruction entry (higher = riskier).
+     * Score is derived from priority and requirement level.
+     * @param entry - Instruction entry to score
+     * @returns Numeric risk score
+     */
+    computeRisk(entry: InstructionEntry): number;
+    private requirementWeight;
+    /**
+     * Compute a SHA-256 hex digest of the given content string.
+     * @param content - UTF-8 string to hash
+     * @returns 64-character hex-encoded SHA-256 digest
+     */
+    computeHash(content: string): string;
+    private computePriorityTier;
+    private reviewIntervalDays;
+    /**
+     * Compute the recommended review interval in days for a given priority tier and requirement level.
+     * @param tier - Priority tier (`'P1'`–`'P4'`; P1 is highest priority)
+     * @param requirement - Requirement level for the instruction
+     * @returns Number of days until the next review should occur
+     */
+    computeReviewIntervalDays(tier: 'P1' | 'P2' | 'P3' | 'P4', requirement: RequirementLevel): number;
+    private deriveSummary;
+}