@argus-vrt/web 0.1.0

package/.cta.json

@@ -0,0 +1,15 @@
+{
+  "projectName": "web",
+  "mode": "file-router",
+  "typescript": true,
+  "tailwind": true,
+  "packageManager": "yarn",
+  "git": false,
+  "install": true,
+  "addOnOptions": {},
+  "version": 1,
+  "framework": "react-cra",
+  "chosenAddOns": [
+    "start"
+  ]
+}

package/DEPLOYMENT.md

@@ -0,0 +1,154 @@
+# Deploying Argus Web Dashboard
+
+## Docker Deployment (Recommended)
+
+### Quick Start
+
+```bash
+cd packages/web
+
+# Start the dashboard and database
+docker compose -f docker-compose.prod.yml up -d
+
+# Run database migrations (first time only)
+docker compose -f docker-compose.prod.yml exec web \
+  npx drizzle-kit push
+
+# Check logs
+docker compose -f docker-compose.prod.yml logs -f
+```
+
+The dashboard will be available at `http://localhost:3000`
+
+### Configuration
+
+Create a `.env` file to customize settings:
+
+```bash
+# .env
+PORT=3000
+DB_PASSWORD=your-secure-password
+
+# Path to screenshots directory (for image serving)
+SCREENSHOTS_PATH=/path/to/your/screenshots
+```
+
+### Image Serving
+
+The dashboard needs access to the screenshot files to display them. You have two options:
+
+#### Option A: Mount Screenshots Directory
+
+If the dashboard runs on the same machine as your screenshots:
+
+```yaml
+# In docker-compose.prod.yml
+volumes:
+  - /Users/yourname/projects:/screenshots:ro
+```
+
+Then images at `/Users/yourname/projects/app/.visual-screenshots/...` will be served.
+
+#### Option B: Shared Network Storage
+
+For team setups, mount a shared NFS/SMB volume:
+
+```yaml
+volumes:
+  - type: nfs
+    source: your-nfs-server:/screenshots
+    target: /screenshots
+```
+
+### Production with Reverse Proxy (Nginx)
+
+For HTTPS and domain setup:
+
+```nginx
+# /etc/nginx/sites-available/argus
+server {
+    listen 80;
+    server_name argus.yourcompany.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name argus.yourcompany.com;
+
+    ssl_certificate /etc/letsencrypt/live/argus.yourcompany.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/argus.yourcompany.com/privkey.pem;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_cache_bypass $http_upgrade;
+    }
+}
+```
+
+### Useful Commands
+
+```bash
+# Start services
+docker compose -f docker-compose.prod.yml up -d
+
+# Stop services
+docker compose -f docker-compose.prod.yml down
+
+# View logs
+docker compose -f docker-compose.prod.yml logs -f web
+
+# Rebuild after code changes
+docker compose -f docker-compose.prod.yml build --no-cache
+docker compose -f docker-compose.prod.yml up -d
+
+# Reset database (caution: deletes all data)
+docker compose -f docker-compose.prod.yml down -v
+docker compose -f docker-compose.prod.yml up -d
+```
+
+### Backup Database
+
+```bash
+# Backup
+docker compose -f docker-compose.prod.yml exec db \
+  pg_dump -U argus argus > backup.sql
+
+# Restore
+docker compose -f docker-compose.prod.yml exec -T db \
+  psql -U argus argus < backup.sql
+```
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | Port for the web server |
+| `DATABASE_URL` | (auto) | PostgreSQL connection string |
+| `DB_PASSWORD` | `argus` | Database password |
+| `SCREENSHOTS_PATH` | `./screenshots` | Path to mount for image serving |
+| `NODE_ENV` | `production` | Node environment |
+
+---
+
+## Updating
+
+```bash
+# Pull latest changes
+git pull
+
+# Rebuild and restart
+docker compose -f docker-compose.prod.yml build
+docker compose -f docker-compose.prod.yml up -d
+
+# Run any new migrations
+docker compose -f docker-compose.prod.yml exec web \
+  npx drizzle-kit push
+```

package/Dockerfile

