@jagilber-org/index-server 1.19.1

package/dist/services/handlers/instructions.groom.js

@@ -0,0 +1,523 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const registry_1 = require("../../server/registry");
+const indexContext_1 = require("../indexContext");
+const auditLog_1 = require("../auditLog");
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+const manifestManager_1 = require("../manifestManager");
+const schemaVersion_1 = require("../../versioning/schemaVersion");
+const categoryRules_1 = require("../categoryRules");
+const canonical_1 = require("../canonical");
+const instructions_shared_1 = require("./instructions.shared");
+(0, registry_1.registerHandler)('index_enrich', (0, instructions_shared_1.guard)('index_enrich', () => {
+    const st = (0, indexContext_1.ensureLoaded)();
+    const baseDir = (0, indexContext_1.getInstructionsDir)();
+    let rewritten = 0;
+    const updated = [];
+    const skipped = [];
+    for (const e of st.list) {
+        const file = path_1.default.join(baseDir, `${e.id}.json`);
+        if (!fs_1.default.existsSync(file))
+            continue;
+        try {
+            const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+            let needs = false;
+            const nowIso = new Date().toISOString();
+            if (!(typeof raw.sourceHash === 'string' && raw.sourceHash.length > 0)) {
+                raw.sourceHash = e.sourceHash || crypto_1.default.createHash('sha256').update(String(e.body || ''), 'utf8').digest('hex');
+                needs = true;
+            }
+            if (typeof raw.createdAt === 'string' && raw.createdAt.length === 0) {
+                raw.createdAt = e.createdAt || nowIso;
+                needs = true;
+            }
+            if (typeof raw.updatedAt === 'string' && raw.updatedAt.length === 0) {
+                raw.updatedAt = e.updatedAt || nowIso;
+                needs = true;
+            }
+            if (raw.owner === 'unowned' && e.owner && e.owner !== 'unowned') {
+                raw.owner = e.owner;
+                needs = true;
+            }
+            if ((raw.priorityTier === undefined || raw.priorityTier === null || raw.priorityTier === '') && e.priorityTier) {
+                raw.priorityTier = e.priorityTier;
+                needs = true;
+            }
+            if (!(typeof raw.semanticSummary === 'string' && raw.semanticSummary.length > 0) && e.semanticSummary) {
+                raw.semanticSummary = e.semanticSummary;
+                needs = true;
+            }
+            const apply = (k) => {
+                const onDisk = raw[k];
+                const norm = e[k];
+                switch (k) {
+                    case 'sourceHash':
+                        if (!(typeof onDisk === 'string' && onDisk.length > 0) && typeof norm === 'string') {
+                            raw[k] = norm;
+                            needs = true;
+                        }
+                        break;
+                    case 'owner':
+                        if (onDisk === 'unowned' && typeof norm === 'string' && norm !== 'unowned') {
+                            raw[k] = norm;
+                            needs = true;
+                        }
+                        break;
+                    case 'updatedAt':
+                        if (typeof onDisk === 'string' && onDisk.length === 0 && typeof norm === 'string' && norm.length > 0) {
+                            raw[k] = norm;
+                            needs = true;
+                        }
+                        break;
+                    case 'priorityTier':
+                        if ((onDisk === undefined || onDisk === null || onDisk === '') && typeof norm === 'string') {
+                            raw[k] = norm;
+                            needs = true;
+                        }
+                        break;
+                    case 'semanticSummary':
+                        if (!(typeof onDisk === 'string' && onDisk.length > 0) && typeof norm === 'string') {
+                            raw[k] = norm;
+                            needs = true;
+                        }
+                        break;
+                    case 'contentType':
+                        if (!onDisk && typeof norm === 'string') {
+                            raw[k] = norm;
+                            needs = true;
+                        }
+                        break;
+                    default: break;
+                }
+            };
+            apply('sourceHash');
+            apply('owner');
+            apply('createdAt');
+            apply('updatedAt');
+            apply('priorityTier');
+            apply('semanticSummary');
+            apply('contentType');
+            if (needs) {
+                fs_1.default.writeFileSync(file, JSON.stringify(raw, null, 2));
+                rewritten++;
+                updated.push(e.id);
+            }
+            else {
+                skipped.push(e.id);
+            }
+        }
+        catch { /* ignore */ }
+    }
+    if (rewritten) {
+        (0, indexContext_1.touchIndexVersion)();
+        (0, indexContext_1.invalidate)();
+        (0, indexContext_1.ensureLoaded)();
+    }
+    const resp = { rewritten, updated, skipped };
+    if (rewritten) {
+        (0, auditLog_1.logAudit)('enrich', updated, { rewritten, skipped: skipped.length });
+        (0, manifestManager_1.attemptManifestUpdate)();
+    }
+    return resp;
+}));
+(0, registry_1.registerHandler)('index_repair', (0, instructions_shared_1.guard)('index_repair', (_p) => {
+    const st = (0, indexContext_1.ensureLoaded)();
+    const toFix = [];
+    for (const e of st.list) {
+        const actual = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+        if (actual !== e.sourceHash)
+            toFix.push({ entry: e, actual });
+    }
+    if (!toFix.length)
+        return { repaired: 0, updated: [] };
+    const repaired = [];
+    for (const { entry, actual } of toFix) {
+        const file = path_1.default.join((0, indexContext_1.getInstructionsDir)(), `${entry.id}.json`);
+        try {
+            const updated = { ...entry, sourceHash: actual, updatedAt: new Date().toISOString() };
+            fs_1.default.writeFileSync(file, JSON.stringify(updated, null, 2));
+            repaired.push(entry.id);
+        }
+        catch { /* ignore */ }
+    }
+    if (repaired.length) {
+        (0, indexContext_1.touchIndexVersion)();
+        (0, indexContext_1.invalidate)();
+        (0, indexContext_1.ensureLoaded)();
+    }
+    const resp = { repaired: repaired.length, updated: repaired };
+    if (repaired.length) {
+        (0, auditLog_1.logAudit)('repair', repaired, { repaired: repaired.length });
+        (0, manifestManager_1.attemptManifestUpdate)();
+    }
+    return resp;
+}));
+(0, registry_1.registerHandler)('index_groom', (0, instructions_shared_1.guard)('index_groom', (p) => {
+    const mode = p.mode || {};
+    const dryRun = !!mode.dryRun;
+    const removeDeprecated = !!mode.removeDeprecated;
+    const mergeDuplicates = !!mode.mergeDuplicates;
+    const purgeLegacyScopes = !!mode.purgeLegacyScopes;
+    const remapCategories = !!mode.remapCategories;
+    const stBefore = (0, indexContext_1.ensureLoaded)();
+    const previousHash = stBefore.hash;
+    const scanned = stBefore.list.length;
+    let repairedHashes = 0, normalizedCategories = 0, deprecatedRemoved = 0, duplicatesMerged = 0, filesRewritten = 0, purgedScopes = 0, migrated = 0, remappedCategories = 0;
+    const notes = [];
+    const byId = new Map();
+    stBefore.list.forEach(e => byId.set(e.id, { ...e }));
+    const updated = new Set();
+    for (const e of byId.values()) {
+        const migrationResult = (0, schemaVersion_1.migrateInstructionRecord)(e);
+        if (migrationResult.changed) {
+            migrated++;
+            updated.add(e.id);
+        }
+    }
+    let signalApplied = 0;
+    {
+        const usageSnap = (0, indexContext_1.loadUsageSnapshot)();
+        for (const e of byId.values()) {
+            const rec = usageSnap[e.id];
+            if (!rec?.lastSignal)
+                continue;
+            const sig = rec.lastSignal;
+            let mutated = false;
+            if (sig === 'outdated') {
+                if (e.requirement !== 'deprecated') {
+                    e.requirement = 'deprecated';
+                    e.updatedAt = new Date().toISOString();
+                    mutated = true;
+                }
+            }
+            else if (sig === 'not-relevant') {
+                const np = Math.max(30, (e.priority ?? 50) - 10);
+                if (np !== e.priority) {
+                    e.priority = np;
+                    e.updatedAt = new Date().toISOString();
+                    mutated = true;
+                }
+            }
+            else if (sig === 'helpful') {
+                const np = Math.min(100, (e.priority ?? 50) + 5);
+                if (np !== e.priority) {
+                    e.priority = np;
+                    e.updatedAt = new Date().toISOString();
+                    mutated = true;
+                }
+            }
+            else if (sig === 'applied') {
+                const np = Math.min(100, (e.priority ?? 50) + 2);
+                if (np !== e.priority) {
+                    e.priority = np;
+                    e.updatedAt = new Date().toISOString();
+                    mutated = true;
+                }
+            }
+            if (mutated) {
+                signalApplied++;
+                updated.add(e.id);
+            }
+        }
+    }
+    const isJunkCategory = (cat) => /^\d/.test(cat) || cat.length <= 1 || /^case-\d{6,}$/.test(cat);
+    for (const e of byId.values()) {
+        let normCats = Array.from(new Set((e.categories || []).filter(c => typeof c === 'string').map(c => c.toLowerCase())));
+        normCats = normCats.filter(c => !isJunkCategory(c));
+        normCats = normCats.filter(cat => !(cat.endsWith('s') && normCats.includes(cat.slice(0, -1))));
+        normCats = normCats.sort();
+        if (JSON.stringify(normCats) !== JSON.stringify(e.categories)) {
+            e.categories = normCats;
+            normalizedCategories++;
+            e.updatedAt = new Date().toISOString();
+            updated.add(e.id);
+        }
+    }
+    const duplicateBodies = new Set();
+    if (mergeDuplicates) {
+        const groups = new Map();
+        for (const e of byId.values()) {
+            const key = e.sourceHash || crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+            const arr = groups.get(key) || [];
+            arr.push(e);
+            groups.set(key, arr);
+        }
+        for (const group of groups.values()) {
+            if (group.length <= 1)
+                continue;
+            let primary = group[0];
+            for (const candidate of group) {
+                if (candidate.createdAt && primary.createdAt) {
+                    if (candidate.createdAt < primary.createdAt)
+                        primary = candidate;
+                }
+                else if (!primary.createdAt && candidate.createdAt) {
+                    primary = candidate;
+                }
+                else if (candidate.id < primary.id) {
+                    primary = candidate;
+                }
+            }
+            for (const dup of group) {
+                if (dup.id === primary.id)
+                    continue;
+                if (dup.priority < primary.priority) {
+                    primary.priority = dup.priority;
+                    updated.add(primary.id);
+                }
+                if (typeof dup.riskScore === 'number') {
+                    if (typeof primary.riskScore !== 'number' || dup.riskScore > primary.riskScore) {
+                        primary.riskScore = dup.riskScore;
+                        updated.add(primary.id);
+                    }
+                }
+                const mergedCats = Array.from(new Set([...(primary.categories || []), ...(dup.categories || [])])).sort();
+                if (JSON.stringify(mergedCats) !== JSON.stringify(primary.categories)) {
+                    primary.categories = mergedCats;
+                    updated.add(primary.id);
+                }
+                if (removeDeprecated) {
+                    duplicateBodies.add(dup.id);
+                }
+                else {
+                    if (dup.deprecatedBy !== primary.id) {
+                        dup.deprecatedBy = primary.id;
+                        dup.requirement = 'deprecated';
+                        dup.updatedAt = new Date().toISOString();
+                        updated.add(dup.id);
+                    }
+                }
+                duplicatesMerged++;
+            }
+        }
+    }
+    const toRemove = [];
+    if (removeDeprecated) {
+        for (const e of byId.values()) {
+            if (e.deprecatedBy && byId.has(e.deprecatedBy))
+                toRemove.push(e.id);
+        }
+        for (const id of duplicateBodies) {
+            if (!toRemove.includes(id))
+                toRemove.push(id);
+        }
+    }
+    if (purgeLegacyScopes) {
+        const baseDir = (0, indexContext_1.getInstructionsDir)();
+        for (const e of byId.values()) {
+            const filePath = path_1.default.join(baseDir, `${e.id}.json`);
+            try {
+                if (fs_1.default.existsSync(filePath)) {
+                    const raw = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
+                    if (Array.isArray(raw.categories)) {
+                        const legacyTokens = raw.categories.filter(c => typeof c === 'string' && /^scope:(workspace|user|team):/.test(c));
+                        if (legacyTokens.length) {
+                            purgedScopes += legacyTokens.length;
+                            updated.add(e.id);
+                        }
+                    }
+                }
+            }
+            catch { /* ignore */ }
+        }
+        if (dryRun && purgedScopes)
+            notes.push(`would-purge:${purgedScopes}`);
+    }
+    if (remapCategories) {
+        for (const e of byId.values()) {
+            if (e.primaryCategory && e.primaryCategory !== 'uncategorized')
+                continue;
+            const derived = (0, categoryRules_1.deriveCategory)(e.id);
+            if (derived === 'Other')
+                continue;
+            e.primaryCategory = derived.toLowerCase();
+            const lc = derived.toLowerCase();
+            if (!e.categories.includes(lc)) {
+                e.categories = [...e.categories, lc].sort();
+            }
+            e.updatedAt = new Date().toISOString();
+            remappedCategories++;
+            updated.add(e.id);
+        }
+    }
+    {
+        const baseDir = (0, indexContext_1.getInstructionsDir)();
+        for (const e of byId.values()) {
+            const filePath = path_1.default.join(baseDir, `${e.id}.json`);
+            let storedHash = e.sourceHash || '';
+            try {
+                if (fs_1.default.existsSync(filePath)) {
+                    const raw = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
+                    if (typeof raw.sourceHash === 'string')
+                        storedHash = raw.sourceHash;
+                }
+            }
+            catch (_err) { /* ignore read error */ }
+            const actualHash = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+            if (storedHash !== actualHash) {
+                e.sourceHash = actualHash;
+                repairedHashes++;
+                e.updatedAt = new Date().toISOString();
+                updated.add(e.id);
+            }
+        }
+    }
+    deprecatedRemoved = toRemove.length;
+    if (!dryRun) {
+        const baseDir = (0, indexContext_1.getInstructionsDir)();
+        for (const id of toRemove) {
+            byId.delete(id);
+        }
+        for (const id of updated) {
+            if (!byId.has(id))
+                continue;
+            const e = byId.get(id);
+            try {
+                fs_1.default.writeFileSync(path_1.default.join(baseDir, `${id}.json`), JSON.stringify(e, null, 2));
+                filesRewritten++;
+            }
+            catch (err) {
+                notes.push(`write-failed:${id}:${err.message}`);
+            }
+        }
+        for (const id of toRemove) {
+            try {
+                fs_1.default.unlinkSync(path_1.default.join(baseDir, `${id}.json`));
+            }
+            catch (err) {
+                notes.push(`delete-failed:${id}:${err.message}`);
+            }
+        }
+        if (updated.size || toRemove.length) {
+            (0, indexContext_1.touchIndexVersion)();
+            (0, indexContext_1.invalidate)();
+            (0, indexContext_1.ensureLoaded)();
+        }
+    }
+    else {
+        if (updated.size)
+            notes.push(`would-rewrite:${updated.size}`);
+        if (toRemove.length)
+            notes.push(`would-remove:${toRemove.length}`);
+    }
+    const stAfter = (0, indexContext_1.ensureLoaded)();
+    const resp = { previousHash, hash: stAfter.hash, scanned, repairedHashes, normalizedCategories, deprecatedRemoved, duplicatesMerged, signalApplied, filesRewritten, purgedScopes, migrated, remappedCategories, dryRun, notes };
+    if (!dryRun && (repairedHashes || normalizedCategories || deprecatedRemoved || duplicatesMerged || signalApplied || filesRewritten || purgedScopes || migrated || remappedCategories)) {
+        (0, auditLog_1.logAudit)('groom', undefined, { repairedHashes, normalizedCategories, deprecatedRemoved, duplicatesMerged, signalApplied, filesRewritten, purgedScopes, migrated, remappedCategories });
+        (0, manifestManager_1.attemptManifestUpdate)();
+    }
+    return resp;
+}));
+(0, registry_1.registerHandler)('index_normalize', (0, instructions_shared_1.guard)('index_normalize', (p) => {
+    const dryRun = !!p?.dryRun;
+    const forceCanonical = !!p?.forceCanonical;
+    const instructionsCfg = (0, runtimeConfig_1.getRuntimeConfig)().instructions;
+    const base = (0, indexContext_1.getInstructionsDir)();
+    const dirs = [base, path_1.default.join(process.cwd(), 'devinstructions')].filter(d => fs_1.default.existsSync(d));
+    let scanned = 0, changed = 0, fixedHash = 0, fixedVersion = 0, fixedTier = 0, addedTimestamps = 0, addedContentType = 0;
+    const updatedIds = [];
+    const SEMVER = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+    for (const dir of dirs) {
+        let files = [];
+        try {
+            files = fs_1.default.readdirSync(dir).filter(f => f.endsWith('.json') && !f.startsWith('_'));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            scanned++;
+            const full = path_1.default.join(dir, f);
+            let raw;
+            try {
+                raw = fs_1.default.readFileSync(full, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            let data;
+            try {
+                data = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            if (!data || typeof data !== 'object')
+                continue;
+            let modified = false;
+            const rec = data;
+            const body = typeof rec.body === 'string' ? rec.body : '';
+            if (body) {
+                const useCanonical = forceCanonical || !instructionsCfg.canonicalDisable;
+                const actual = useCanonical ? (0, canonical_1.hashBody)(body) : crypto_1.default.createHash('sha256').update(body, 'utf8').digest('hex');
+                if (rec.sourceHash !== actual) {
+                    rec.sourceHash = actual;
+                    modified = true;
+                    fixedHash++;
+                }
+            }
+            if (!rec.contentType || typeof rec.contentType !== 'string' || rec.contentType.length === 0) {
+                rec.contentType = 'instruction';
+                modified = true;
+                addedContentType++;
+            }
+            if (!rec.version || typeof rec.version !== 'string' || !SEMVER.test(rec.version)) {
+                rec.version = '1.0.0';
+                modified = true;
+                fixedVersion++;
+            }
+            if (rec.priorityTier) {
+                const upper = String(rec.priorityTier).toUpperCase();
+                if (['P1', 'P2', 'P3', 'P4'].includes(upper) && upper !== rec.priorityTier) {
+                    rec.priorityTier = upper;
+                    modified = true;
+                    fixedTier++;
+                }
+            }
+            const nowIso = new Date().toISOString();
+            if (!rec.createdAt) {
+                rec.createdAt = nowIso;
+                modified = true;
+                addedTimestamps++;
+            }
+            if (!rec.updatedAt) {
+                rec.updatedAt = nowIso;
+                modified = true;
+                addedTimestamps++;
+            }
+            if (modified) {
+                if (!dryRun) {
+                    try {
+                        fs_1.default.writeFileSync(full, JSON.stringify(rec, null, 2) + '\n', 'utf8');
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                changed++;
+                updatedIds.push(path_1.default.basename(full, '.json'));
+            }
+        }
+    }
+    if (changed && !dryRun) {
+        try {
+            (0, indexContext_1.touchIndexVersion)();
+            (0, indexContext_1.invalidate)();
+            (0, indexContext_1.ensureLoaded)();
+        }
+        catch { /* ignore */ }
+        try {
+            (0, manifestManager_1.attemptManifestUpdate)();
+        }
+        catch { /* ignore */ }
+    }
+    return { scanned, changed, fixedHash, fixedVersion, fixedTier, addedTimestamps, addedContentType, dryRun, updated: updatedIds };
+}));
+// usage_flush (mutation)
+(0, registry_1.registerHandler)('usage_flush', (0, instructions_shared_1.guard)('usage_flush', () => ({ flushed: true })));

package/dist/services/handlers/instructions.import.d.ts

@@ -0,0 +1 @@
+export {};