feat(m0): bootstrap repo, design system, compose stack

- Repo scaffolding: .gitignore, .env.example, Makefile, docker-compose.yml,
  README.md, CHANGELOG.md, pre-commit config.
- Three-service stack: api (Flask 3), db (postgres:16-alpine), front (nginx
  serving the Vite bundle). Named volumes metamorph_db + metamorph_evidence.
- Backend skeleton: Flask app factory, JSON structured logging on stdout,
  GET /api/v1/health, multi-stage Dockerfile, pyproject.toml driven by uv,
  Pydantic Settings with secret guard rails (refuses to boot in non-dev with
  placeholders), APP_ENV gating.
- Frontend skeleton: Vite + React 18 + TypeScript strict + TailwindCSS, RTOps
  design tokens from tasks/design.md, self-hosted JetBrains Mono / IBM Plex
  Sans via @fontsource, base UI primitives (Card/Tag/SectionHeader/FlowNode/
  Button), home page wired to /api/v1/health.
- Engine-agnostic Makefile: auto-detects docker or podman, picks the matching
  compose driver. Targets: up/down/build/rebuild/dev/lint/fmt/test/migrate/
  seed-mitre/print-install-token/e2e/inspect-health.
- Playwright suite: e2e/tests/m0-smoke.spec.ts (8 tests) + HTML + JUnit
  reports + traces on retry.
- Docs: tasks/spec.md (finalized after Q&A), tasks/design.md, tasks/todo.md
  (14 milestones), tasks/testing-m0.md, tasks/lessons.md.

DoD: make up + make health + make e2e all pass on podman 5.x (Fedora) and
docker. TLS terminated by external reverse proxy (spec §6 NF-network).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

e2e/.eslintrc.cjs

@@ -0,0 +1,12 @@
+/* eslint-env node */
+module.exports = {
+  root: true,
+  env: { node: true, es2022: true },
+  extends: ['eslint:recommended', 'plugin:@typescript-eslint/recommended'],
+  parser: '@typescript-eslint/parser',
+  parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+  ignorePatterns: ['playwright-report', 'test-results', 'node_modules', '.eslintrc.cjs'],
+  rules: {
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+  },
+};

e2e/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+playwright-report
+test-results
+playwright/.cache
+*.log

e2e/README.md