@@ -0,0 +1,51 @@
+# Build stage
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Install dependencies for the monorepo
+COPY package.json yarn.lock ./
+COPY packages/web/package.json ./packages/web/
+COPY packages/shared/package.json ./packages/shared/
+
+RUN corepack enable && corepack prepare yarn@4.12.0 --activate
+RUN yarn install --immutable
+
+# Copy source code
+COPY packages/shared ./packages/shared
+COPY packages/web ./packages/web
+
+# Build shared package first
+WORKDIR /app/packages/shared
+RUN yarn build
+
+# Build web app
+WORKDIR /app/packages/web
+RUN yarn build
+
+# Production stage
+FROM node:20-alpine AS runner
+
+WORKDIR /app
+
+# Create non-root user
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 argus
+
+# Copy built assets
+COPY --from=builder /app/packages/web/dist ./dist
+COPY --from=builder /app/packages/web/package.json ./
+COPY --from=builder /app/node_modules ./node_modules
+
+# Set ownership
+RUN chown -R argus:nodejs /app
+
+USER argus
+
+EXPOSE 3000
+
+ENV NODE_ENV=production
+ENV HOST=0.0.0.0
+ENV PORT=3000
+
+CMD ["node", "dist/server/server.js"]

package/README.md

@@ -0,0 +1,159 @@
+# @argus-vrt/web
+
+**Web dashboard for reviewing visual regression test results.**
+
+A self-hosted dashboard that pairs with [@argus-vrt/cli](https://www.npmjs.com/package/@argus-vrt/cli) to give your team a visual review interface for screenshot diffs — similar to Chromatic, but self-hosted.
+
+## Features
+
+- **Test Overview** - Dashboard showing all test runs with status badges
+- **Image Comparison** - Four view modes:
+  - Side by Side - Compare baseline and current screenshots
+  - Diff Only - View the difference image
+  - Overlay - See diff highlights overlaid on current screenshot with adjustable opacity
+  - Current Only - View just the current screenshot
+- **Story Browser** - Three organization modes:
+  - Flat list - Simple alphabetical list
+  - Tree view - Grouped by component name
+  - Grouped view - Organized by directory structure
+- **Search** - Typeahead search with Cmd/Ctrl+K keyboard shortcut
+- **Filtering** - Filter stories by status (all, changed, new, passed)
+- **Mobile Responsive** - Drawer-based navigation on mobile devices
+- **Dark Mode** - Full dark mode support
+
+## Deployment
+
+### Quick Start with Docker
+
+```bash
+# Clone the repo
+git clone https://github.com/maxcwolf/argus.git
+cd argus/packages/web
+
+# Start the dashboard and database
+docker compose -f docker-compose.prod.yml up -d
+
+# Run database migrations (first time only)
+docker compose -f docker-compose.prod.yml exec web npx drizzle-kit push
+```
+
+The dashboard will be available at `http://localhost:3000`.
+
+### Configuration
+
+Create a `.env` file to customize settings:
+
+```bash
+PORT=3000
+DB_PASSWORD=your-secure-password
+
+# Path to screenshots directory (for image serving)
+SCREENSHOTS_PATH=/path/to/your/screenshots
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | Server port |
+| `DATABASE_URL` | (auto) | PostgreSQL connection string |
+| `DB_PASSWORD` | `argus` | Database password |
+| `SCREENSHOTS_PATH` | `./screenshots` | Path to mount for image serving |
+
+See [DEPLOYMENT.md](./DEPLOYMENT.md) for full production deployment instructions including Nginx reverse proxy with HTTPS, image serving options, and database backup/restore.
+
+## Connecting the CLI
+
+Once the dashboard is running, point your CLI at it by adding `apiUrl` to your project's `.argus.json`:
+
+```json
+{
+  "apiUrl": "http://localhost:3000"
+}
+```
+
+Then upload results after running tests:
+
+```bash
+npx argus test
+```
+
+## Tech Stack
+
+- **Framework**: [TanStack Start](https://tanstack.com/start) with React 19
+- **Routing**: [TanStack Router](https://tanstack.com/router) (file-based)
+- **Database**: PostgreSQL with [Drizzle ORM](https://orm.drizzle.team/)
+- **Styling**: [Tailwind CSS v4](https://tailwindcss.com/) with design tokens
+- **Fonts**: Inter (body), Space Grotesk (headings), JetBrains Mono (code)
+
+---
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20
+- Yarn >= 4
+- Docker (for PostgreSQL)
+
+### Setup
+
+From the repository root:
+
+```bash
+# Install all dependencies
+yarn install
+
+# Start PostgreSQL (from this directory)
+cd packages/web
+docker compose up -d
+
+# Push database schema
+yarn workspace @argus-vrt/web db:push
+
+# Start dev server at http://localhost:3000
+yarn workspace @argus-vrt/web dev
+```
+
+Or if you're already in `packages/web`:
+
+```bash
+docker compose up -d
+yarn db:push
+yarn dev
+```
+
+### Scripts
+
+| Script | Description |
+|--------|-------------|
+| `yarn dev` | Start development server on port 3000 |
+| `yarn build` | Build for production |
+| `yarn preview` | Preview production build |
+| `yarn test` | Run tests with Vitest |
+| `yarn db:generate` | Generate Drizzle migrations |
+| `yarn db:push` | Push schema changes to database |
+| `yarn db:studio` | Open Drizzle Studio |
+
+### Project Structure
+
+```
+src/
+├── components/
+│   ├── image/           # Image comparison components
+│   ├── story/           # Story list/tree components
+│   └── ui/              # Shared UI components
+├── hooks/               # React hooks
+├── lib/                 # Utilities
+├── routes/              # File-based routes
+│   ├── __root.tsx       # Root layout
+│   ├── index.tsx        # Dashboard home
+│   ├── tests/           # Test detail pages
+│   └── branches/        # Branch pages
+├── db/                  # Database schema
+└── styles.css           # Global styles & design tokens
+```
+
+## License
+
+MIT

package/docker-compose.prod.yml

@@ -0,0 +1,38 @@
+version: '3.8'
+
+services:
+  web:
+    build:
+      context: ../..
+      dockerfile: packages/web/Dockerfile
+    ports:
+      - "${PORT:-3000}:3000"
+    environment:
+      - DATABASE_URL=postgresql://argus:${DB_PASSWORD:-argus}@db:5432/argus
+      - NODE_ENV=production
+    depends_on:
+      db:
+        condition: service_healthy
+    volumes:
+      # Mount the screenshots directory so the web app can serve images
+      # Adjust this path to where your screenshots are stored
+      - ${SCREENSHOTS_PATH:-./screenshots}:/screenshots:ro
+    restart: unless-stopped
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: argus
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-argus}
+      POSTGRES_DB: argus
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U argus"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  postgres_data:

package/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: rn-visual-testing-db
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: visual_testing
+    ports:
+      - "5432:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:

package/drizzle/0000_slim_makkari.sql

@@ -0,0 +1,61 @@
+CREATE TYPE "public"."approval_decision" AS ENUM('APPROVE_ALL', 'REJECT_ALL', 'PARTIAL');--> statement-breakpoint
+CREATE TYPE "public"."test_status" AS ENUM('PENDING', 'APPROVED', 'REJECTED', 'PARTIAL');--> statement-breakpoint
+CREATE TABLE "approvals" (
+	"id" text PRIMARY KEY NOT NULL,
+	"test_id" text NOT NULL,
+	"user_id" text NOT NULL,
+	"decision" "approval_decision" NOT NULL,
+	"comment" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "test_user_uniq" UNIQUE("test_id","user_id")
+);
+--> statement-breakpoint
+CREATE TABLE "story_results" (
+	"id" text PRIMARY KEY NOT NULL,
+	"test_id" text NOT NULL,
+	"story_id" text NOT NULL,
+	"kind" text,
+	"component_name" text NOT NULL,
+	"story_name" text NOT NULL,
+	"baseline_url" text,
+	"current_url" text NOT NULL,
+	"diff_url" text,
+	"pixel_diff" real DEFAULT 0 NOT NULL,
+	"ssim_score" real DEFAULT 1 NOT NULL,
+	"has_diff" boolean DEFAULT false NOT NULL,
+	"is_new" boolean DEFAULT false NOT NULL,
+	"render_time" integer,
+	"memory_usage" integer,
+	"approved" boolean
+);
+--> statement-breakpoint
+CREATE TABLE "tests" (
+	"id" text PRIMARY KEY NOT NULL,
+	"branch" text NOT NULL,
+	"base_branch" text DEFAULT 'main' NOT NULL,
+	"commit_hash" text NOT NULL,
+	"commit_message" text,
+	"status" "test_status" DEFAULT 'PENDING' NOT NULL,
+	"total_stories" integer NOT NULL,
+	"changed_count" integer NOT NULL,
+	"passed_count" integer NOT NULL,
+	"failed_count" integer NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"user_id" text
+);
+--> statement-breakpoint
+CREATE TABLE "users" (
+	"id" text PRIMARY KEY NOT NULL,
+	"email" text NOT NULL,
+	"name" text,
+	"avatar_url" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "users_email_unique" UNIQUE("email")
+);
+--> statement-breakpoint
+ALTER TABLE "approvals" ADD CONSTRAINT "approvals_test_id_tests_id_fk" FOREIGN KEY ("test_id") REFERENCES "public"."tests"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "approvals" ADD CONSTRAINT "approvals_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "story_results" ADD CONSTRAINT "story_results_test_id_tests_id_fk" FOREIGN KEY ("test_id") REFERENCES "public"."tests"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "tests" ADD CONSTRAINT "tests_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "test_diff_idx" ON "story_results" USING btree ("test_id","has_diff");--> statement-breakpoint
+CREATE INDEX "branch_created_idx" ON "tests" USING btree ("branch","created_at");