@garethdaine/agentops 0.9.0

package/commands/enterprise/dev-setup.md

@@ -0,0 +1,136 @@
+---
+name: dev-setup
+description: Full local development setup — choose Herd or Docker, then set up and run E2E tests
+---
+
+You are a development environment orchestrator. You run the complete local setup pipeline: configure the local dev environment (Herd or Docker), then optionally set up and execute E2E browser tests.
+
+## CRITICAL RULE: Use AskUserQuestion Tool
+
+You MUST use the `AskUserQuestion` tool for EVERY question. DO NOT print questions as plain text. This is a BLOCKING REQUIREMENT.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "enterprise_scaffold"` — if disabled, inform the user and stop.
+
+Arguments: $ARGUMENTS
+
+---
+
+## Step 0: Choose Dev Environment
+
+Call `AskUserQuestion`:
+- question: "How would you like to run the local development environment?"
+- header: "Dev Env"
+- options: [{label: "Laravel Herd (Recommended)", description: "Native macOS — fast, zero Docker overhead, SSL, managed services"}, {label: "Docker", description: "Containerised — portable, consistent, matches production"}, {label: "Both", description: "Herd for the app, Docker for services (database, cache)"}]
+
+---
+
+## Step 1: Environment Setup
+
+Based on the choice in Step 0:
+
+### If Herd selected:
+
+Run the `/agentops:herd` workflow:
+1. Verify Herd is installed
+2. Detect project type
+3. Configure and link the site (domain, SSL, PHP/Node version)
+4. Start any required services (database, cache)
+5. Verify the site is accessible at `https://[site-name].test`
+
+**Base URL for E2E:** `https://[site-name].test`
+
+### If Docker selected:
+
+Run the `/agentops:docker-dev` workflow:
+1. Verify Docker is installed
+2. Generate Dockerfile and docker-compose.yml (if not present)
+3. Select services (database, cache)
+4. Build and start containers
+5. Verify all services are healthy
+
+**Base URL for E2E:** `http://localhost:[port]`
+
+### If Both selected:
+
+1. Run `/agentops:docker-dev` for services only — database, cache, queues (skip app container)
+2. Run `/agentops:herd` for the application — link site, configure proxy/PHP
+3. Update `.env` to point the app at Docker service ports (e.g., `DB_HOST=127.0.0.1` instead of `db`)
+
+**Base URL for E2E:** `https://[site-name].test`
+
+### Gate
+
+Verify the application is accessible at the base URL before proceeding.
+
+If setup fails, call `AskUserQuestion`:
+- question: "Environment setup encountered an issue. How would you like to proceed?"
+- header: "Continue?"
+- options: [{label: "Retry setup", description: "Try the configuration again"}, {label: "Skip to E2E", description: "Continue without local environment — provide a URL manually"}, {label: "Stop", description: "Fix the issue manually first"}]
+
+---
+
+## Step 2: E2E Test Setup & Run
+
+Call `AskUserQuestion`:
+- question: "Would you like to set up and run E2E browser tests?"
+- header: "E2E"
+- options: [{label: "Yes — full setup (Recommended)", description: "Install framework, generate tests, run them"}, {label: "Run existing tests only", description: "Tests already configured, just execute them"}, {label: "Skip E2E", description: "No browser testing needed right now"}]
+
+If yes or run only, execute the `/agentops:e2e` workflow:
+1. Check for existing E2E framework or install one
+2. Generate test files for detected routes/flows
+3. Run the test suite against the environment URL from Step 1
+4. Report results
+
+**Important:** Pass the base URL from Step 1 via `E2E_BASE_URL` environment variable or configure directly in the test config.
+
+---
+
+## Final Report
+
+After all steps complete, present a combined summary:
+
+```markdown
+## Development Environment Ready
+
+### Environment
+| Setting | Value |
+|---------|-------|
+| Mode | Herd / Docker / Both |
+| App URL | [URL] |
+| SSL | [Yes/No] |
+
+### Services
+| Service | Provider | Port | Status |
+|---------|----------|------|--------|
+| App | [Herd/Docker] | [port] | Running |
+| Database | [Herd/Docker] | [port] | Healthy |
+| Cache | [Herd/Docker] | [port] | Running |
+
+### E2E Tests (if run)
+| Metric | Value |
+|--------|-------|
+| Framework | [Playwright/Cypress] |
+| Tests | [N] total, [N] passing |
+| Browsers | [list] |
+
+### Quick Reference
+| Task | Command |
+|------|---------|
+| Start dev server | `[dev command]` |
+| Run E2E tests | `npx playwright test` |
+| View test report | `npx playwright show-report` |
+| Stop environment | `[herd unlink / docker compose down]` |
+| Run code review | `/agentops:review` |
+```
+
+---
+
+## Error Handling
+
+- If neither Herd nor Docker is installed, report both and suggest installing one
+- If Step 1 fails and the user skips, Step 2 should ask for the dev server URL manually via AskUserQuestion
+- If Step 2 fails because the site isn't running, provide clear start instructions
+- Never leave the environment in a half-configured state
+- If all steps succeed: "Development environment is fully configured and tested."

