ci(OMN-9845): adapt golden-chain-coverage.yml for v2 layout

.env.example

@@ -1,13 +1,58 @@
-# Part 4: AI Assistant Configuration
+# omnidash-v2 environment configuration template.
+# Copy to `.env` and fill in values for your environment.
+# Do NOT commit `.env` — it is ignored by .gitignore.
 
-# LLM backend host only — no /v1 suffix (the client appends /v1 itself)
-# Change to http://192.168.86.201:8001 to use DeepSeek-R1-14B fallback
-VITE_LLM_BASE_URL=http://192.168.86.201:8000
-VITE_LLM_MODEL=qwen3-coder-30b-awq
-VITE_LLM_API_KEY=not-needed
+# ---------------------------------------------------------------------------
+# Frontend (Vite — VITE_* vars are exposed to the browser)
+# ---------------------------------------------------------------------------
 
-# Set to "false" to disable the AI assistant entirely (hides the button + panel)
-VITE_AGENT_ENABLED=true
+# Data source mode. `file` reads from ./fixtures/ (default in dev, zero infra).
+# `http` reads via the Express bridge declared by VITE_HTTP_DATA_SOURCE_URL.
+# VITE_DATA_SOURCE=file
 
-# Part 1: API backend (omnidash v1 server)
-VITE_API_BASE=http://localhost:3000
+# HTTP data-source URL. Required when VITE_DATA_SOURCE=http.
+# VITE_HTTP_DATA_SOURCE_URL=http://localhost:3002
+
+# WebSocket invalidation channel. Required when running with the Express bridge.
+# Mirrors VITE_HTTP_DATA_SOURCE_URL but with the ws:// or wss:// scheme.
+# VITE_WS_URL=ws://localhost:3002/ws
+
+# Optional override for the Vite dev server port (default 3001).
+# VITE_DEV_PORT=3001
+
+# ---------------------------------------------------------------------------
+# Frontend — AI Assistant
+# ---------------------------------------------------------------------------
+
+# Master toggle. Set to "false" to hide the assistant button + panel entirely.
+# VITE_AGENT_ENABLED=true
+
+# LLM backend host (no /v1 suffix; the client appends it).
+# Required for production builds; in dev the Vite proxy stands in for it
+# only if this is set. Leave unset to disable the proxy in dev.
+# VITE_LLM_BASE_URL=http://your-llm-host:8000
+# VITE_LLM_MODEL=qwen3-coder-30b-awq
+# VITE_LLM_API_KEY=not-needed
+
+# Optional fallback LLM (only consulted when callers pass useFallback=true).
+# VITE_LLM_FALLBACK_URL=http://your-llm-fallback-host:8001
+# VITE_LLM_FALLBACK_MODEL=deepseek-r1-14b-awq
+# VITE_LLM_FALLBACK_API_KEY=not-needed
+
+# ---------------------------------------------------------------------------
+# Server (Express bridge — server/index.ts)
+# ---------------------------------------------------------------------------
+
+# Postgres connection string for the analytics DB. REQUIRED — server fails
+# fast at startup if this is unset.
+# OMNIDASH_ANALYTICS_DB_URL=postgresql://user:password@host:5432/omnidash_analytics
+
+# ---------------------------------------------------------------------------
+# Build-time scripts
+# ---------------------------------------------------------------------------
+
+# Path to a checkout of omnibase_core. REQUIRED for `npm run types:generate`.
+# OMNIBASE_CORE_PATH=/path/to/omnibase_core
+
+# Path to a checkout of omnibase_infra. REQUIRED for `npm run generate:fixtures`.
+# OMNIBASE_INFRA_PATH=/path/to/omnibase_infra

.github/workflows/ci.yml

@@ -27,10 +27,31 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: TypeScript typecheck
+      - name: Env-contamination gate
+        run: bash scripts/check-no-env-contamination.sh
+
+      - name: TypeScript typecheck (frontend)
         run: npx tsc --noEmit
 
-      - name: Run tests
-        run: npx vitest run
+      - name: TypeScript typecheck (server / vite config)
+        run: npm run build:server
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
         env:
           CI: true
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage/
+          if-no-files-found: ignore
+          retention-days: 14
+
+      - name: Build Storybook
+        run: npx storybook build -o storybook-static

.github/workflows/golden-chain-coverage.yml

