See++ v2

.env.example

@@ -1,32 +1,112 @@
-# A template for the environment variables used in local development.
-# Create a copy of this file as ".env".
-# Fill out your environment variables here.
-# NEVER submit your .env file with secure access keys to Git, GitHub, etc.
-
-# ------------------------------------------------------------------------------
-# General Development Configuration
-# - NODE_ENV: Set the Node environment ("development" or "production")
-# ------------------------------------------------------------------------------
+# Template for local development. Copy this file to `.env` and fill in your
+# values. `.env` is gitignored — never commit real secrets.
+#
+#   cp .env.example .env
+#
+# `.env` is read by docker-compose.yml (directly) and by localdev.sh (which
+# passes --env-file .env to Compose).
+
+# ==============================================================================
+# Core
+# ==============================================================================
+
+# "development" or "production". Keep it "development" for local use —
+# the DevAuthProvider and other developer affordances key on this value.
 NODE_ENV=development
 
-# ------------------------------------------------------------------------------
-# Backend Configuration
-# - EXEC_MODE: What mode to run the backend in ("local" or "lambda")
-# - PORT: The port to expose the backend on
-# - USER_CODE_FILE_PREFIX: A prefix to use for all user code files
-# ------------------------------------------------------------------------------
+
+# ==============================================================================
+# Backend + code-runner
+# ==============================================================================
+
+# "local" runs user code in a Docker container spawned by the backend.
+# "lambda" invokes a deployed Lambda function. Local mode needs Docker
+# running; Lambda mode needs AWS_* credentials below + LAMBDA_FUNCTION_NAME.
 EXEC_MODE=local
+
+# Backend HTTP port inside its container. Host-side port is mapped 1:1 by
+# docker-compose unless you override.
 PORT=3000
+
+# Filename prefix for the user's .cpp under /tmp.
 USER_CODE_FILE_PREFIX=main
 
-# ------------------------------------------------------------------------------
-# AWS Configuration (Optional - only needed for Lambda mode)
-# - AWS_REGION: The region your AWS cluster and services are located in
-# - AWS_ACCESS_KEY_ID: Your account's AWS access key (only used outside deployed apps)
-# - AWS_SECRET_ACCESS_KEY: Your account's AWS secret access key (only used outside deployed apps)
-# - LAMBDA_FUNCTION_NAME: The name of your Lambda function for code execution
-# ------------------------------------------------------------------------------
+
+# ==============================================================================
+# Database (Postgres — docker-compose spins it up as a sibling service)
+# ==============================================================================
+
+# The backend reads DATABASE_URL directly; docker-compose.yml builds it
+# from the postgres service name + credentials. Override here only if you
+# point local at an external DB.
+# DATABASE_URL=postgres://spp:spp@postgres:5432/seepp_main
+
+
+# ==============================================================================
+# Auth — Google OAuth
+# ==============================================================================
+#
+# Create an OAuth 2.0 Web Application client in Google Cloud Console (see
+# docs/oauth-setup.md for the step-by-step). Register these redirect URIs:
+#
+#   http://localhost:4000/api/auth/google/callback          (local)
+#   https://frontend.test.spp.seepluspl.us/api/auth/google/callback  (test)
+#   https://seepluspl.us/api/auth/google/callback           (prod)
+#
+# The Client ID is public and safe to share. The Client Secret is NOT —
+# if it leaks, reset it in the Google Cloud Console and update here + SSM.
+
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+
+# Where OAuth callback URLs are rooted. Override if you run the frontend
+# on a non-default host/port (Google must have the resulting URI registered).
+OAUTH_CALLBACK_BASE_URL=http://localhost:4000
+
+
+# ==============================================================================
+# Auth — sessions
+# ==============================================================================
+
+# Signs session cookies. Generate with:
+#   openssl rand -hex 32
+# Rotating this invalidates every active session (local logs you out).
+SESSION_SECRET=
+
+
+# ==============================================================================
+# Auth — dev-only one-click sign-in (optional)
+# ==============================================================================
+#
+# Registers a `dev` auth provider that signs you in as dev@localhost in one
+# click — no Google round-trip. Triple-gated server-side (NODE_ENV + this
+# flag + absence of AWS_EXECUTION_ENV) so it cannot register in a deployed
+# environment. See docs/oauth-setup.md § "Optional: one-click local
+# sign-in" for safety details.
+
+DEV_AUTH_ENABLED=
+
+
+# ==============================================================================
+# Admin
+# ==============================================================================
+#
+# Users in ADMIN_EMAILS get users.is_admin = true on sign-in / upsert. Comma
+# or semicolon separated; case-insensitive. Leave blank if you don't need
+# anyone promoted via env (use the DevAuthProvider path locally instead).
+ADMIN_EMAILS=
+
+# When DEV_AUTH_ENABLED is on, the Dev User is auto-promoted to admin so
+# you can exercise /admin without jumping through ADMIN_EMAILS. Set to
+# "false" to test the non-admin code path locally. Defaults to true.
+DEV_AUTH_IS_ADMIN=true
+
+
+# ==============================================================================
+# AWS — only needed for EXEC_MODE=lambda or SDK calls outside Fargate
+# ==============================================================================
+
 AWS_REGION=us-west-2