@@ -0,0 +1,66 @@
+# Metamorph e2e
+
+End-to-end tests powered by [Playwright](https://playwright.dev/). Each milestone in `tasks/todo.md` should add at least one spec file (`tests/m<N>-*.spec.ts`).
+
+## One-time setup
+
+```bash
+cd e2e
+npm install
+npm run install-browsers      # downloads chromium (uses sudo for system deps)
+```
+
+## Running against a live stack
+
+```bash
+# 1. Bring the stack up from the repo root:
+cd .. && make up
+
+# 2. Run the tests:
+cd e2e && npm test
+
+# 3. Open the HTML report:
+npm run report                 # opens playwright-report/index.html in your browser
+```
+
+Or from the repo root:
+
+```bash
+make e2e        # runs against the already-up stack
+make e2e-report # opens the HTML report
+make e2e-up     # one-shot: make up + wait healthy + run tests
+```
+
+## Auto-spawn mode
+
+Set `PW_AUTOSTART=1` to let Playwright spawn `make up` itself before the run:
+
+```bash
+PW_AUTOSTART=1 npm test
+```
+
+## Configuration
+
+| Env var      | Default                  | Purpose                                       |
+|--------------|--------------------------|-----------------------------------------------|
+| `BASE_URL`   | `http://localhost:8080`  | The front nginx URL (which proxies `/api/*`)  |
+| `PW_AUTOSTART` | `0`                    | If `1`, spawn `make up` before the tests      |
+| `CI`         | unset                    | When set, retries=2 and parallel workers=2    |
+
+## Reports
+
+- **HTML**  : `e2e/playwright-report/index.html`
+- **JUnit** : `e2e/playwright-report/junit.xml` (CI ingestion)
+- **Trace** : kept on first retry, opened with `npx playwright show-trace …`
+
+## Layout
+
+```
+e2e/
+├── tests/
+│   └── m0-smoke.spec.ts        # bootstrap milestone (current)
+│   └── m<N>-*.spec.ts          # one spec per milestone, added as features land
+├── playwright.config.ts
+├── tsconfig.json
+└── package.json
+```

e2e/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "metamorph-e2e",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "test": "playwright test",
+    "test:headed": "playwright test --headed",
+    "test:debug": "PWDEBUG=1 playwright test",
+    "report": "playwright show-report",
+    "install-browsers": "playwright install --with-deps chromium",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.45.0",
+    "@types/node": "^20.12.7",
+    "@typescript-eslint/eslint-plugin": "^7.13.0",
+    "@typescript-eslint/parser": "^7.13.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.4.5"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

e2e/playwright.config.ts

@@ -0,0 +1,60 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Playwright configuration for Metamorph end-to-end tests.
+ *
+ * Run modes:
+ *   1. Against an already-running stack (default in CI/local):
+ *        cd e2e && BASE_URL=http://localhost:8080 npm test
+ *   2. With auto-spawned dev servers — set PW_AUTOSTART=1 (see `webServer` block).
+ *
+ * Reports:
+ *   - HTML report → `e2e/playwright-report/` (open with `npm run report`)
+ *   - JUnit XML  → `e2e/playwright-report/junit.xml` (CI ingestion)
+ *   - Traces and screenshots are kept on retry for forensics.
+ */
+const BASE_URL = process.env.BASE_URL ?? 'http://localhost:8080';
+const AUTOSTART = process.env.PW_AUTOSTART === '1';
+
+export default defineConfig({
+  testDir: './tests',
+  timeout: 30_000,
+  expect: { timeout: 5_000 },
+  // The stack uses a shared Postgres. Each spec that calls /diag/reset wipes
+  // global state, so we must serialise execution to avoid spec-vs-spec races
+  // (notably the install-token reset and the per-spec admin bootstrap).
+  fullyParallel: false,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: [
+    ['list'],
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'playwright-report/junit.xml' }],
+  ],
+  use: {
+    baseURL: BASE_URL,
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  // Optional: spawn the compose stack via `make up` before the tests run.
+  // Disabled by default — rely on the operator to bring the stack up.
+  ...(AUTOSTART
+    ? {
+        webServer: {
+          command: 'cd .. && make up',
+          url: `${BASE_URL}/api/v1/health`,
+          reuseExistingServer: true,
+          timeout: 120_000,
+          stdout: 'pipe',
+          stderr: 'pipe',
+        },
+      }
+    : {}),
+});

e2e/tests/m0-smoke.spec.ts

