@jagilber-org/index-server 1.19.1

package/dist/versioning/schemaVersion.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_VERSION = void 0;
+exports.migrateInstructionRecord = migrateInstructionRecord;
+// Central schema version constant for instruction JSON files.
+// Bump this when making a backward-incompatible on-disk schema change that
+// requires a migration rewrite. Migration logic should detect older versions
+// and transform + persist them once.
+exports.SCHEMA_VERSION = '4';
+// Helper function for review interval computation (matches ClassificationService logic)
+function computeReviewIntervalDays(tier, requirement) {
+    // Shorter intervals for higher criticality
+    if (tier === 'P1' || requirement === 'mandatory' || requirement === 'critical')
+        return 30;
+    if (tier === 'P2')
+        return 60;
+    if (tier === 'P3')
+        return 90;
+    return 120;
+}
+// Migration hook for schema version upgrades
+function migrateInstructionRecord(rec) {
+    const notes = [];
+    let changed = false;
+    const prevVersion = rec.schemaVersion || '1';
+    // v1 → v2 migration: Add reviewIntervalDays if missing
+    if (prevVersion === '1' && !rec.reviewIntervalDays) {
+        const tier = rec.priorityTier || 'P4';
+        const requirement = rec.requirement || 'optional';
+        rec.reviewIntervalDays = computeReviewIntervalDays(tier, requirement);
+        changed = true;
+        notes.push('added reviewIntervalDays from tier+requirement');
+    }
+    // v2 → v3 migration: Introduce primaryCategory (first category if present)
+    if (prevVersion === '2') {
+        const cats = Array.isArray(rec.categories) ? rec.categories.filter(c => typeof c === 'string' && c.trim()) : [];
+        if (!('primaryCategory' in rec) && cats.length) {
+            rec.primaryCategory = cats[0];
+            changed = true;
+            notes.push('added primaryCategory from first categories element');
+        }
+        if (('primaryCategory' in rec) && cats.length) {
+            const pc = rec.primaryCategory;
+            if (typeof pc === 'string' && pc && !cats.includes(pc)) {
+                // ensure consistency: inject primaryCategory into categories array
+                cats.unshift(pc);
+                rec.categories = Array.from(new Set(cats));
+                changed = true;
+                notes.push('normalized categories to include primaryCategory');
+            }
+        }
+    }
+    // v3 → v4 migration: Schema now accepts sourceWorkspace & createdByAgent at root level.
+    // No data transforms needed — fields are optional. Just version bump.
+    if (prevVersion === '3') {
+        // no-op: new optional fields (sourceWorkspace, createdByAgent) already valid if present
+        notes.push('v3→v4: added sourceWorkspace & createdByAgent to schema (optional)');
+    }
+    // Clean optional nullable fields that upstream tools may emit as null
+    // (riskScore must be number or absent — null causes AJV rejection)
+    if ('riskScore' in rec && rec.riskScore === null) {
+        delete rec.riskScore;
+        changed = true;
+        notes.push('removed null riskScore (optional field)');
+    }
+    // Ensure contentType field (backward compatibility default)
+    if (!('contentType' in rec) || !rec.contentType) {
+        rec.contentType = 'instruction';
+        changed = true;
+        notes.push('added contentType with default value "instruction"');
+    }
+    // Ensure all required fields are present (defensive migration)
+    const requiredDefaults = {
+        categories: [],
+        priority: 50,
+        audience: 'all',
+        requirement: 'optional'
+    };
+    for (const [key, defaultValue] of Object.entries(requiredDefaults)) {
+        if (!(key in rec) || rec[key] === undefined || rec[key] === null) {
+            rec[key] = defaultValue;
+            changed = true;
+            notes.push(`added required field ${key} with default value`);
+        }
+    }
+    // Update schema version if changed
+    if (rec.schemaVersion !== exports.SCHEMA_VERSION) {
+        rec.schemaVersion = exports.SCHEMA_VERSION;
+        changed = true;
+        notes.push(`schemaVersion updated ${prevVersion}→${exports.SCHEMA_VERSION}`);
+    }
+    return { changed, notes: notes.length ? notes : undefined };
+}

package/package.json