@@ -0,0 +1,66 @@
+# .github/workflows/golden-chain-coverage.yml
+# Golden Chain Coverage Gate (OMN-9845)
+#
+# Adapted from omnidash v1 (OMN-7495).
+# v2 path changes:
+#   - v1 watched: server/consumers/read-model/** (Kafka read-model consumer dir)
+#   - v2 watches: src/data-source/** (snapshot projection sources) + shared/types/topics.ts
+#
+# Always produces a `golden-chain` check status (required by branch protection).
+# Skips the heavy test run when no projection-related files changed.
+name: Golden Chain Coverage Gate
+
+on:
+  pull_request:
+  merge_group:
+  push:
+    branches: [main]
+
+jobs:
+  golden-chain:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for projection-related changes
+        id: changes
+        run: |
+          if [ "${{ github.event_name }}" = "push" ] || [ "${{ github.event_name }}" = "merge_group" ]; then
+            echo "run_tests=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          BASE_SHA="${{ github.event.pull_request.base.sha }}"
+          HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+          CHANGED=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- \
+            'src/data-source/**' \
+            'shared/types/topics.ts' \
+            'server/__tests__/golden-chain/**' \
+          )
+          if [ -n "$CHANGED" ]; then
+            echo "run_tests=true" >> "$GITHUB_OUTPUT"
+            echo "Projection files changed — running golden chain tests"
+          else
+            echo "run_tests=false" >> "$GITHUB_OUTPUT"
+            echo "No projection files changed — skipping tests"
+          fi
+
+      - uses: actions/setup-node@v4
+        if: steps.changes.outputs.run_tests == 'true'
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - run: npm ci
+        if: steps.changes.outputs.run_tests == 'true'
+
+      - name: Run golden projection tests (unit mode)
+        if: steps.changes.outputs.run_tests == 'true'
+        run: npx vitest run server/__tests__/golden-chain/ --reporter=verbose
+        env:
+          GOLDEN_MODE: unit
+
+      - name: Verify projection coverage gate
+        if: steps.changes.outputs.run_tests == 'true'
+        run: npx vitest run server/__tests__/golden-chain/coverage-gate.test.ts --reporter=verbose

.gitignore

@@ -2,3 +2,31 @@ node_modules/
 dist/
 .vite/
 *.local
+fixtures/
+# Storybook fixture builders are part of the source tree (OMN-103).
+!src/storybook/fixtures/
+!src/storybook/fixtures/**
+build/
+dashboard-layouts/
+
+# Skill-result artifacts (local runs; not for repo)
+.onex_state/
+
+# Stray compiled JS from .ts sources (pre-existing, should not be in repo)
+src/**/*.js
+src/**/*.test.js
+shared/**/*.js
+shared/**/*.test.js
+
+# Prototype design files — captured locally, large, not committed.
+# reference/README.md is tracked as a breadcrumb to where the files came from.
+reference/claude-design/
+
+*storybook.log
+storybook-static
+
+# tsc --build / project references — intermediate cache files
+*.tsbuildinfo
+
+# vitest coverage output — generated by `npm run test:coverage`
+coverage/

.storybook/main.ts