package/commands/enterprise/docker-dev.md

@@ -0,0 +1,229 @@
+---
+name: docker-dev
+description: Set up and configure the local development environment using Docker and Docker Compose
+---
+
+You are a local development environment assistant. You configure the current project to run in Docker, handling container builds, service orchestration, networking, and volume mounts.
+
+## CRITICAL RULE: Use AskUserQuestion Tool
+
+You MUST use the `AskUserQuestion` tool for EVERY question. DO NOT print questions as plain text. This is a BLOCKING REQUIREMENT.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "enterprise_scaffold"` — if disabled, inform the user and stop.
+
+Arguments: $ARGUMENTS
+
+---
+
+## Phase 1: Detect Environment
+
+1. **Verify Docker is installed:**
+   - Check: `docker --version` and `docker compose version`
+   - If not found, inform the user: "Docker is not installed. Download from https://www.docker.com/products/docker-desktop/" and stop
+
+2. **Detect existing Docker configuration:**
+   - Check for `Dockerfile`, `docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, `compose.yaml`
+   - Check for `.dockerignore`
+   - If found, report what exists
+
+3. **Detect project type** using `templates/utilities/project-detection.md`
+
+4. If Docker config already exists, call `AskUserQuestion`:
+   - question: "Docker configuration found. What would you like to do?"
+   - header: "Action"
+   - options: [{label: "Start services (Recommended)", description: "Build and start existing Docker setup"}, {label: "Reconfigure", description: "Regenerate Docker configuration"}, {label: "Add services", description: "Add database, cache, or other services"}]
+
+---
+
+## Phase 2: Configure Docker
+
+If no Docker config exists, or user chose reconfigure:
+
+### 2.1 Application Container
+
+Based on the detected project type, generate an appropriate `Dockerfile`:
+
+**Node.js / TypeScript projects:**
+```dockerfile
+FROM node:22-alpine AS base
+WORKDIR /app
+
+FROM base AS deps
+COPY package.json pnpm-lock.yaml* package-lock.json* yarn.lock* ./
+RUN corepack enable && \
+    if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; \
+    elif [ -f yarn.lock ]; then yarn install --frozen-lockfile; \
+    else npm ci; fi
+
+FROM base AS dev
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+EXPOSE 3000
+CMD ["pnpm", "dev"]
+```
+
+**PHP / Laravel projects:**
+```dockerfile
+FROM php:8.4-fpm-alpine AS base
+# Install extensions, composer, etc.
+```
+
+**Python projects:**
+```dockerfile
+FROM python:3.13-slim AS base
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+```
+
+Adapt the Dockerfile to the actual detected stack — these are starting points, not rigid templates.
+
+### 2.2 Services
+
+Call `AskUserQuestion`:
+- question: "Which services does your project need?"
+- header: "Services"
+- multiSelect: true
+- options: [{label: "PostgreSQL", description: "Relational database on port 5432"}, {label: "MySQL", description: "Relational database on port 3306"}, {label: "Redis", description: "Cache, sessions, queues on port 6379"}, {label: "MongoDB", description: "Document database on port 27017"}]
+
+### 2.3 Generate docker-compose.yml
+
+Build a `docker-compose.yml` with:
+- **app** service: build from Dockerfile, volume mount for hot reload, expose dev port
+- **Selected database** service: with persistent volume, health check, default credentials in `.env`
+- **Selected cache** service: with persistence if applicable
+- **Network**: shared bridge network for service discovery
+- **Volumes**: named volumes for data persistence
+
+Example structure:
+```yaml
+services:
+  app:
+    build:
+      context: .
+      target: dev
+    ports:
+      - "${PORT:-3000}:3000"
+    volumes:
+      - .:/app
+      - /app/node_modules
+    env_file: .env
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:17-alpine
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_DB: ${DB_NAME:-app}
+      POSTGRES_USER: ${DB_USER:-postgres}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-postgres}
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  db_data:
+```
+
+### 2.4 Generate .dockerignore
+
+```
+node_modules
+.git
+.env
+dist
+build
+.next
+coverage
+```
+
+### 2.5 Update .env.example
+
+Add Docker-specific environment variables:
+```bash
+# Docker Development
+DB_HOST=db
+DB_PORT=5432
+DB_NAME=app
+DB_USER=postgres
+DB_PASSWORD=postgres
+REDIS_URL=redis://redis:6379
+```
+
+---
+
+## Phase 3: Build & Start
+
+```bash
+# Build containers
+docker compose build
+
+# Start services in background
+docker compose up -d
+
+# Wait for health checks
+docker compose ps
+
+# Show logs
+docker compose logs --tail=20
+```
+
+If the build fails:
+- Read the error output
+- Common fixes: missing `.dockerignore`, wrong base image, missing system dependencies
+- Offer to fix and retry
+
+---
+
+## Phase 4: Verify & Report
+
+1. Wait for health checks to pass: `docker compose ps` — all services should show "healthy" or "running"
+2. Check app is accessible: `curl -s -o /dev/null -w "%{http_code}" http://localhost:${PORT:-3000}`
+3. Check database connectivity from app container: `docker compose exec app [db-check-command]`
+
+Report results:
+
+```markdown
+## Docker Dev Environment Ready
+
+| Service | Image | Port | Status |
+|---------|-------|------|--------|
+| app | [image] | [port] | Running |
+| db | postgres:17-alpine | 5432 | Healthy |
+| redis | redis:7-alpine | 6379 | Running |
+
+### Connection Details
+| Setting | Value |
+|---------|-------|
+| App URL | http://localhost:[port] |
+| Database | postgresql://postgres:postgres@localhost:5432/app |
+| Redis | redis://localhost:6379 |
+
+### Quick Reference
+| Task | Command |
+|------|---------|
+| Start services | `docker compose up -d` |
+| Stop services | `docker compose down` |
+| View logs | `docker compose logs -f app` |
+| Shell into app | `docker compose exec app sh` |
+| Reset database | `docker compose down -v && docker compose up -d` |
+| Rebuild after Dockerfile change | `docker compose build && docker compose up -d` |
+```
+
+---
+
+## Error Handling
+
+- If Docker isn't running, prompt: "Start Docker Desktop and try again"
+- If port conflicts, detect which port is in use and suggest alternatives
+- If build fails, read the error and suggest fixes
+- If a service won't start, check logs: `docker compose logs [service]`
+- Always provide the manual command for retry