-AWS_ACCESS_KEY_ID=YOUR_AWS_ACCESS_KEY_ID
-AWS_SECRET_ACCESS_KEY=YOUR_AWS_SECRET_ACCESS_KEY
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
 LAMBDA_FUNCTION_NAME=spp-trace-executor-dev

.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# GitHub auto-requests review from these owners on every PR.
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Default owner for everything in the repo.
+*       @knazir

.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    branches: [master]
+
+jobs:
+  backend:
+    name: Backend (build + test)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: backend
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: backend/package-lock.json
+
+      - name: Install
+        run: npm ci
+
+      - name: Test
+        run: npm test
+
+      - name: Build (tsc)
+        run: npm run build
+
+  frontend:
+    name: Frontend (lint + typecheck + test + build)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test
+        run: npm run test
+
+      - name: Build
+        run: npm run build

.gitignore

@@ -4,9 +4,12 @@
 # IDE
 .idea/
 
-# Claude Code
-.claude/
-CLAUDE.md
+# Claude Code — track shared config, ignore per-user
+.claude/settings.local.json
+.claude/.credentials.json
+.claude/commands/
+.claude/scheduled_tasks.lock
+.claude/scheduled_tasks.log
 
 # Temporary Files
 tmp/
@@ -17,4 +20,24 @@ tmp/
 
 # AWS Copilot
 copilot/.workspace
-copilot/environments/*/secrets
+copilot/environments/*/secrets
+
+# Monorepo tooling artifacts
+node_modules/
+**/node_modules/
+**/dist/
+**/.turbo/
+**/coverage/
+.pnpm-store/
+*.tsbuildinfo
+
+# Playwright
+**/test-results/
+**/playwright-report/
+**/playwright/.cache/
+.playwright-mcp/
+
+# Ad-hoc screenshots from Playwright MCP verification runs (root only)
+/*.png
+/*.jpeg
+/*.jpg

CLAUDE.md

@@ -0,0 +1,47 @@
+# See++ Agent Context
+
+Context notes for AI coding assistants (Claude Code, Cursor, etc.). A
+human reader can safely ignore this file.
+
+## Layout
+
+- `backend/` — Node/Express API. Parses Valgrind output into the trace JSON
+  the frontend consumes. Main endpoint is `POST /api/run`.
+- `code-runner/` — sandboxed C++ execution.
+  - `local/` — Docker container (spawned by backend when `EXEC_MODE=local`).
+  - `lambda/` — AWS Lambda (`EXEC_MODE=lambda`).
+  - `SPP-Valgrind/` — git submodule, the modified Valgrind that emits
+    traces.
+- `frontend/` — React + Vite + Tailwind + Zustand. CM6 editor + the
+  visualization pane.
+- `frontend-legacy/` — original 2018 frontend. Reference only; do not
+  modify unless explicitly asked.
+- `copilot/` — AWS Copilot manifests for deployed environments.
+- `docs/` — architecture, deployment, guides, etc.
+- `localdev.sh` — thin `docker compose` wrapper.
+
+## Trace contract
+
+`backend/src/parse_vg_trace.ts` translates Valgrind stdout into the
+`ProgramTrace` JSON the frontend consumes. The frontend revalidates with a
+Zod schema at `frontend/src/trace/schema.ts` — drift surfaces at the
+boundary, not deep in the render tree. The two sides are deliberately
+decoupled (no shared package).
+
+## Running locally
+
+```
+./localdev.sh up
+```
+
+Starts backend, Postgres, frontend, and the code-runner image. Config
+loaded from `.env` (copy from `.env.example`). Defaults to
+`3000 / 4000 / 5432` when `.env` is absent.
+
+## Conventions
+
+- No trailing whitespace; no leading whitespace on blank lines.
+- Tests live next to the code (`foo.ts` + `foo.test.ts`). Run with
+  `npx vitest run` in `frontend/` or `npm test` in `backend/`.
+- Keep per-directory tooling self-contained — no root `package.json`.
+- Don't commit unless asked.