@@ -0,0 +1,54 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(ts|tsx|mdx)'],
+  addons: [
+    // Trimmed addon list for cold-start performance. Re-add anything
+    // below when actually used.
+    //   '@chromatic-com/storybook'    — visual regression service. Not used.
+    //   '@storybook/addon-vitest'     — Storybook test runner integration. We
+    //                                   use vitest directly; the addon's
+    //                                   manager-side UniversalStore bootstrap
+    //                                   throws on every Storybook boot
+    //                                   without a "leader" test runner.
+    //   '@storybook/addon-onboarding' — welcome tour for new Storybook users.
+    //   '@storybook/addon-docs'       — MDX docs framework. We use plain TSX
+    //                                   stories; not authoring MDX.
+    '@storybook/addon-a11y',
+    '@storybook/addon-themes',
+  ],
+  framework: { name: '@storybook/react-vite', options: {} },
+  // Switched from `react-docgen-typescript` (uses full TS program — accurate
+  // but very slow on cold start, the single biggest contributor to startup
+  // time when stories include heavy widgets like CostTrend3D / CostByModelPie)
+  // to `react-docgen` (regex/AST-based, ~10× faster). Prop tables in the
+  // Controls panel will be slightly less detailed but still functional.
+  // To regain the richer prop typing later, reverse this flag.
+  typescript: { reactDocgen: 'react-docgen' },
+  // Dedupe react / react-dom so libraries that bring their own peer-dep
+  // resolution (echarts-for-react, @tanstack/react-query, three drei, etc.)
+  // share the host iframe's React instance. Without this, hook calls inside
+  // those libraries hit "resolveDispatcher() is null / cannot read property
+  // useMemo" because Vite's dependency optimizer materialized two React
+  // copies. Also pre-bundle the chart libraries + react-query explicitly so
+  // Vite resolves their React references against the deduped copy at
+  // optimize time, which dramatically improves cold-load performance.
+  viteFinal: async (config) => {
+    config.resolve = config.resolve ?? {};
+    config.resolve.dedupe = Array.from(
+      new Set([...(config.resolve.dedupe ?? []), 'react', 'react-dom']),
+    );
+    config.optimizeDeps = config.optimizeDeps ?? {};
+    config.optimizeDeps.include = Array.from(
+      new Set([
+        ...(config.optimizeDeps.include ?? []),
+        'echarts-for-react',
+        'echarts',
+        '@tanstack/react-query',
+        'three',
+      ]),
+    );
+    return config;
+  },
+};
+export default config;

.storybook/preview.tsx

@@ -0,0 +1,35 @@
+import type { Preview } from '@storybook/react-vite';
+import { withThemeByDataAttribute } from '@storybook/addon-themes';
+import '../src/styles/globals.css';
+
+// Per OMN-103 (plan amendment to OMN-100 Task 3): the dashboard
+// decorator `makeDashboardDecorator` from
+// `src/storybook/decorators/withDashboardContext.tsx` is applied
+// **explicitly per-story** rather than wired here in the global
+// `decorators` array. Storybook composes (does not replace) decorator
+// stacks, so a global default would double the QueryClient + ThemeProvider
+// context for every widget story that supplies its own. See ADR
+// `docs/adr/002-storybook-widget-coverage.md` for context.
+
+const preview: Preview = {
+  parameters: {
+    backgrounds: { disable: true },
+    controls: { matchers: { color: /(background|color)$/i } },
+    a11y: {
+      // 'todo' - show a11y violations in the test UI only
+      // 'error' - fail CI on a11y violations
+      // 'off' - skip a11y checks entirely
+      test: 'todo',
+    },
+  },
+  decorators: [
+    withThemeByDataAttribute({
+      themes: { Light: 'light', Dark: 'dark' },
+      defaultTheme: 'Light',
+      attributeName: 'data-theme',
+      parentSelector: 'html',
+    }),
+  ],
+};
+
+export default preview;

CLAUDE.md