@@ -0,0 +1,134 @@
+{
+  "name": "@jagilber-org/index-server",
+  "version": "1.19.1",
+  "description": "MCP instruction indexing server for AI assistant governance — search, CRUD, schema validation, usage tracking, and cross-repo knowledge promotion.",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist/",
+    "!dist/tests/",
+    "schemas/",
+    "templates/",
+    "scripts/copy-dashboard-assets.mjs",
+    "scripts/setup-hooks.cjs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "main": "dist/server/index-server.js",
+  "bin": {
+    "index-server": "dist/server/index-server.js"
+  },
+  "scripts": {
+    "instructions:normalize": "node scripts/normalize-instructions.js",
+    "build": "tsc -p tsconfig.json && node scripts/copy-dashboard-assets.mjs",
+    "start": "node dist/server/index-server.js",
+    "start-minimal": "node dist/minimal/index.js",
+    "prestart": "npm run build",
+    "pretest": "node scripts/pretest-build-or-skip.mjs",
+    "dev": "node --watch dist/server/index-server.js",
+    "build:watch": "tsc -w -p tsconfig.json",
+    "check:dist": "npm run build && git diff --quiet --exit-code dist || (echo 'Dist out of date. Run npm run build and commit generated files.' && exit 1)",
+    "coverage": "vitest run --coverage",
+    "sbom": "npx syft packages dir:. -o json > sbom.json || echo 'Syft not installed'",
+    "coverage:core": "cross-env FAST_COVERAGE=1 vitest run --coverage --reporter=dot --reporter=json",
+    "coverage:ci": "cross-env COVERAGE_HARD_MIN=50 COVERAGE_TARGET=60 npm run coverage:core && node scripts/coverage-alias.js && node scripts/check-coverage.mjs",
+    "manifest:generate": "node scripts/generate-manifest.mjs",
+    "contract:tools": "node scripts/generate-tools-snapshot.mjs",
+    "verify:manifest": "node scripts/verify-manifest.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:contracts": "vitest run src/tests/contractSchemas.spec.ts",
+    "test:diag": "cross-env INDEX_SERVER_HEALTH_MIXED_DIAG=1 vitest run src/tests/handshakeFlakeRepro.spec.ts src/tests/healthMixedReproLoop.spec.ts src/tests/healthHangExploration.spec.ts",
+    "test:stress": "cross-env INDEX_SERVER_STRESS_DIAG=1 vitest run",
+    "test:stress:focus": "cross-env INDEX_SERVER_STRESS_DIAG=1 vitest run src/tests/handshakeFlakeRepro.spec.ts src/tests/healthMixedReproLoop.spec.ts src/tests/healthHangExploration.spec.ts src/tests/healthMultiProcessStress.spec.ts src/tests/dispatcherStress.spec.ts src/tests/dispatcherFlakeStress.spec.ts src/tests/concurrencyFuzz.spec.ts",
+    "test:property": "vitest run src/tests/concurrencyFuzz.spec.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint . --ext .ts",
+    "lint:instructions": "node scripts/lint-instructions.mjs",
+    "format": "prettier --write .",
+    "prepare": "node scripts/setup-hooks.cjs",
+    "prepublishOnly": "npm run build && npm run typecheck",
+    "scan:security": "node scripts/security-scan.mjs",
+    "release:patch": "node scripts/bump-version.mjs patch",
+    "release:minor": "node scripts/bump-version.mjs minor",
+    "release:major": "node scripts/bump-version.mjs major",
+    "perf": "ts-node src/perf/benchmark.ts",
+    "perf:baseline": "npm run build && node scripts/perf-baseline.mjs",
+    "perf:drift": "npm run perf:baseline && node scripts/perf-compare.mjs",
+    "perf:trend": "node scripts/perf-trend.mjs",
+    "perf:summary": "node scripts/perf-summary-md.mjs",
+    "perf:ci": "npm run perf:drift && npm run perf:trend && npm run perf:summary",
+    "guard:env": "ts-node scripts/enforce-config-usage.ts",
+    "build:verify": "npm run typecheck && npm run build && npm run test:fast && npm run guard:env && npm run guard:decl",
+    "test:unit": "vitest run --config vitest.config.unit.ts",
+    "test:unit:watch": "vitest --config vitest.config.unit.ts",
+    "test:fast": "node scripts/test-fast.mjs",
+    "test:slow": "node scripts/test-slow.mjs",
+    "docs:tools": "node scripts/generate-tools-doc.cjs",
+    "health:check": "node scripts/health-check.mjs",
+    "guard:skips": "node scripts/check-no-skips.mjs",
+    "guard:baseline": "node scripts/guard-baseline.mjs",
+    "baseline:sentinel:update": "node scripts/baseline-sentinel.mjs update",
+    "baseline:sentinel:verify": "node scripts/baseline-sentinel.mjs verify",
+    "guard:decl": "node scripts/guard-declarations.mjs",
+    "guard:decl:fix": "node scripts/purge-extra-decls.mjs && node scripts/guard-declarations.mjs",
+    "pw:init": "npx playwright install --with-deps chromium firefox webkit",
+    "pw:test": "playwright test",
+    "playwright:start-server": "cross-env INDEX_SERVER_DASHBOARD=1 node dist/server/index-server.js",
+    "pw:baseline": "node scripts/run-playwright.mjs --grep @baseline --update",
+    "pw:drift": "node scripts/run-playwright.mjs --grep @baseline",
+    "pw:drift:report": "npm run pw:drift && node scripts/generate-drift-report.mjs",
+    "pw:drift:ci": "cross-env DRIFT_BROWSERS=chromium,firefox npm run pw:drift:report",
+    "dash:seed": "node scripts/seed-dashboard-fixtures.mjs"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/adm-zip": "^0.5.8",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.19.37",
+    "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "cross-env": "^7.0.3",
+    "eslint": "^8.57.0",
+    "fast-check": "^3.17.0",
+    "prettier": "^3.8.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@mermaid-js/layout-elk": "^0.2.1",
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "adm-zip": "^0.5.17",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^2.1.1",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.3.2",
+    "ws": "^8.19.0",
+    "zod": "^3.23.8"
+  },
+  "optionalScripts": {},
+  "promptReviewCriteriaVersion": "1.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagilber-org/index-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jagilber-org/index-server/issues"
+  },
+  "homepage": "https://github.com/jagilber-org/index-server#readme"
+}

