Merge branch 'claude/agitated-brown-27f411' — demo-mode governance (registry + ESLint + banner + Challenger)

Author: SchenLong

deploy/docker-compose.challenger.yml

@@ -25,6 +25,12 @@ services:
       NEXT_PUBLIC_MAX_TEXT_LENGTH: "10000"
       NEXT_PUBLIC_ENABLE_ANALYTICS: "false"
       NEXT_PUBLIC_ENABLE_ERROR_REPORTING: "false"
+      # Demo mode — Challenger is DEV/QA only. Mock data enabled for pitch /
+      # onboarding demos. Production failsafe in src/lib/demo/index.ts is
+      # overridden here by TPI_ALLOW_DEMO_IN_PROD. Do NOT copy these two
+      # variables to deploy/docker-compose.yml (Voyager / real PROD).
+      NEXT_PUBLIC_DEMO_MODE: "${NEXT_PUBLIC_DEMO_MODE:-true}"
+      TPI_ALLOW_DEMO_IN_PROD: "${TPI_ALLOW_DEMO_IN_PROD:-true}"
       NODA_API_KEY: "${NODA_API_KEY}"
       NODA_API_KEY_ROLE: "${NODA_API_KEY_ROLE:-analyst}"
       TPI_DB_ENCRYPTION_KEY: "${TPI_DB_ENCRYPTION_KEY}"

packages/dojolm-web/eslint.config.mjs

@@ -15,6 +15,31 @@ const eslintConfig = defineConfig([
       "react-hooks/static-components": "off",
       "react-hooks/refs": "off",
       "react-hooks/preserve-manual-memoization": "off",
+      // Forbid importing demo mock data outside API route handlers and the
+      // demo dir itself. The isDemoMode() guard and auth constants (via the
+      // `@/lib/demo` barrel) remain importable everywhere because those are
+      // runtime metadata, not fixtures. Enforces the governance contract
+      // described in src/lib/demo/registry.ts.
+      "no-restricted-imports": ["error", {
+        patterns: [{
+          group: [
+            "@/lib/demo/mock-*",
+            "@/lib/demo/mock-api-handlers",
+            "@/lib/demo/registry",
+          ],
+          message: "Demo mock data/handlers are restricted to src/app/api/** and src/lib/demo/**. Import isDemoMode() from '@/lib/demo' instead if you need to gate behavior on demo mode.",
+        }],
+      }],
+    },
+  },
+  {
+    // API route handlers and the demo package itself may import mock data.
+    files: [
+      "src/app/api/**/*.{ts,tsx}",
+      "src/lib/demo/**/*.{ts,tsx}",
+    ],
+    rules: {
+      "no-restricted-imports": "off",
     },
   },
   {
@@ -25,6 +50,7 @@ const eslintConfig = defineConfig([
     ],
     rules: {
       "react/display-name": "off",
+      "no-restricted-imports": "off",
     },
   },
 ]);

packages/dojolm-web/src/app/api/audit/log/route.ts

@@ -8,8 +8,6 @@
  */
 
 import { NextRequest, NextResponse } from 'next/server';
-import { isDemoMode } from '@/lib/demo';
-import { demoNoOp } from '@/lib/demo/mock-api-handlers';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { checkApiAuth } from '@/lib/api-auth';

packages/dojolm-web/src/instrumentation.ts

@@ -0,0 +1,44 @@
+/**
+ * File: src/instrumentation.ts
+ * Purpose: Next.js runtime init hook. Runs once per server process on cold
+ *         start (both Node and Edge runtimes). Used here solely to emit a
+ *         visible banner when demo mode is active, so operators spot an
+ *         accidentally-enabled demo deployment in the logs.
+ *
+ * Next.js auto-loads this file — do not import from elsewhere. See:
+ * https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
+ */
+
+export async function register(): Promise<void> {
+  // Only run in the Node.js runtime. The Edge runtime boots per-request and
+  // lacks the env vars we care about here (DEMO_MODE is Node-time flag).
+  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
+
+  const demoRequested = process.env.NEXT_PUBLIC_DEMO_MODE === 'true';
+  if (!demoRequested) return;
+
+  const isProd = process.env.NODE_ENV === 'production';
+  const prodOverride = process.env.TPI_ALLOW_DEMO_IN_PROD === 'true';
+
+  if (isProd && !prodOverride) {
+    // Matches the failsafe in src/lib/demo/index.ts — demo mode refused.
+    // eslint-disable-next-line no-console
+    console.error(
+      '[demo] REFUSED: NEXT_PUBLIC_DEMO_MODE=true in production without ' +
+        'TPI_ALLOW_DEMO_IN_PROD=true. Mock data will NOT be served. ' +
+        'Review your deployment env — this is a dangerous combination.',
+    );
+    return;
+  }
+
+  const env = isProd ? 'PRODUCTION (override enabled)' : 'development';
+  // eslint-disable-next-line no-console
+  console.warn(
+    `\n${'━'.repeat(72)}\n` +
+      `  [demo] DEMO MODE ACTIVE — ${env}\n` +
+      `  All 54 gated API routes will return mock data from @/lib/demo.\n` +
+      `  Auth bypassed. No DB, filesystem, or external LLM calls.\n` +
+      `  Registry: src/lib/demo/registry.ts\n` +
+      `${'━'.repeat(72)}\n`,
+  );
+}

