@jagilber-org/index-server 1.27.0 → 1.28.0

package/dist/versioning/schemaVersion.d.ts

@@ -1,4 +1,4 @@
-export declare const SCHEMA_VERSION = "4";
+export declare const SCHEMA_VERSION = "5";
 export interface MigrationResult {
     changed: boolean;
     notes?: string[];

package/dist/versioning/schemaVersion.js

@@ -6,7 +6,7 @@ exports.migrateInstructionRecord = migrateInstructionRecord;
 // 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';
+exports.SCHEMA_VERSION = '5';
 // Helper function for review interval computation (matches ClassificationService logic)
 function computeReviewIntervalDays(tier, requirement) {
     // Shorter intervals for higher criticality
@@ -57,6 +57,14 @@ function migrateInstructionRecord(rec) {
         // no-op: optional metadata fields are already valid if present
         notes.push('v3→v4: added optional metadata fields to schema');
     }
+    // v4 → v5 migration: public persisted contentType "chat-session" was renamed
+    // to "workflow". Preserve the workflow/runbook semantics instead of falling
+    // through the generic invalid-enum fallback to "instruction".
+    if (prevVersion === '4' && rec.contentType === 'chat-session') {
+        rec.contentType = 'workflow';
+        changed = true;
+        notes.push('v4→v5: migrated legacy contentType "chat-session" to "workflow"');
+    }
     // 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) {
@@ -75,7 +83,7 @@ function migrateInstructionRecord(rec) {
         categories: [],
         priority: 50,
         audience: 'all',
-        requirement: 'optional'
+        requirement: 'recommended'
     };
     for (const [key, defaultValue] of Object.entries(requiredDefaults)) {
         if (!(key in rec) || rec[key] === undefined || rec[key] === null) {
@@ -84,6 +92,43 @@ function migrateInstructionRecord(rec) {
             notes.push(`added required field ${key} with default value`);
         }
     }
+    // Validate and coerce enum fields to prevent invalid values from persisting.
+    // Legacy alias maps mirror indexLoader.ts coercion — try known aliases first,
+    // only fall back to defaults for truly unknown values. Keep in sync with indexLoader.ts.
+    const legacyStatusMap = { active: 'approved' };
+    const legacyAudienceMap = {
+        system: 'all', developers: 'group', developer: 'individual',
+        team: 'group', teams: 'group', users: 'group', dev: 'individual',
+        devs: 'group', testers: 'group', administrators: 'group',
+        admins: 'group', agents: 'group', 'powershell script authors': 'group',
+    };
+    const legacyRequirementMap = {
+        MUST: 'mandatory', SHOULD: 'recommended', MAY: 'optional',
+        CRITICAL: 'critical', OPTIONAL: 'optional', MANDATORY: 'mandatory',
+        DEPRECATED: 'deprecated', REQUIRED: 'mandatory',
+    };
+    const legacyContentTypeMap = {
+        'chat-session': 'workflow',
+    };
+    const enumDefaults = {
+        audience: { valid: ['individual', 'group', 'all'], fallback: 'all', legacy: legacyAudienceMap },
+        requirement: { valid: ['mandatory', 'critical', 'recommended', 'optional', 'deprecated'], fallback: 'optional', legacy: legacyRequirementMap },
+        contentType: { valid: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent'], fallback: 'instruction', legacy: legacyContentTypeMap },
+        status: { valid: ['draft', 'review', 'approved', 'deprecated'], fallback: 'draft', legacy: legacyStatusMap },
+        priorityTier: { valid: ['P1', 'P2', 'P3', 'P4'], fallback: 'P3' },
+        classification: { valid: ['public', 'internal', 'restricted'], fallback: 'internal' },
+    };
+    for (const [field, { valid, fallback, legacy }] of Object.entries(enumDefaults)) {
+        if (typeof rec[field] === 'string' && !valid.includes(rec[field])) {
+            const val = rec[field];
+            // Try legacy alias maps (exact match then case-insensitive) before falling back to default
+            const resolved = legacy?.[val] ?? legacy?.[val.toLowerCase()] ?? legacy?.[val.toUpperCase()];
+            const target = resolved ?? (field === 'requirement' && /\s/.test(val) && val.length < 300 ? 'recommended' : fallback);
+            notes.push(`corrected invalid ${field} "${val}" → "${target}"`);
+            rec[field] = target;
+            changed = true;
+        }
+    }
     // Update schema version if changed
     if (rec.schemaVersion !== exports.SCHEMA_VERSION) {
         rec.schemaVersion = exports.SCHEMA_VERSION;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jagilber-org/index-server",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "mcpName": "io.github.jagilber-org/index-server",
-  "description": "MCP instruction indexing server for AI assistant governance — search, CRUD, schema validation, usage tracking, and cross-repo knowledge promotion.",
+  "description": "MCP instruction indexing server with search, CRUD, validation, and cross-repo knowledge promotion.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -16,10 +16,10 @@
     "!dist/tests/",
     "schemas/",
     "templates/",
-    "scripts/copy-dashboard-assets.mjs",
-    "scripts/setup-hooks.cjs",
-    "scripts/generate-certs.mjs",
-    "scripts/setup-wizard.mjs",
+    "scripts/build/copy-dashboard-assets.mjs",
+    "scripts/hooks/setup-hooks.cjs",
+    "scripts/build/generate-certs.mjs",
+    "scripts/build/setup-wizard.mjs",
     "server.json",
     "README.md",
     "LICENSE",
@@ -33,24 +33,24 @@
     "index-server": "dist/server/index-server.js"
   },
   "scripts": {
-    "setup": "node scripts/setup-wizard.mjs",
-    "instructions:normalize": "node scripts/normalize-instructions.js",
-    "build": "tsc -p tsconfig.json && node scripts/copy-dashboard-assets.mjs",
+    "setup": "node scripts/build/setup-wizard.mjs",
+    "instructions:normalize": "node scripts/migration/normalize-instructions.js",
+    "build": "tsc -p tsconfig.json && node scripts/build/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",
+    "pretest": "node scripts/testing/pretest-build-or-skip.mjs",
     "dev": "cross-env NODE_ENV=development 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",
-    "check:version-parity": "node scripts/check-version-parity.mjs",
+    "coverage:ci": "cross-env COVERAGE_HARD_MIN=50 COVERAGE_TARGET=60 npm run coverage:core && node scripts/governance/coverage-alias.cjs && node scripts/governance/check-coverage.mjs",
+    "manifest:generate": "node scripts/build/generate-manifest.mjs",
+    "contract:tools": "node scripts/build/generate-tools-snapshot.mjs",
+    "verify:manifest": "node scripts/governance/verify-manifest.mjs",
+    "check:version-parity": "node scripts/governance/check-version-parity.mjs",
     "test": "npm run test:fast",
     "test:all": "vitest run",
     "test:watch": "vitest",
@@ -61,43 +61,48 @@
     "test:property": "vitest run src/tests/concurrencyFuzz.spec.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint .",
-    "lint:instructions": "node scripts/lint-instructions.mjs",
+    "lint:instructions": "node scripts/governance/lint-instructions.mjs",
+    "lint:logs": "node scripts/diagnostics/crawl-logs.mjs --dir logs --file test-results/test-output.log --allowlist .crawl-logs-allowlist --strict",
     "format": "prettier --write .",
-    "prepare": "node scripts/setup-hooks.cjs",
+    "prepare": "node scripts/hooks/setup-hooks.cjs",
     "audit": "npm audit --omit=dev --audit-level=high",
     "prepublishOnly": "npm run build && npm run typecheck && npm run audit",
-    "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",
+    "scan:security": "node scripts/governance/security-scan.mjs",
+    "publish:dry-run": "pwsh -NoProfile -File scripts/Invoke-ReleaseWorkflow.ps1 -DryRun",
+    "publish:prepare": "pwsh -NoProfile -File scripts/Invoke-ReleaseWorkflow.ps1",
+    "publish:create-pr": "pwsh -NoProfile -File scripts/Invoke-ReleaseWorkflow.ps1 -CreatePR",
+    "release:patch": "node scripts/build/bump-version.mjs patch",
+    "release:minor": "node scripts/build/bump-version.mjs minor",
+    "release:major": "node scripts/build/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:baseline": "npm run build && node scripts/perf/perf-baseline.mjs",
+    "perf:drift": "npm run perf:baseline && node scripts/perf/perf-compare.mjs",
+    "perf:trend": "node scripts/perf/perf-trend.mjs",
+    "perf:summary": "node scripts/perf/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",
+    "guard:env": "ts-node scripts/governance/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",
+    "test:fast": "node scripts/testing/test-fast.mjs",
+    "test:slow": "node scripts/testing/test-slow.mjs",
+    "docs:tools": "node scripts/build/generate-tools-doc.mjs",
+    "health:check": "node scripts/diagnostics/health-check.mjs",
+    "guard:skips": "node scripts/governance/check-no-skips.mjs",
+    "guard:baseline": "node scripts/governance/guard-baseline.mjs",
+    "baseline:sentinel:update": "node scripts/governance/baseline-sentinel.mjs update",
+    "baseline:sentinel:verify": "node scripts/governance/baseline-sentinel.mjs verify",
+    "guard:decl": "node scripts/governance/guard-declarations.mjs",
+    "guard:decl:fix": "node scripts/governance/purge-extra-decls.mjs && node scripts/governance/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:baseline": "node scripts/testing/run-playwright.mjs --grep @baseline --update",
+    "pw:drift": "node scripts/testing/run-playwright.mjs --grep @baseline",
+    "pw:drift:report": "npm run pw:drift && node scripts/build/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"
+    "pw:adversarial": "node scripts/testing/run-adversarial-tests.mjs",
+    "dash:seed": "node scripts/testing/seed-dashboard-fixtures.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
@@ -134,6 +139,15 @@
     "ws": "^8.19.0",
     "zod": "^3.23.8"
   },
+  "overrides": {
+    "mermaid": {
+      "uuid": "^14.0.0"
+    },
+    "@mermaid-js/layout-elk": {
+      "uuid": "^14.0.0"
+    },
+    "@types/express-serve-static-core": "5.0.7"
+  },
   "optionalScripts": {},
   "promptReviewCriteriaVersion": "1.0.0",
   "license": "MIT",

package/schemas/index-server.code-schema.json

@@ -23436,7 +23436,7 @@
         {
           "name": "ContentType",
           "isExported": true,
-          "type": "'instruction' | 'template' | 'chat-session' | 'reference' | 'example' | 'agent'",
+          "type": "'instruction' | 'template' | 'workflow' | 'reference' | 'example' | 'agent'",
           "line": 3
         }
       ],

package/schemas/instruction.schema.json

@@ -134,18 +134,18 @@
       "enum": [
         "instruction",
         "template",
-        "chat-session",
+        "workflow",
         "reference",
         "example",
         "agent"
       ],
       "default": "instruction",
-      "description": "Content type classification: instruction (actionable guidance), template (scaffolds/error templates), chat-session (conversation history), reference (docs/guides), example (code samples), agent (AI agent definitions/personas)"
+      "description": "Content type classification: instruction (actionable guidance), template (scaffolds/error templates), workflow (multi-step processes or runbooks), reference (docs/guides), example (code samples), agent (AI agent definitions/personas). The legacy value chat-session is accepted only by migration/write compatibility and is normalized to workflow before persistence; new records should use workflow."
     },
     "schemaVersion": {
       "type": "string",
       "enum": [
-        "4"
+        "5"
       ],
       "description": "Internal schema version for migration"
     },

package/schemas/json-schema/instruction-content-type.schema.json

@@ -7,7 +7,7 @@
       "enum": [
         "instruction",
         "template",
-        "chat-session",
+        "workflow",
         "reference",
         "example",
         "agent"

package/schemas/json-schema/instruction-instruction-entry.schema.json

@@ -200,7 +200,7 @@
       "enum": [
         "instruction",
         "template",
-        "chat-session",
+        "workflow",
         "reference",
         "example",
         "agent"

package/scripts/README.md

@@ -0,0 +1,48 @@
+# Scripts Directory
+
+Organized by purpose. Each subdirectory has a clear role; naming conventions make intent obvious at a glance.
+
+## Directory Structure
+
+| Directory | Purpose | Naming Convention |
+|-----------|---------|-------------------|
+| `build/` | Build, release, asset generation | `generate-*`, `copy-*`, `bump-*`, `build-*` |
+| `ci/` | CI-specific runners and validation | — |
+| `client/` | Client CLI tools and wizards | — |
+| `deploy/` | Deployment and production ops | `deploy-*`, `smoke-*`, `prod-*` |
+| `diagnostics/` | Adhoc probes, health checks, inspection | `adhoc-*` for one-off probes |
+| `dist/` | Distributable scripts (shipped to users) | — |
+| `governance/` | Guards, validators, lint, coverage | `guard-*`, `check-*`, `validate-*` |
+| `hooks/` | Git hook implementations | `pre-commit*`, `pre-push*`, `commit-msg*` |
+| `mappings/` | Configuration mappings | — |
+| `migration/` | One-time data migrations (keep for history) | — |
+| `perf/` | Performance baselines, trends, benchmarks | `perf-*`, `benchmark-*`, `stress-*` |
+| `testing/` | Test runners, helpers, fixtures | `test-*`, `run-*`, `seed-*` |
+
+## Naming Conventions
+
+- **`adhoc-*`** — One-off diagnostic probes. Never referenced by CI or `package.json`. Safe to run manually during debugging; safe to delete when no longer needed.
+- **`guard-*` / `check-*` / `validate-*`** — Governance gates. Referenced by package.json `guard:*` scripts or CI.
+- **`generate-*`** — Code/doc/schema generators that produce artifacts.
+- **`run-*`** — Wrappers that invoke test suites or tools with specific config.
+
+## Adding New Scripts
+
+1. **Pick the right directory** based on the table above.
+2. **Use the naming convention** for that directory.
+3. **Prefer `.mjs`** (ESM) over `.js`/`.cjs` for new scripts.
+4. **If it's a one-off probe**, prefix with `adhoc-` and put in `diagnostics/`.
+5. **If it needs to be referenced** from `package.json` or `.pre-commit-config.yaml`, note that in a comment at the top of the script.
+
+## Migration Status
+
+This reorg is in progress. Scripts are being moved category-by-category:
+- [x] `diagnostics/` — adhoc probes, health checks
+- [x] `hooks/` — git hook scripts
+- [x] `client/` — client CLI tools
+- [x] `build/` — build and release tools
+- [x] `governance/` — guard and validation scripts
+- [x] `perf/` — performance tools
+- [x] `testing/` — test runners
+- [x] `deploy/` — deployment scripts
+- [x] `migration/` — one-time migrations

package/scripts/{generate-certs.mjs → build/generate-certs.mjs}

@@ -14,7 +14,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const ROOT = path.resolve(__dirname, '..');
+const ROOT = path.resolve(__dirname, '..', '..');
 
 function parseArgs() {
   const args = process.argv.slice(2);

package/scripts/{setup-wizard.mjs → build/setup-wizard.mjs}

@@ -25,7 +25,7 @@ import { fileURLToPath } from 'url';
 import { select, input, confirm, checkbox } from '@inquirer/prompts';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const ROOT = path.resolve(__dirname, '..');
+const ROOT = path.resolve(__dirname, '..', '..');
 const IS_WINDOWS = process.platform === 'win32';
 
 // --------------------------------------------------------------------------

package/scripts/{setup-hooks.cjs → hooks/setup-hooks.cjs}

@@ -8,19 +8,19 @@ function main(){
 
   // Pre-commit hook — uses cross-platform Node.js script
   const hookPath = join(hooksDir, 'pre-commit');
-  const content = `#!/usr/bin/env bash\n# Auto-generated pre-commit hook (cross-platform Node.js)\nnode ./scripts/pre-commit.mjs`;
+  const content = `#!/usr/bin/env bash\n# Auto-generated pre-commit hook (cross-platform Node.js)\nnode ./scripts/hooks/pre-commit.mjs`;
   writeFileSync(hookPath, content, { encoding:'utf8' });
   chmodSync(hookPath, 0o755);
 
   // Commit-msg hook — uses cross-platform Node.js script
   const commitMsgPath = join(hooksDir, 'commit-msg');
-  const commitMsgContent = `#!/usr/bin/env bash\n# Auto-generated commit-msg hook (cross-platform Node.js)\nnode ./scripts/commit-msg-baseline.mjs "$1"`;
+  const commitMsgContent = `#!/usr/bin/env bash\n# Auto-generated commit-msg hook (cross-platform Node.js)\nnode ./scripts/hooks/commit-msg-baseline.mjs "$1"`;
   writeFileSync(commitMsgPath, commitMsgContent, { encoding:'utf8' });
   chmodSync(commitMsgPath, 0o755);
 
   // Pre-push hook enforces public-mirror protection.
   const prePushPath = join(hooksDir, 'pre-push');
-  const prePushContent = `#!/usr/bin/env bash\n# Auto-generated pre-push hook (cross-platform Node.js)\nnode ./scripts/pre-push.mjs "$@"`;
+  const prePushContent = `#!/usr/bin/env bash\n# Auto-generated pre-push hook (cross-platform Node.js)\nnode ./scripts/hooks/pre-push.mjs "$@"`;
   writeFileSync(prePushPath, prePushContent, { encoding:'utf8' });
   chmodSync(prePushPath, 0o755);
 }

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.jagilber-org/index-server",
-  "description": "MCP instruction indexing server for AI assistant governance — search, CRUD, schema validation, usage tracking, and cross-repo knowledge promotion.",
+  "description": "MCP instruction indexing server with search, CRUD, validation, and cross-repo knowledge promotion.",
   "repository": {
     "url": "https://github.com/jagilber-org/index-server",
     "source": "github"
   },
-  "version": "1.27.0",
+  "version": "1.28.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@jagilber-org/index-server",
-      "version": "1.27.0",
+      "version": "1.28.0",
       "transport": {
         "type": "stdio"
       }