@@ -0,0 +1,127 @@
+import { test, expect, type Request } from '@playwright/test';
+
+/**
+ * M0 — Bootstrap smoke checks.
+ * Validates what M0 actually delivers:
+ *   1. The 3-container stack is reachable (front + api proxy).
+ *   2. The home page renders the RTOps design system primitives.
+ *   3. Self-hosted webfonts (no Google Fonts CDN — spec §7).
+ *   4. No JS console errors on first load.
+ *   5. API health endpoint returns the expected JSON.
+ */
+
+test.describe('M0 — bootstrap smoke', () => {
+  const consoleErrors: string[] = [];
+  const externalRequests: string[] = [];
+
+  test.beforeEach(({ page }) => {
+    consoleErrors.length = 0;
+    externalRequests.length = 0;
+
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    page.on('pageerror', (err) => consoleErrors.push(`pageerror: ${err.message}`));
+    page.on('request', (req: Request) => {
+      const url = req.url();
+      if (
+        url.includes('fonts.googleapis.com') ||
+        url.includes('fonts.gstatic.com') ||
+        url.includes('cdn.jsdelivr.net') ||
+        url.includes('unpkg.com')
+      ) {
+        externalRequests.push(url);
+      }
+    });
+  });
+
+  test('home page loads and renders the RTOps header', async ({ page }) => {
+    const resp = await page.goto('/');
+    expect(resp?.status(), 'home page should respond 200').toBe(200);
+    await expect(page).toHaveTitle(/Metamorph/);
+
+    const h1 = page.getByRole('heading', { level: 1 });
+    await expect(h1).toContainText('Metamorph');
+    await expect(h1).toContainText('Purple Team Platform');
+  });
+
+  test('API health card eventually shows OK', async ({ page }) => {
+    await page.goto('/');
+    // The "API" card binds the health probe; wait for the green-accent state.
+    const apiCard = page.locator('h3', { hasText: /^API$/ }).locator('..');
+    await expect(apiCard).toContainText(/version\s+\d+/i, { timeout: 10_000 });
+    await expect(apiCard).toContainText('ok');
+  });
+
+  test('design system primitives render with the expected accent classes', async ({ page }) => {
+    await page.goto('/');
+    // Tags from the demo row.
+    await expect(page.getByText('EVASION', { exact: true })).toBeVisible();
+    await expect(page.getByText('C2', { exact: true })).toBeVisible();
+    await expect(page.getByText('LATERAL', { exact: true })).toBeVisible();
+    // Flow nodes.
+    await expect(page.getByText('recon', { exact: true })).toBeVisible();
+    await expect(page.getByText('impact', { exact: true })).toBeVisible();
+    // Buttons.
+    await expect(page.getByRole('button', { name: /primary/i })).toBeVisible();
+  });
+
+  test('body uses self-hosted IBM Plex Sans, no Google Fonts requests', async ({ page }) => {
+    await page.goto('/');
+    // Wait for fonts to settle.
+    await page.evaluate(() => document.fonts.ready);
+
+    const bodyFont = await page.evaluate(() =>
+      window.getComputedStyle(document.body).fontFamily.toLowerCase(),
+    );
+    expect(bodyFont).toContain('ibm plex sans');
+
+    // Header is mono.
+    const h1Font = await page.evaluate(() => {
+      const h1 = document.querySelector('h1');
+      return h1 ? window.getComputedStyle(h1).fontFamily.toLowerCase() : '';
+    });
+    expect(h1Font).toContain('jetbrains mono');
+
+    // No request must hit Google Fonts or any other CDN — see spec §7.
+    expect(externalRequests, `unexpected CDN traffic: ${externalRequests.join(', ')}`).toEqual([]);
+  });
+
+  test('background uses the RTOps deep navy token', async ({ page }) => {
+    await page.goto('/');
+    const bg = await page.evaluate(() => window.getComputedStyle(document.body).backgroundColor);
+    // tasks/design.md: --bg = #0a0e1a → rgb(10, 14, 26)
+    expect(bg).toBe('rgb(10, 14, 26)');
+  });
+
+  test('no JS console errors on first load', async ({ page }) => {
+    await page.goto('/');
+    await page.waitForLoadState('networkidle');
+    // The auth provider attempts a silent /auth/refresh at mount; without a
+    // refresh cookie the server returns 401 and the browser logs a generic
+    // "Failed to load resource" warning. That's expected for unauthenticated
+    // visitors and doesn't constitute a real error.
+    const realErrors = consoleErrors.filter(
+      (e) => !/Failed to load resource.*401/i.test(e),
+    );
+    expect(realErrors, `console errors: ${realErrors.join(' | ')}`).toEqual([]);
+  });
+
+  test('API health endpoint returns the expected JSON shape', async ({ request }) => {
+    const resp = await request.get('/api/v1/health');
+    expect(resp.status()).toBe(200);
+    const body = (await resp.json()) as { status: string; version: string };
+    expect(body.status).toBe('ok');
+    expect(body.version).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  test('CORS headers are set when the SPA origin asks for them', async ({ request }) => {
+    const resp = await request.get('/api/v1/health', {
+      headers: { Origin: 'http://localhost:8080' },
+    });
+    expect(resp.status()).toBe(200);
+    // flask-cors echoes back the configured origin when allowed.
+    const allowed = resp.headers()['access-control-allow-origin'];
+    expect(allowed === 'http://localhost:8080' || allowed === '*').toBeTruthy();
+  });
+});

e2e/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitOverride": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["playwright.config.ts", "tests/**/*"]
+}