@@ -0,0 +1,93 @@
+## Local dev mode (no infra)
+
+This repo runs in two modes:
+- `VITE_DATA_SOURCE=file` (default in dev) — reads snapshots from `./fixtures/`, persists layouts to `./dashboard-layouts/`. Zero infra required.
+- `VITE_DATA_SOURCE=http` — reads via `http://localhost:3002` Express bridge. Used only when we have a running Express server.
+
+### Hard rules
+
+1. **Do NOT hardcode** `localhost:3002` anywhere. All data access goes through `src/data-source/` — either `FileSnapshotSource` or `HttpSnapshotSource`, selected by `VITE_DATA_SOURCE`.
+2. **Do NOT hand-edit** `src/registry/component-registry.json`. Run `npm run generate:registry`.
+3. **Do NOT hand-edit** anything under `src/shared/types/generated/`. Run `npm run types:generate`.
+4. **Do NOT edit** any file under `node_modules/`. Components discovered there are read-only.
+5. **Fixtures and layouts are not committed.** They live under `./fixtures/` and `./dashboard-layouts/`, both gitignored.
+
+### Common tasks
+
+**Regenerate everything from scratch:**
+```bash
+npm run types:generate
+npm run generate:fixtures
+npm run generate:projection-registry
+npm run generate:registry
+npm run dev
+```
+
+**Add a new widget (two tracks — pick one):**
+
+_Track A — local MVP widget (the seven current widgets use this path):_
+1. Create `src/components/dashboard/<name>/<Name>.tsx`. Default-export a React component that accepts a `config` prop shaped per its manifest.
+2. Register the lazy import in `src/components/dashboard/index.ts` under its `implementationKey` (e.g. `'<name>/<Name>': lazy(() => import('./<name>/<Name>'))`).
+3. Add the manifest entry to the `MVP_COMPONENTS` object in `scripts/generate-registry.ts`. This is the canonical MVP manifest location — there is no per-widget `manifest.ts` file for local widgets.
+4. Run `npm run generate:registry` to rewrite `src/registry/component-registry.json`.
+5. Restart dev server.
+
+_Track B — external package widget (plugin extension path):_
+1. Publish an `@omninode/*` npm package containing your widget component plus a JSON manifest file listing one or more `ComponentManifest` entries.
+2. Reference the manifest path in the package's `package.json` via `"dashboardComponents": "./path/to/manifests.json"`.
+3. `npm install` the package into omnidash-v2.
+4. Run `npm run generate:registry` — the script auto-scans `node_modules/@omninode/*` and merges discovered manifests into the registry.
+5. Dynamic code loading for external packages is a future phase; for now they surface in the palette with `status: 'not_implemented'` unless their `implementationKey` also appears in the local `componentImports` map.
+
+**Add a new data source adapter:**
+1. Create `src/data-source/<name>-snapshot-source.ts` implementing `ProtocolSnapshotSource`.
+2. Register it in `src/data-source/index.ts` under its `VITE_DATA_SOURCE` key.
+3. Add a test in `src/data-source/<name>-snapshot-source.test.ts`.
+
+### Gotchas
+
+- Edit mode toggle is in the Zustand `editModeSlice`. Drag and resize are ONLY enabled when edit mode is active.
+- When you move a widget on the canvas, save the layout explicitly (`Save` button) — it does NOT auto-persist per drag.
+- If the palette is empty, your `src/registry/component-registry.json` is likely out of date. Run `npm run generate:registry`.
+- If widgets render but show "no data", check `./fixtures/<topic>/` has JSON files and `./fixtures/registry.json` lists the topic.
+
+### Where to look
+
+- Data fetching: `src/data-source/`
+- Grid behavior: `src/components/dashboard/DashboardGrid.tsx`
+- Palette: `src/components/dashboard/ComponentPalette.tsx`
+- Edit/view toggle: `src/store/editModeSlice.ts`, `src/pages/DashboardBuilder.tsx`
+- Layout persistence: `src/layout/layout-persistence.ts`
+- Widget lazy-import map: `src/components/dashboard/index.ts`
+- Widget MVP manifests: `scripts/generate-registry.ts` (`MVP_COMPONENTS`)
+- External package manifest discovery: `scripts/generate-registry.ts` → `scanInstalledPackages()`
+
+## Typography
+
+- All text in widgets must be rendered via `<Text>` or `<Heading>` from
+  `@/components/ui/typography`. Do not set `fontSize`, `fontFamily`,
+  `fontWeight`, text `color`, `textTransform`, or `letterSpacing` in
+  inline `style` props — enforced by the local ESLint rule
+  `local/no-typography-inline`.
+- Tokens live in `src/styles/globals.css :root`. See
+  `docs/adr/001-typography-system.md` for rationale.
+- Showcase: `npm run storybook` → Typography pages.
+
+## Storybook conventions
+
+- New stories live alongside their component as `<Name>.stories.tsx`
+  (e.g. `src/components/dashboard/quality/QualityScorePanel.stories.tsx`).
+- Any widget that calls `useProjectionQuery` must wrap its stories with
+  `makeDashboardDecorator(...)` from
+  `@/storybook/decorators/withDashboardContext` so the projection client
+  is seeded with deterministic fixture data.
+- Fixtures live under `src/storybook/fixtures/` and are exported via
+  `src/storybook/fixtures/index.ts`. Extend existing fixtures rather
+  than duplicating — every story should compose from the shared barrel.
+- Each widget must expose at minimum `Empty` and `Populated` story
+  exports. State-specific variants (`Loading`, `Error`,
+  `HighDisagreement`, `BalancedSplit`, etc.) are encouraged where
+  meaningful. The compliance scorecard
+  `src/storybook-coverage-compliance.test.ts` enforces this contract on
+  every `npm test`. See `docs/adr/002-storybook-widget-coverage.md` for
+  rationale.