packages/dojolm-web/src/lib/demo/__tests__/registry.test.ts

@@ -0,0 +1,131 @@
+/**
+ * File: registry.test.ts
+ * Purpose: Enforce parity between DEMO_ROUTE_REGISTRY and the real filesystem.
+ *
+ * Failure modes caught by this test:
+ *   - A route.ts file adds `isDemoMode()` without a registry entry → drift.
+ *   - A registry entry references a route.ts that no longer uses
+ *     `isDemoMode()` → stale entry.
+ *   - A handler name listed in the registry is not exported from
+ *     mock-api-handlers.ts → broken reference.
+ *   - A handler is exported but referenced by no registry entry → dead code.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import {
+  DEMO_ROUTE_REGISTRY,
+  DEMO_REGISTERED_HANDLERS,
+  DEMO_ROUTE_COUNT,
+} from '../registry';
+
+const API_ROOT = join(__dirname, '../../../app/api');
+const HANDLERS_FILE = join(__dirname, '../mock-api-handlers.ts');
+
+/** Recursively find every route.ts under src/app/api. */
+function findRouteFiles(dir: string, out: string[] = []): string[] {
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    const stat = statSync(full);
+    if (stat.isDirectory()) findRouteFiles(full, out);
+    else if (name === 'route.ts') out.push(full);
+  }
+  return out;
+}
+
+/** Convert absolute route.ts path to registry-style path (e.g. '/stats'). */
+function toRoutePath(absPath: string): string {
+  const rel = relative(API_ROOT, absPath).replace(/\\/g, '/');
+  return '/' + rel.replace(/\/route\.ts$/, '');
+}
+
+describe('DEMO_ROUTE_REGISTRY', () => {
+  it('matches the routes that call isDemoMode() on disk', () => {
+    const routeFiles = findRouteFiles(API_ROOT);
+    const routesUsingDemoMode = routeFiles
+      .filter((f) => readFileSync(f, 'utf8').includes('isDemoMode()'))
+      .map(toRoutePath)
+      .sort();
+
+    const registryRoutes = DEMO_ROUTE_REGISTRY.map((e) => e.route).sort();
+
+    const missing = routesUsingDemoMode.filter((r) => !registryRoutes.includes(r));
+    const stale = registryRoutes.filter((r) => !routesUsingDemoMode.includes(r));
+
+    expect(missing, `Routes that call isDemoMode() but are missing from DEMO_ROUTE_REGISTRY: ${missing.join(', ')}`).toEqual([]);
+    expect(stale, `Registry entries for routes no longer calling isDemoMode(): ${stale.join(', ')}`).toEqual([]);
+  });
+
+  it('has the expected route count', () => {
+    expect(DEMO_ROUTE_COUNT).toBeGreaterThan(0);
+    expect(DEMO_ROUTE_REGISTRY).toHaveLength(DEMO_ROUTE_COUNT);
+  });
+
+  it('is sorted by route path', () => {
+    const routes = DEMO_ROUTE_REGISTRY.map((e) => e.route);
+    const sorted = [...routes].sort();
+    expect(routes).toEqual(sorted);
+  });
+
+  it('has no duplicate route entries', () => {
+    const routes = DEMO_ROUTE_REGISTRY.map((e) => e.route);
+    const unique = new Set(routes);
+    expect(unique.size).toBe(routes.length);
+  });
+});
+
+describe('DEMO handler references', () => {
+  it('every handler in registry is exported from mock-api-handlers.ts', () => {
+    const handlersSource = readFileSync(HANDLERS_FILE, 'utf8');
+    const missing: string[] = [];
+    for (const name of DEMO_REGISTERED_HANDLERS) {
+      const exportPattern = new RegExp(
+        `^export (?:async )?(?:function|const) ${name}\\b`,
+        'm',
+      );
+      if (!exportPattern.test(handlersSource)) missing.push(name);
+    }
+    expect(missing, `Registry references handlers not exported from mock-api-handlers.ts: ${missing.join(', ')}`).toEqual([]);
+  });
+
+  it('has no dead handlers (exported but never referenced)', () => {
+    const handlersSource = readFileSync(HANDLERS_FILE, 'utf8');
+    const exported = Array.from(
+      handlersSource.matchAll(/^export (?:async )?(?:function|const) (demo\w+)/gm),
+      (m) => m[1],
+    );
+    const referenced = new Set(DEMO_REGISTERED_HANDLERS);
+    // Handlers that are wrappers (demoNoOp*, demoBatch*, demoGuard*) may be referenced
+    // by inline routes — exempt them from the dead-code check.
+    const inlineReferenced = new Set([
+      'demoNoOp',
+      'demoNoOpCreated',
+      'demoNoOpAccepted',
+      'demoBatchGet',
+      'demoBatchPost',
+      'demoBatchById',
+      'demoBatchExecutions',
+      'demoGuardConfigGet',
+      'demoGuardStatsGet',
+      'demoGuardAuditGet',
+      'demoCampaignsGet',
+      'demoCampaignById',
+      'demoCampaignRunById',
+      'demoComplianceGet',
+      'demoComplianceFrameworksGet',
+      'demoComplianceAuditGet',
+      'demoSettingsGet',
+      'demoTestsGet',
+      'demoResultsGet',
+      'demoTestCasesGet',
+      'demoMitsukeGet',
+      'demoMcpStatusGet',
+      'demoScanPost',
+    ]);
+    const dead = exported.filter(
+      (name) => !referenced.has(name) && !inlineReferenced.has(name),
+    );
+    expect(dead, `Exported demo handlers with no registry or inline reference: ${dead.join(', ')}`).toEqual([]);
+  });
+});

