@argus-vrt/web 0.1.0 → 0.2.0

package/README.md

@@ -1,157 +1,150 @@
 # @argus-vrt/web
 
-**Web dashboard for reviewing visual regression test results.**
+**CLI tool for deploying and managing the Argus web dashboard.**
 
-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.
+The Argus web dashboard is a self-hosted review interface for visual regression test results — similar to Chromatic, but self-hosted. This package provides an interactive CLI to set up and manage the dashboard via Docker.
 
-## Features
+## Quick Start
 
-- **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
+```bash
+# Run the interactive setup wizard
+npx @argus-vrt/web init
 
-## Deployment
+# Start the dashboard
+npx @argus-vrt/web start
 
-### Quick Start with Docker
+# Open http://localhost:3000
+```
 
-```bash
-# Clone the repo
-git clone https://github.com/maxcwolf/argus.git
-cd argus/packages/web
+The `init` wizard generates a `docker-compose.yml`, `.env`, and optionally `nginx.conf` in an `./argus/` directory.
 
-# Start the dashboard and database
-docker compose -f docker-compose.prod.yml up -d
+## Prerequisites
 
-# Run database migrations (first time only)
-docker compose -f docker-compose.prod.yml exec web npx drizzle-kit push
-```
+- [Docker](https://docs.docker.com/get-docker/) installed and running
+- Node.js >= 20 (for running the CLI via npx)
+- A [GitHub OAuth App](https://github.com/settings/developers) for authentication
 
-The dashboard will be available at `http://localhost:3000`.
+## Authentication
 
-### Configuration
+Argus requires GitHub OAuth for login. All browser routes are protected — unauthenticated users are redirected to GitHub to sign in.
 
-Create a `.env` file to customize settings:
+The `/api/upload` endpoint used by CI/CD is authenticated separately via API key (`Authorization: Bearer <key>` header), so pipelines don't need GitHub credentials.
 
-```bash
-PORT=3000
-DB_PASSWORD=your-secure-password
+### Setting Up GitHub OAuth
 
-# Path to screenshots directory (for image serving)
-SCREENSHOTS_PATH=/path/to/your/screenshots
-```
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers) → **New OAuth App**
+2. Set the **Authorization callback URL** to `https://your-domain.com/auth/github/callback` (or `http://localhost:3000/auth/github/callback` for local development)
+3. Save the **Client ID** and generate a **Client Secret**
+4. Provide these values when running `npx @argus-vrt/web init`
 
-### Environment Variables
+## Commands
 
-| 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 |
+### `npx @argus-vrt/web init`
 
-See [DEPLOYMENT.md](./DEPLOYMENT.md) for full production deployment instructions including Nginx reverse proxy with HTTPS, image serving options, and database backup/restore.
+Interactive setup wizard. Prompts for:
 
-## Connecting the CLI
+- **PostgreSQL** — include a container (recommended) or use an external instance
+- **Port** — default 3000
+- **Domain** — custom domain or localhost
+- **HTTPS** — Let's Encrypt, custom certificate, or none
+- **Reverse proxy** — include an Nginx container or manage yourself
+- **Screenshots path** — where uploaded screenshots are stored
+- **GitHub Client ID** — from your GitHub OAuth App
+- **GitHub Client Secret** — from your GitHub OAuth App
+- **API key** — for CI/CD uploads (auto-generated by default)
 
-Once the dashboard is running, point your CLI at it by adding `apiUrl` to your project's `.argus.json`:
+A **session secret** is auto-generated and does not require input.
 
-```json
-{
-  "apiUrl": "http://localhost:3000"
-}
-```
+Generates configuration files into `./argus/` (or `--dir <path>`).
 
-Then upload results after running tests:
+### `npx @argus-vrt/web start`
+
+Start Argus containers (`docker compose up -d`).
+
+### `npx @argus-vrt/web stop`
+
+Stop Argus containers (`docker compose down`).
+
+### `npx @argus-vrt/web logs`
+
+Stream container logs (`docker compose logs -f`).
 
 ```bash
-npx argus test
+npx @argus-vrt/web logs --service web    # only web container
+npx @argus-vrt/web logs --service db     # only database
 ```
 
-## Tech Stack
+### `npx @argus-vrt/web status`
 
-- **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)
+Show container status and run a health check on the web dashboard.
 
----
+### `npx @argus-vrt/web upgrade`
 
-## Development
+Pull the latest Docker images and restart containers.
 
-### Prerequisites
+### `npx @argus-vrt/web setup-ssl <domain>`
 
-- Node.js >= 20
-- Yarn >= 4
-- Docker (for PostgreSQL)
+Obtain a Let's Encrypt SSL certificate for your domain. Requires the Nginx and Certbot containers (select Let's Encrypt during `init`).
 
-### Setup
+```bash
+npx @argus-vrt/web setup-ssl argus.yourcompany.com
+```
 
-From the repository root:
+## Options
 
-```bash
-# Install all dependencies
-yarn install
+All management commands (`start`, `stop`, `logs`, `status`, `upgrade`, `setup-ssl`) accept:
+
+| Flag | Description |
+|------|-------------|
+| `-d, --dir <path>` | Path to the Argus directory (default: `./argus`) |
 
-# Start PostgreSQL (from this directory)
-cd packages/web
-docker compose up -d
+## Connecting the CLI
+
+Once the dashboard is running, point the testing CLI at it by adding `apiUrl` and `apiKey` to your project's `.argus.json`:
+
+```json
+{
+  "apiUrl": "http://localhost:3000",
+  "apiKey": "your-api-key-from-init"
+}
+```
 
-# Push database schema
-yarn workspace @argus-vrt/web db:push
+Then upload results after running tests:
 
-# Start dev server at http://localhost:3000
-yarn workspace @argus-vrt/web dev
+```bash
+npx argus test
 ```
 
-Or if you're already in `packages/web`:
+Or upload manually with a header:
 
 ```bash
-docker compose up -d
-yarn db:push
-yarn dev
+curl -X POST https://your-domain.com/api/upload \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{"branch":"main","commitHash":"abc123","stories":[...]}'
 ```
 
-### Scripts
+## Environment Variables
+
+The generated `.env` file includes:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | Server port |
+| `DATABASE_URL` | (auto) | PostgreSQL connection string (external DB only) |
+| `DB_PASSWORD` | `argus` | Database password (container DB only) |
+| `SCREENSHOTS_PATH` | `./argus-data/images` | Path to screenshots directory |
+| `GITHUB_CLIENT_ID` | — | GitHub OAuth App client ID |
+| `GITHUB_CLIENT_SECRET` | — | GitHub OAuth App client secret |
+| `SESSION_SECRET` | (auto-generated) | Encryption key for session cookies |
+| `ARGUS_API_KEY` | (auto-generated) | API key for CI/CD upload authentication |
 
-| 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 |
+## Docker Image
 
-### Project Structure
+The web dashboard is distributed as a Docker image on GitHub Container Registry:
 
 ```
-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
+ghcr.io/maxcwolf/argus-web:latest
 ```
 
 ## License