package/schemas/README.md

@@ -0,0 +1,13 @@
+# Schemas
+
+Authoritative JSON Schemas for persisted and exchanged objects.
+
+| Schema | Description |
+|--------|-------------|
+| `instruction.schema.json` | Canonical instruction entry persisted on disk. |
+| `feedback-entry.schema.json` | Feedback subsystem persistent record. |
+| `usage-event.schema.json` | Single instruction usage event (pre-aggregation). |
+| `usage-batch.schema.json` | Batch of usage events flushed together. |
+| `usage-buckets.schema.json` | Rotating temporal usage counters container. |
+
+All schemas draft-07. Internal references use relative `$ref` where applicable.

package/schemas/feedback-entry.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://example.local/schemas/feedback-entry.schema.json",
+  "title": "FeedbackEntry",
+  "type": "object",
+  "description": "Persistent feedback record stored by feedback tools.",
+  "required": ["id","type","severity","status","description","createdAt"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-f0-9]{12,64}$" },
+    "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+    "type": { "type": "string", "enum": ["issue","status","security","feature-request","bug-report","performance","usability","other"] },
+    "severity": { "type": "string", "enum": ["low","medium","high","critical"] },
+    "status": { "type": "string", "enum": ["new","acknowledged","in-progress","resolved","closed"] },
+    "description": { "type": "string", "minLength": 1, "maxLength": 10000 },
+    "context": { "type": "object", "additionalProperties": true },
+    "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-_]{0,30}$" }, "uniqueItems": true, "maxItems": 10 },
+    "metadata": { "type": "object", "additionalProperties": true },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" },
+    "createdBy": { "type": "string" },
+    "updatedBy": { "type": "string" },
+    "resolution": { "type": "string", "maxLength": 4000 },
+    "resolutionAt": { "type": "string", "format": "date-time" },
+    "_internal": { "type": "object", "additionalProperties": true, "description": "Internal system fields (rotation, lineage)." }
+  }
+}

package/schemas/graph-export-v2.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/schemas/graph-export-v2.schema.json",
+  "title": "Graph Export Response (Schema v2)",
+  "type": "object",
+  "required": ["meta","nodes","edges"],
+  "additionalProperties": false,
+  "properties": {
+    "meta": {
+      "type": "object",
+      "required": ["graphSchemaVersion","nodeCount","edgeCount"],
+      "properties": {
+        "graphSchemaVersion": {"const": 2},
+        "nodeCount": {"type": "number"},
+        "edgeCount": {"type": "number"},
+        "truncated": {"type": "boolean"},
+        "notes": {"type": "array", "items": {"type": "string"}}
+      },
+      "additionalProperties": false
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id"],
+        "properties": {
+          "id": {"type": "string"},
+          "nodeType": {"type": "string", "enum": ["instruction","category"]},
+          "categories": {"type": "array", "items": {"type": "string"}},
+          "primaryCategory": {"type": "string"},
+          "priority": {"type": "number"},
+          "priorityTier": {"type": "string"},
+          "requirement": {"type": "string"},
+          "owner": {"type": "string"},
+          "status": {"type": "string"},
+          "createdAt": {"type": "string"},
+          "updatedAt": {"type": "string"},
+          "usageCount": {"type": "number"}
+        },
+        "additionalProperties": false
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from","to","type"],
+        "properties": {
+          "from": {"type": "string"},
+            "to": {"type": "string"},
+            "type": {"type": "string", "enum": ["primary","category","belongs"]},
+            "weight": {"type": "number"}
+        },
+        "additionalProperties": false
+      }
+    },
+    "dot": {"type": "string"},
+    "mermaid": {"type": "string"}
+  }
+}