@jagilber-org/index-server 1.19.1

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

@@ -0,0 +1,173 @@
+"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 features_1 = require("../features");
+const schemaVersion_1 = require("../../versioning/schemaVersion");
+const classificationService_1 = require("../classificationService");
+const ownershipService_1 = require("../ownershipService");
+const atomicFs_1 = require("../atomicFs");
+const auditLog_1 = require("../auditLog");
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+const manifestManager_1 = require("../manifestManager");
+const instructions_shared_1 = require("./instructions.shared");
+/** Validate that a resolved path falls within allowed base directories (cwd or configured data dir). */
+function isPathAllowed(resolved) {
+    const cwd = process.cwd();
+    const config = (0, runtimeConfig_1.getRuntimeConfig)();
+    const dataDir = config.index.baseDir || cwd;
+    const normalizedResolved = path_1.default.resolve(resolved);
+    const allowedRoots = [path_1.default.resolve(cwd), path_1.default.resolve(dataDir)];
+    return allowedRoots.some(root => normalizedResolved.startsWith(root + path_1.default.sep) || normalizedResolved === root);
+}
+(0, registry_1.registerHandler)('index_import', (0, instructions_shared_1.guard)('index_import', (p) => {
+    let entries;
+    const mode = p.mode || 'skip';
+    if (Array.isArray(p.entries)) {
+        entries = p.entries;
+    }
+    else if (typeof p.entries === 'string') {
+        const filePath = path_1.default.resolve(p.entries);
+        if (!isPathAllowed(filePath))
+            return { error: 'entries path is outside allowed directories', path: filePath };
+        if (!fs_1.default.existsSync(filePath))
+            return { error: 'entries file not found', path: filePath };
+        try {
+            const raw = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
+            if (!Array.isArray(raw))
+                return { error: 'entries file must contain a JSON array', path: filePath };
+            entries = raw;
+        }
+        catch (e) {
+            return { error: 'entries file parse error', path: filePath, detail: e.message };
+        }
+    }
+    else if (typeof p.source === 'string') {
+        const dirPath = path_1.default.resolve(p.source);
+        if (!isPathAllowed(dirPath))
+            return { error: 'source path is outside allowed directories', path: dirPath };
+        if (!fs_1.default.existsSync(dirPath))
+            return { error: 'source directory not found', path: dirPath };
+        let stat;
+        try {
+            stat = fs_1.default.statSync(dirPath);
+        }
+        catch (e) {
+            return { error: 'source path inaccessible', path: dirPath, detail: e.message };
+        }
+        if (!stat.isDirectory())
+            return { error: 'source path is not a directory', path: dirPath };
+        const files = fs_1.default.readdirSync(dirPath).filter(f => f.endsWith('.json') && !f.startsWith('_'));
+        entries = [];
+        for (const fname of files) {
+            const fpath = path_1.default.join(dirPath, fname);
+            try {
+                const parsed = JSON.parse(fs_1.default.readFileSync(fpath, 'utf8'));
+                if (parsed && typeof parsed === 'object' && parsed.id)
+                    entries.push(parsed);
+            }
+            catch { /* skip unparseable files */ }
+        }
+    }
+    else {
+        entries = [];
+    }
+    if (!entries.length)
+        return { error: 'no entries' };
+    const dir = (0, indexContext_1.getInstructionsDir)();
+    if (!fs_1.default.existsSync(dir))
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    const instructionsCfg = (0, runtimeConfig_1.getRuntimeConfig)().instructions;
+    let imported = 0, skipped = 0, overwritten = 0;
+    const errors = [];
+    const classifier = new classificationService_1.ClassificationService();
+    for (const e of entries) {
+        if (!e || !e.id || !e.title || !e.body) {
+            const id = e?.id || 'unknown';
+            errors.push({ id, error: 'missing required fields' });
+            continue;
+        }
+        const bodyTrimmed = typeof e.body === 'string' ? e.body.trim() : String(e.body);
+        const { bodyMaxLength: importBodyMax } = (0, runtimeConfig_1.getRuntimeConfig)().index;
+        if (bodyTrimmed.length > importBodyMax) {
+            errors.push({ id: e.id, error: `body_too_large: ${bodyTrimmed.length} chars exceeds ${importBodyMax} limit. Split into cross-linked instructions.` });
+            continue;
+        }
+        const file = path_1.default.join(dir, `${e.id}.json`);
+        const fileExists = fs_1.default.existsSync(file);
+        const now = new Date().toISOString();
+        let categories = Array.from(new Set((Array.isArray(e.categories) ? e.categories : []).filter((c) => typeof c === 'string' && c.trim().length > 0).map(c => c.toLowerCase()))).sort();
+        const primaryCategoryRaw = e.primaryCategory;
+        if (!categories.length) {
+            if (instructionsCfg.requireCategory) {
+                errors.push({ id: e.id, error: 'category_required' });
+                continue;
+            }
+            categories = ['uncategorized'];
+            (0, features_1.incrementCounter)('instructions:autoCategory');
+        }
+        const effectivePrimary = (primaryCategoryRaw && categories.includes(primaryCategoryRaw.toLowerCase())) ? primaryCategoryRaw.toLowerCase() : categories[0];
+        const newBodyHash = crypto_1.default.createHash('sha256').update(bodyTrimmed, 'utf8').digest('hex');
+        let existing = null;
+        if (fileExists) {
+            try {
+                existing = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+            }
+            catch {
+                existing = null;
+            }
+        }
+        if (e.priorityTier === 'P1' && (!categories.length || !e.owner)) {
+            errors.push({ id: e.id, error: 'P1 requires category & owner' });
+            continue;
+        }
+        if ((e.requirement === 'mandatory' || e.requirement === 'critical') && !e.owner) {
+            errors.push({ id: e.id, error: 'mandatory/critical require owner' });
+            continue;
+        }
+        if (fileExists && mode === 'skip') {
+            skipped++;
+            continue;
+        }
+        if (fileExists && mode === 'overwrite')
+            overwritten++;
+        else if (!fileExists)
+            imported++;
+        const base = existing ? { ...existing, title: e.title, body: bodyTrimmed, rationale: e.rationale, priority: e.priority, audience: e.audience, requirement: e.requirement, categories, primaryCategory: effectivePrimary, updatedAt: now } : { id: e.id, title: e.title, body: bodyTrimmed, rationale: e.rationale, priority: e.priority, audience: e.audience, requirement: e.requirement, categories, primaryCategory: effectivePrimary, sourceHash: newBodyHash, schemaVersion: schemaVersion_1.SCHEMA_VERSION, deprecatedBy: e.deprecatedBy, createdAt: now, updatedAt: now, riskScore: e.riskScore, createdByAgent: instructionsCfg.agentId, sourceWorkspace: instructionsCfg.workspaceId };
+        const govKeys = ['version', 'owner', 'status', 'priorityTier', 'classification', 'lastReviewedAt', 'nextReviewDue', 'changeLog', 'semanticSummary', 'contentType'];
+        for (const k of govKeys) {
+            const v = e[k];
+            if (v !== undefined) {
+                base[k] = v;
+            }
+        }
+        base.sourceHash = newBodyHash;
+        const record = classifier.normalize(base);
+        if (record.owner === 'unowned') {
+            const auto = (0, ownershipService_1.resolveOwner)(record.id);
+            if (auto) {
+                record.owner = auto;
+                record.updatedAt = new Date().toISOString();
+            }
+        }
+        try {
+            (0, atomicFs_1.atomicWriteJson)(file, record);
+        }
+        catch {
+            errors.push({ id: e.id, error: 'write-failed' });
+        }
+    }
+    (0, indexContext_1.touchIndexVersion)();
+    (0, indexContext_1.invalidate)();
+    const st = (0, indexContext_1.ensureLoaded)();
+    const summary = { hash: st.hash, imported, skipped, overwritten, total: entries.length, errors };
+    (0, auditLog_1.logAudit)('import', entries.map(e => e.id), { imported, skipped, overwritten, errors: errors.length });
+    (0, manifestManager_1.attemptManifestUpdate)();
+    return summary;
+}));

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

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

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