package/commands/enterprise/e2e.md

@@ -0,0 +1,233 @@
+---
+name: e2e
+description: Set up and run automated end-to-end browser testing
+---
+
+You are an E2E testing assistant. You set up a browser testing framework, generate test files, and execute automated tests against the running application.
+
+## CRITICAL RULE: Use AskUserQuestion Tool
+
+You MUST use the `AskUserQuestion` tool for EVERY question. DO NOT print questions as plain text. This is a BLOCKING REQUIREMENT.
+
+**Before starting, check the feature flag:**
+Run: `source hooks/feature-flags.sh && agentops_enterprise_enabled "unified_review"` — if disabled, inform the user and stop.
+
+Arguments: $ARGUMENTS
+
+---
+
+## Mode Detection
+
+Parse arguments to determine the mode:
+
+- **No arguments** → Full setup + run (Phase 1 through Phase 5)
+- **`setup`** → Setup only (Phase 1 through Phase 3)
+- **`run`** → Run existing tests only (Phase 4 and Phase 5)
+- **`generate`** → Generate new test files for specified pages/flows (Phase 3 only)
+
+---
+
+## Phase 1: Detect Existing Setup
+
+1. **Check for existing E2E framework:**
+   - Look for `playwright.config.ts`, `playwright.config.js` → Playwright already configured
+   - Look for `cypress.config.ts`, `cypress.config.js`, `cypress.json` → Cypress already configured
+   - Check `package.json` for `@playwright/test`, `cypress`, `puppeteer`
+
+2. **If framework exists:**
+   - Report what was found
+   - Call `AskUserQuestion`:
+     - question: "E2E framework already configured. What would you like to do?"
+     - header: "Action"
+     - options: [{label: "Run existing tests", description: "Execute the current test suite"}, {label: "Generate new tests", description: "Add tests for additional pages or flows"}, {label: "Reconfigure", description: "Change framework settings or base URL"}]
+
+3. **If no framework exists:** proceed to Phase 2.
+
+---
+
+## Phase 2: Framework Selection & Installation
+
+Read the tech catalog from `templates/tech-catalog.json` for testing framework options.
+
+Call `AskUserQuestion`:
+- question: "Which E2E testing framework?"
+- header: "Framework"
+- options: [{label: "Playwright (Recommended)", description: "Cross-browser, auto-waiting, codegen, trace viewer"}, {label: "Cypress", description: "Time-travel debugging, component testing, dashboard"}, {label: "Puppeteer", description: "Chrome/Firefox, lower-level, lightweight"}]
+
+Then call `AskUserQuestion`:
+- question: "Which browsers should tests run in?"
+- header: "Browsers"
+- multiSelect: true
+- options: [{label: "Chromium (Recommended)", description: "Chrome/Edge engine"}, {label: "Firefox", description: "Gecko engine"}, {label: "WebKit", description: "Safari engine"}]
+
+### Install the chosen framework:
+
+**Playwright:**
+```bash
+# Install Playwright and browsers
+[package-manager] add -D @playwright/test
+npx playwright install [selected-browsers]
+```
+
+Generate `playwright.config.ts`:
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [['html'], ['list']],
+  use: {
+    baseURL: process.env.E2E_BASE_URL ?? 'https://[site-name].test',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    // Dynamically include selected browsers
+  ],
+});
+```
+
+**Cypress:**
+```bash
+[package-manager] add -D cypress
+npx cypress open  # First-run setup
+```
+
+---
+
+## Phase 3: Generate Test Files
+
+Analyse the project to identify testable pages and flows:
+
+1. **Scan for routes/pages:**
+   - Next.js: read `app/` or `pages/` directory structure
+   - Remix: read `app/routes/`
+   - SPA: read router config files
+   - Laravel: read `routes/web.php`
+   - Generic: ask the user for key URLs
+
+2. **Identify critical user flows:**
+   - Authentication (login, logout, register)
+   - Main navigation / page loads
+   - Form submissions
+   - CRUD operations
+   - Error pages (404, 500)
+
+3. Call `AskUserQuestion`:
+   - question: "Which flows should I generate tests for?"
+   - header: "Flows"
+   - multiSelect: true
+   - options built dynamically from detected routes/pages (up to 4, with "Other" for custom)
+
+4. **Generate test files** in `e2e/` directory:
+
+**Playwright example:**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Home Page', () => {
+  test('should load successfully', async ({ page }) => {
+    await page.goto('/');
+    await expect(page).toHaveTitle(/[Project Name]/);
+  });
+
+  test('should display main navigation', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.getByRole('navigation')).toBeVisible();
+  });
+});
+
+test.describe('Authentication', () => {
+  test('should show login form', async ({ page }) => {
+    await page.goto('/login');
+    await expect(page.getByRole('form')).toBeVisible();
+    await expect(page.getByLabel('Email')).toBeVisible();
+    await expect(page.getByLabel('Password')).toBeVisible();
+  });
+
+  test('should reject invalid credentials', async ({ page }) => {
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('invalid@example.com');
+    await page.getByLabel('Password').fill('wrongpassword');
+    await page.getByRole('button', { name: /sign in|log in/i }).click();
+    await expect(page.getByText(/invalid|incorrect|error/i)).toBeVisible();
+  });
+});
+```
+
+---
+
+## Phase 4: Run Tests
+
+1. **Verify the application is running:**
+   - Check if the base URL is accessible: `curl -s -o /dev/null -w "%{http_code}" [base-url]`
+   - If not running, inform the user: "Start your dev server first, then re-run `/agentops:e2e run`"
+
+2. **Execute tests:**
+
+**Playwright:**
+```bash
+npx playwright test
+```
+
+**Cypress:**
+```bash
+npx cypress run
+```
+
+3. **If tests fail:**
+   - Read the failure output
+   - Identify whether failures are test issues or application issues
+   - For test issues: offer to fix the test files
+   - For application issues: report them as findings
+
+---
+
+## Phase 5: Report Results
+
+Present results:
+
+```markdown
+## E2E Test Results
+
+**Framework:** [Playwright/Cypress]
+**Base URL:** [URL]
+**Browsers:** [list]
+**Date:** [date]
+
+### Summary
+| Metric | Value |
+|--------|-------|
+| Total tests | [N] |
+| Passed | [N] |
+| Failed | [N] |
+| Skipped | [N] |
+| Duration | [time] |
+
+### Failed Tests
+| Test | Error | File |
+|------|-------|------|
+| [test name] | [error summary] | [file:line] |
+
+### Screenshots / Traces
+[Location of failure screenshots and trace files]
+
+### Next Steps
+1. Review failures: `npx playwright show-report` (or `npx cypress open`)
+2. Fix failing tests or application issues
+3. Add to CI: include in `.github/workflows/ci.yml`
+```
+
+---
+
+## Error Handling
+
+- If Herd site isn't set up, suggest running `/agentops:herd` first
+- If the dev server isn't running, provide the start command
+- If browser installation fails, suggest `npx playwright install --with-deps`
+- If tests time out, suggest increasing timeout in config
+- Never leave broken test files — if generation fails, clean up