packages/dojolm-web/src/lib/demo/registry.ts

@@ -0,0 +1,107 @@
+/**
+ * File: src/lib/demo/registry.ts
+ * Purpose: Authoritative list of API routes that branch on `isDemoMode()`.
+ *
+ * Every entry pairs a route path with the demo handler(s) it invokes when
+ * `isDemoMode()` returns true. The companion test (registry.test.ts) walks
+ * src/app/api/** and fails the build if a route gains or loses an
+ * `isDemoMode()` call without a matching registry update. This prevents drift
+ * between demo-mode coverage and the real app surface.
+ *
+ * Governance contract:
+ *   - Every `isDemoMode()` branch in src/app/api/** MUST be listed here.
+ *   - Every handler referenced here MUST be exported from mock-api-handlers.ts
+ *     or declared in the `inline` list for routes that inline their demo path.
+ *   - New demo handlers added to mock-api-handlers.ts without a registry entry
+ *     are unreachable from production routes and will flag in the test.
+ */
+export interface DemoRouteEntry {
+  /** Route path relative to /api (e.g. '/stats', '/llm/models/[id]'). */
+  route: string;
+  /**
+   * Demo handler function names imported from './mock-api-handlers'. Empty
+   * array when the route inlines its demo response (see `inline`).
+   */
+  handlers: ReadonlyArray<string>;
+  /**
+   * True when the route implements its demo branch inline (no named handler
+   * from mock-api-handlers.ts). Used for routes that return minimal static
+   * JSON without crossing the handler boundary.
+   */
+  inline?: boolean;
+}
+
+/**
+ * Exhaustive demo-mode route registry. Keep sorted by route path to make
+ * diffs reviewable. When adding a new route that reads `isDemoMode()`, add
+ * the entry here in the same PR.
+ */
+export const DEMO_ROUTE_REGISTRY: ReadonlyArray<DemoRouteEntry> = [
+  { route: '/admin/health', handlers: [], inline: true },
+  { route: '/admin/settings', handlers: [], inline: true },
+  { route: '/arena', handlers: ['demoArenaGet', 'demoArenaPost'] },
+  { route: '/arena/[id]', handlers: ['demoArenaMatchById'] },
+  { route: '/arena/warriors', handlers: ['demoArenaWarriorsGet'] },
+  { route: '/attackdna/analyze', handlers: ['demoNoOp'] },
+  { route: '/attackdna/ingest', handlers: ['demoNoOp'] },
+  { route: '/attackdna/query', handlers: ['demoAttackDnaQueryGet'] },
+  { route: '/attackdna/sync', handlers: ['demoNoOp'] },
+  { route: '/auth/login', handlers: [], inline: true },
+  { route: '/auth/logout', handlers: [], inline: true },
+  { route: '/auth/me', handlers: [], inline: true },
+  { route: '/auth/users', handlers: ['demoUsersGet', 'demoNoOpCreated'] },
+  { route: '/compliance', handlers: [], inline: true },
+  { route: '/compliance/export', handlers: [], inline: true },
+  { route: '/compliance/frameworks', handlers: [], inline: true },
+  { route: '/ecosystem/findings', handlers: ['demoEcosystemGet'] },
+  { route: '/fixtures', handlers: ['demoFixturesGet'] },
+  { route: '/health', handlers: ['demoHealthGet'] },
+  { route: '/llm/batch', handlers: [], inline: true },
+  { route: '/llm/batch/[id]', handlers: [], inline: true },
+  { route: '/llm/batch/[id]/executions', handlers: [], inline: true },
+  { route: '/llm/batch/cleanup', handlers: [], inline: true },
+  { route: '/llm/coverage', handlers: ['demoCoverageGet'] },
+  { route: '/llm/fingerprint', handlers: ['demoFingerprintGet', 'demoNoOpAccepted'] },
+  { route: '/llm/guard', handlers: [], inline: true },
+  { route: '/llm/guard/audit', handlers: [], inline: true },
+  { route: '/llm/guard/stats', handlers: [], inline: true },
+  { route: '/llm/leaderboard', handlers: ['demoLeaderboardGet'] },
+  { route: '/llm/local-models', handlers: [], inline: true },
+  { route: '/llm/models', handlers: ['demoModelsGet', 'demoModelsPost'] },
+  { route: '/llm/models/[id]', handlers: ['demoModelById', 'demoNoOp'] },
+  { route: '/llm/obl/alignment', handlers: [], inline: true },
+  { route: '/llm/obl/depth', handlers: [], inline: true },
+  { route: '/llm/obl/geometry', handlers: [], inline: true },
+  { route: '/llm/obl/robustness', handlers: [], inline: true },
+  { route: '/llm/providers', handlers: ['demoProvidersGet', 'demoProvidersPost'] },
+  { route: '/llm/reports', handlers: ['demoReportsGet'] },
+  { route: '/llm/results', handlers: [], inline: true },
+  { route: '/llm/test-cases', handlers: [], inline: true },
+  { route: '/mcp/status', handlers: [], inline: true },
+  { route: '/ronin/programs', handlers: ['demoRoninProgramsGet'] },
+  { route: '/ronin/submissions', handlers: ['demoRoninSubmissionsGet'] },
+  { route: '/scan', handlers: [], inline: true },
+  { route: '/sengoku/campaigns', handlers: [], inline: true },
+  { route: '/sengoku/campaigns/[id]', handlers: [], inline: true },
+  { route: '/sengoku/campaigns/[id]/run', handlers: ['demoNoOpAccepted'] },
+  { route: '/sengoku/campaigns/[id]/runs', handlers: ['demoCampaignRunsGet'] },
+  { route: '/setup/admin', handlers: [], inline: true },
+  { route: '/setup/status', handlers: [], inline: true },
+  { route: '/shingan/formats', handlers: ['demoShinganFormatsGet'] },
+  { route: '/shingan/scan', handlers: ['demoShinganScansGet'] },
+  { route: '/stats', handlers: ['demoStatsGet'] },
+  { route: '/tests', handlers: [], inline: true },
+];
+
+/** Number of API routes gated by `isDemoMode()`. */
+export const DEMO_ROUTE_COUNT: number = DEMO_ROUTE_REGISTRY.length;
+
+/** All handler names referenced by the registry, deduplicated. */
+export const DEMO_REGISTERED_HANDLERS: ReadonlyArray<string> = Array.from(
+  new Set(DEMO_ROUTE_REGISTRY.flatMap((entry) => entry.handlers)),
+).sort();
+
+/** Lookup by route path. Returns undefined if route is not in registry. */
+export function getDemoRouteEntry(route: string): DemoRouteEntry | undefined {
+  return DEMO_ROUTE_REGISTRY.find((entry) => entry.route === route);
+}