@@ -0,0 +1,167 @@
+"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 registry_1 = require("../../server/registry");
+const indexContext_1 = require("../indexContext");
+const auditLog_1 = require("../auditLog");
+const manifestManager_1 = require("../manifestManager");
+const features_1 = require("../features");
+const instructions_shared_1 = require("./instructions.shared");
+(0, registry_1.registerHandler)('index_governanceHash', () => {
+    let st = (0, indexContext_1.ensureLoaded)();
+    const now = Date.now();
+    const loadedAgo = now - new Date(st.loadedAt).getTime();
+    if (loadedAgo > 50) {
+        try {
+            const first = st.list[0];
+            if (first) {
+                const file = path_1.default.join((0, indexContext_1.getInstructionsDir)(), `${first.id}.json`);
+                if (fs_1.default.existsSync(file)) {
+                    const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+                    if (raw && typeof raw.owner === 'string' && raw.owner !== first.owner) {
+                        (0, indexContext_1.invalidate)();
+                        st = (0, indexContext_1.ensureLoaded)();
+                    }
+                }
+            }
+        }
+        catch { /* ignore verification errors */ }
+    }
+    let projections = st.list.slice().sort((a, b) => a.id.localeCompare(b.id)).map(indexContext_1.projectGovernance);
+    try {
+        const dir = (0, indexContext_1.getInstructionsDir)();
+        const files = fs_1.default.readdirSync(dir).filter(f => f.endsWith('.json'));
+        if (files.length && (projections.length === 0 || projections.length < Math.floor(files.length * 0.9))) {
+            const missingIds = new Set(files.map(f => f.replace(/\.json$/, '')));
+            for (const p of projections) {
+                missingIds.delete(p.id);
+            }
+            let hydrated = false;
+            let loadCount = 0;
+            for (const mid of missingIds) {
+                if (loadCount >= 5)
+                    break;
+                loadCount++;
+                const file = path_1.default.join(dir, mid + '.json');
+                try {
+                    const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+                    if (raw && raw.id === mid) {
+                        st.list.push(raw);
+                        st.byId.set(raw.id, raw);
+                        hydrated = true;
+                    }
+                }
+                catch { /* ignore individual load errors */ }
+            }
+            if (hydrated) {
+                projections = st.list.slice().sort((a, b) => a.id.localeCompare(b.id)).map(indexContext_1.projectGovernance);
+                try {
+                    (0, features_1.incrementCounter)('governance:lateMaterialize');
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    catch { /* ignore defensive reload errors */ }
+    const governanceHash = (0, indexContext_1.computeGovernanceHash)(st.list);
+    if (projections.length && projections.length < Math.floor(st.list.length * 0.9) || projections.some(p => !p.owner)) {
+        try {
+            (0, indexContext_1.invalidate)();
+            const st2 = (0, indexContext_1.ensureLoaded)();
+            projections = st2.list.slice().sort((a, b) => a.id.localeCompare(b.id)).map(indexContext_1.projectGovernance);
+            try {
+                (0, features_1.incrementCounter)('governance:projectionRepair');
+            }
+            catch { /* ignore */ }
+        }
+        catch { /* ignore reload failure */ }
+    }
+    return { count: projections.length, governanceHash, items: projections };
+});
+(0, registry_1.registerHandler)('index_governanceUpdate', (0, instructions_shared_1.guard)('index_governanceUpdate', (p) => {
+    const id = p.id;
+    const st = (0, indexContext_1.ensureLoaded)();
+    const existing = st.byId.get(id);
+    if (!existing)
+        return { id, notFound: true };
+    const file = path_1.default.join((0, indexContext_1.getInstructionsDir)(), `${id}.json`);
+    if (!fs_1.default.existsSync(file))
+        return { id, notFound: true };
+    let record;
+    try {
+        record = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return { id, error: 'read-failed' };
+    }
+    let changed = false;
+    const now = new Date().toISOString();
+    const bump = p.bump || 'none';
+    if (p.owner && p.owner !== record.owner) {
+        record.owner = p.owner;
+        changed = true;
+    }
+    if (p.status) {
+        const allowed = ['draft', 'review', 'approved', 'deprecated'];
+        const desired = p.status === 'active' ? 'approved' : p.status;
+        if (!allowed.includes(desired)) {
+            return { id, error: 'invalid status', provided: p.status };
+        }
+        if (desired !== record.status) {
+            record.status = desired;
+            changed = true;
+        }
+    }
+    if (p.lastReviewedAt) {
+        record.lastReviewedAt = p.lastReviewedAt;
+        changed = true;
+    }
+    if (p.nextReviewDue) {
+        record.nextReviewDue = p.nextReviewDue;
+        changed = true;
+    }
+    if (bump && bump !== 'none') {
+        const parts = (record.version || '1.0.0').split('.').map(n => parseInt(n || '0', 10));
+        while (parts.length < 3)
+            parts.push(0);
+        if (bump === 'major')
+            parts[0]++;
+        else if (bump === 'minor')
+            parts[1]++;
+        else if (bump === 'patch')
+            parts[2]++;
+        if (bump === 'major') {
+            parts[1] = 0;
+            parts[2] = 0;
+        }
+        if (bump === 'minor') {
+            parts[2] = 0;
+        }
+        const newVersion = parts.join('.');
+        if (newVersion !== record.version) {
+            record.version = newVersion;
+            record.changeLog = [...(record.changeLog || []), { version: newVersion, changedAt: now, summary: `manual ${bump} bump via governanceUpdate` }];
+            changed = true;
+        }
+    }
+    if (!changed)
+        return { id, changed: false };
+    record.updatedAt = now;
+    try {
+        fs_1.default.writeFileSync(file, JSON.stringify(record, null, 2));
+    }
+    catch {
+        return { id, error: 'write-failed' };
+    }
+    (0, indexContext_1.touchIndexVersion)();
+    (0, indexContext_1.invalidate)();
+    (0, indexContext_1.ensureLoaded)();
+    const resp = { id, changed: true, version: record.version, owner: record.owner, status: record.status, lastReviewedAt: record.lastReviewedAt, nextReviewDue: record.nextReviewDue };
+    (0, auditLog_1.logAudit)('governanceUpdate', id, { changed: true, version: record.version });
+    (0, manifestManager_1.attemptManifestUpdate)();
+    return resp;
+}));

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

@@ -0,0 +1,163 @@
+import { InstructionEntry } from '../../models/instruction';
+export declare const instructionActions: {
+    list: (p: {
+        category?: string;
+        expectId?: string;
+        contentType?: string;
+        limit?: number;
+        offset?: number;
+    }) => {
+        hash: string;
+        count: number;
+        items: InstructionEntry[];
+    };
+    listScoped: (p: {
+        userId?: string;
+        workspaceId?: string;
+        teamIds?: string[];
+    }) => {
+        hash: string;
+        count: number;
+        scope: string;
+        items: InstructionEntry[];
+    };
+    get: (p: {
+        id: string;
+    }) => {
+        hash: string;
+        item: InstructionEntry;
+        notFound?: undefined;
+        id?: undefined;
+        readonly hint?: undefined;
+        example?: undefined;
+    } | {
+        notFound: boolean;
+        id: string;
+        hint: string;
+        example: {
+            action: string;
+            id: string;
+        };
+        hash?: undefined;
+        item?: undefined;
+    };
+    getEnhanced: (p: {
+        id: string;
+    }) => {
+        readonly hash: string;
+        readonly item: InstructionEntry;
+        notFound?: undefined;
+    } | {
+        readonly notFound: true;
+        hash?: undefined;
+        item?: undefined;
+    } | {
+        notFound: boolean;
+        hash?: undefined;
+        item?: undefined;
+    };
+    search: (p: {
+        q?: string;
+        keywords?: string[];
+        mode?: "keyword" | "regex" | "semantic";
+        limit?: number;
+        includeCategories?: boolean;
+        caseSensitive?: boolean;
+        contentType?: string;
+    }) => Promise<{
+        hash: string;
+        count: number;
+        totalMatches: number;
+        items: InstructionEntry[];
+        results: import("../handlers.search").SearchResult[];
+        query: {
+            keywords: string[];
+            mode: "regex" | "keyword" | "semantic";
+            limit: number;
+            includeCategories: boolean;
+            caseSensitive: boolean;
+            contentType?: string;
+        };
+        autoTokenized: boolean | undefined;
+        hints: string[] | undefined;
+    }>;
+    diff: (p: {
+        clientHash?: string;
+        known?: {
+            id: string;
+            sourceHash: string;
+        }[];
+    }) => {
+        upToDate: boolean;
+        hash: string;
+        added?: undefined;
+        updated?: undefined;
+        removed?: undefined;
+        changed?: undefined;
+    } | {
+        hash: string;
+        added: InstructionEntry[];
+        updated: InstructionEntry[];
+        removed: string[];
+        upToDate?: undefined;
+        changed?: undefined;
+    } | {
+        hash: string;
+        changed: InstructionEntry[];
+        upToDate?: undefined;
+        added?: undefined;
+        updated?: undefined;
+        removed?: undefined;
+    };
+    export: (p: {
+        ids?: string[];
+        metaOnly?: boolean;
+    }) => {
+        hash: string;
+        count: number;
+        items: InstructionEntry[];
+    };
+    query: (p: {
+        categoriesAll?: string[];
+        categoriesAny?: string[];
+        excludeCategories?: string[];
+        contentType?: string;
+        priorityMin?: number;
+        priorityMax?: number;
+        priorityTiers?: ("P1" | "P2" | "P3" | "P4")[];
+        requirements?: InstructionEntry["requirement"][];
+        text?: string;
+        limit?: number;
+        offset?: number;
+    }) => {
+        hash: string;
+        total: number;
+        count: number;
+        offset: number;
+        limit: number;
+        items: InstructionEntry[];
+        applied: {
+            catsAll: string[];
+            catsAny: string[];
+            catsEx: string[];
+            prMin: number | undefined;
+            prMax: number | undefined;
+            tiers: ("P1" | "P2" | "P3" | "P4")[];
+            requirements: import("../../models/instruction").RequirementLevel[];
+            text: string | undefined;
+        };
+    };
+    categories: (_p: unknown) => {
+        count: number;
+        categories: {
+            name: string;
+            count: number;
+        }[];
+    };
+    dir: () => {
+        dir: string;
+        filesCount: number;
+        files: string[];
+    };
+};
+export {};