@samahlstrom/forge-cli 0.1.0

package/templates/addons/beads-dolt-backend/files/dolt-setup.sh

@@ -0,0 +1,267 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# dolt-setup.sh — Initialize Dolt database for bead storage
+# Part of the beads-dolt-backend forge addon
+
+DOLT_DIR=".forge/beads/dolt"
+BEAD_STATE_SCRIPT=".forge/bead-state.sh"
+
+# --- Helpers ---
+
+log()  { echo "[dolt-setup] $*"; }
+warn() { echo "[dolt-setup] WARN: $*" >&2; }
+die()  { echo "[dolt-setup] ERROR: $*" >&2; exit 1; }
+
+# --- Check prerequisites ---
+
+log "Checking for Dolt installation..."
+
+if ! command -v dolt > /dev/null 2>&1; then
+  log "Dolt not found. Attempting to install..."
+
+  if command -v brew > /dev/null 2>&1; then
+    log "Installing via Homebrew..."
+    brew install dolt
+  elif command -v curl > /dev/null 2>&1; then
+    log "Installing via install script..."
+    sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'
+  else
+    die "Cannot install Dolt automatically. Install manually: https://docs.dolthub.com/introduction/installation"
+  fi
+
+  # Verify installation
+  if ! command -v dolt > /dev/null 2>&1; then
+    die "Dolt installation failed. Install manually: https://docs.dolthub.com/introduction/installation"
+  fi
+fi
+
+DOLT_VERSION=$(dolt version 2>/dev/null | head -1)
+log "Found: ${DOLT_VERSION}"
+
+# --- Initialize Dolt database ---
+
+if [ -d "${DOLT_DIR}/.dolt" ]; then
+  log "Dolt database already exists at ${DOLT_DIR}"
+else
+  log "Initializing Dolt database at ${DOLT_DIR}..."
+  mkdir -p "${DOLT_DIR}"
+
+  # Configure Dolt user if not already set
+  if ! dolt config --global --get user.name > /dev/null 2>&1; then
+    GIT_USER=$(git config user.name 2>/dev/null || echo "forge-user")
+    GIT_EMAIL=$(git config user.email 2>/dev/null || echo "forge@local")
+    dolt config --global --add user.name "${GIT_USER}"
+    dolt config --global --add user.email "${GIT_EMAIL}"
+    log "Configured Dolt user: ${GIT_USER} <${GIT_EMAIL}>"
+  fi
+
+  cd "${DOLT_DIR}"
+  dolt init
+  cd - > /dev/null
+
+  log "Dolt database initialized"
+fi
+
+# --- Create beads table schema ---
+
+log "Creating beads table schema..."
+
+cd "${DOLT_DIR}"
+
+# Create the beads table if it doesn't exist
+dolt sql -q "
+CREATE TABLE IF NOT EXISTS beads (
+  id VARCHAR(64) PRIMARY KEY,
+  title VARCHAR(255) NOT NULL,
+  status VARCHAR(32) NOT NULL DEFAULT 'open',
+  branch VARCHAR(128),
+  parent_id VARCHAR(64),
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  metadata JSON,
+  INDEX idx_status (status),
+  INDEX idx_branch (branch),
+  INDEX idx_parent (parent_id)
+);
+" 2>/dev/null || log "  beads table already exists or schema unchanged"
+
+# Create the bead_events table for history tracking
+dolt sql -q "
+CREATE TABLE IF NOT EXISTS bead_events (
+  id VARCHAR(64) PRIMARY KEY,
+  bead_id VARCHAR(64) NOT NULL,
+  event_type VARCHAR(32) NOT NULL,
+  actor VARCHAR(128),
+  timestamp TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  data JSON,
+  INDEX idx_bead_id (bead_id),
+  INDEX idx_timestamp (timestamp),
+  FOREIGN KEY (bead_id) REFERENCES beads(id)
+);
+" 2>/dev/null || log "  bead_events table already exists or schema unchanged"
+
+# Create the bead_links table for relationships
+dolt sql -q "
+CREATE TABLE IF NOT EXISTS bead_links (
+  source_id VARCHAR(64) NOT NULL,
+  target_id VARCHAR(64) NOT NULL,
+  link_type VARCHAR(32) NOT NULL DEFAULT 'related',
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (source_id, target_id, link_type),
+  FOREIGN KEY (source_id) REFERENCES beads(id),
+  FOREIGN KEY (target_id) REFERENCES beads(id)
+);
+" 2>/dev/null || log "  bead_links table already exists or schema unchanged"
+
+# Commit the schema
+if dolt status | grep -q "Changes\|new table"; then
+  dolt add .
+  dolt commit -m "Initialize bead storage schema"
+  log "Schema committed to Dolt"
+else
+  log "Schema already up to date"
+fi
+
+cd - > /dev/null
+
+# --- Configure bead-state.sh for Dolt backend ---
+
+log "Configuring bead-state.sh to use Dolt backend..."
+
+if [ -f "${BEAD_STATE_SCRIPT}" ]; then
+  # Check if already configured for dolt
+  if grep -q 'BEAD_BACKEND=dolt\|BEAD_BACKEND="dolt"' "${BEAD_STATE_SCRIPT}" 2>/dev/null; then
+    log "  bead-state.sh already configured for Dolt"
+  else
+    # Add Dolt backend configuration at the top of the script (after shebang)
+    TEMP_FILE=$(mktemp)
+    {
+      head -1 "${BEAD_STATE_SCRIPT}"
+      echo ""
+      echo "# --- Dolt backend configuration (added by beads-dolt-backend addon) ---"
+      echo "export BEAD_BACKEND=dolt"
+      echo "export BEAD_DOLT_DIR=\"${DOLT_DIR}\""
+      echo "# --- End Dolt configuration ---"
+      echo ""
+      tail -n +2 "${BEAD_STATE_SCRIPT}"
+    } > "${TEMP_FILE}"
+    mv "${TEMP_FILE}" "${BEAD_STATE_SCRIPT}"
+    chmod +x "${BEAD_STATE_SCRIPT}"
+    log "  bead-state.sh updated with Dolt backend config"
+  fi
+else
+  # Create a minimal bead-state.sh with Dolt backend
+  mkdir -p "$(dirname "${BEAD_STATE_SCRIPT}")"
+  cat > "${BEAD_STATE_SCRIPT}" <<'BEAD_SCRIPT'
+#!/usr/bin/env bash
+set -euo pipefail
+
+# bead-state.sh — Bead state management (Dolt backend)
+# Generated by beads-dolt-backend addon
+
+export BEAD_BACKEND=dolt
+BEAD_SCRIPT
+
+  # Append the DOLT_DIR (not using heredoc to expand variable)
+  echo "export BEAD_DOLT_DIR=\"${DOLT_DIR}\"" >> "${BEAD_STATE_SCRIPT}"
+
+  cat >> "${BEAD_STATE_SCRIPT}" <<'BEAD_SCRIPT'
+
+COMMAND="${1:-help}"
+shift || true
+
+dolt_query() {
+  cd "${BEAD_DOLT_DIR}" && dolt sql -q "$1" -r json 2>/dev/null && cd - > /dev/null
+}
+
+dolt_exec() {
+  cd "${BEAD_DOLT_DIR}" && dolt sql -q "$1" 2>/dev/null && cd - > /dev/null
+}
+
+dolt_commit() {
+  cd "${BEAD_DOLT_DIR}" && dolt add . && dolt commit -m "$1" 2>/dev/null && cd - > /dev/null
+}
+
+case "$COMMAND" in
+  list)
+    dolt_query "SELECT id, title, status, branch, created_at FROM beads ORDER BY updated_at DESC"
+    ;;
+  get)
+    [ -z "${1:-}" ] && echo "Usage: bead-state.sh get <id>" && exit 1
+    dolt_query "SELECT * FROM beads WHERE id = '$1'"
+    ;;
+  create)
+    ID="${1:-$(uuidgen | tr '[:upper:]' '[:lower:]')}"
+    TITLE="${2:-Untitled bead}"
+    BRANCH="${3:-$(git branch --show-current 2>/dev/null || echo 'none')}"
+    dolt_exec "INSERT INTO beads (id, title, status, branch) VALUES ('${ID}', '${TITLE}', 'open', '${BRANCH}')"
+    dolt_exec "INSERT INTO bead_events (id, bead_id, event_type, actor) VALUES ('$(uuidgen | tr '[:upper:]' '[:lower:]')', '${ID}', 'created', '$(whoami)')"
+    dolt_commit "Create bead: ${TITLE}"
+    echo "${ID}"
+    ;;
+  update)
+    [ -z "${1:-}" ] || [ -z "${2:-}" ] && echo "Usage: bead-state.sh update <id> <status>" && exit 1
+    dolt_exec "UPDATE beads SET status = '$2', updated_at = CURRENT_TIMESTAMP WHERE id = '$1'"
+    dolt_exec "INSERT INTO bead_events (id, bead_id, event_type, actor, data) VALUES ('$(uuidgen | tr '[:upper:]' '[:lower:]')', '$1', 'status_change', '$(whoami)', '{\"status\":\"$2\"}')"
+    dolt_commit "Update bead $1: status -> $2"
+    ;;
+  history)
+    [ -z "${1:-}" ] && echo "Usage: bead-state.sh history <id>" && exit 1
+    dolt_query "SELECT * FROM bead_events WHERE bead_id = '$1' ORDER BY timestamp DESC"
+    ;;
+  diff)
+    cd "${BEAD_DOLT_DIR}" && dolt diff "${1:-HEAD~1}" && cd - > /dev/null
+    ;;
+  sync)
+    cd "${BEAD_DOLT_DIR}"
+    if dolt remote -v 2>/dev/null | grep -q origin; then
+      dolt push origin main 2>/dev/null || echo "Push failed — configure remote with: cd ${BEAD_DOLT_DIR} && dolt remote add origin <url>"
+    else
+      echo "No remote configured. Add one with: cd ${BEAD_DOLT_DIR} && dolt remote add origin <url>"
+    fi
+    cd - > /dev/null
+    ;;
+  help|*)
+    echo "Usage: bead-state.sh <command> [args]"
+    echo ""
+    echo "Commands:"
+    echo "  list              List all beads"
+    echo "  get <id>          Get bead details"
+    echo "  create [id] [title] [branch]  Create a new bead"
+    echo "  update <id> <status>          Update bead status"
+    echo "  history <id>      Show bead event history"
+    echo "  diff [ref]        Show Dolt diff (versioned changes)"
+    echo "  sync              Push to remote Dolt (if configured)"
+    ;;
+esac
+BEAD_SCRIPT
+
+  chmod +x "${BEAD_STATE_SCRIPT}"
+  log "  Created ${BEAD_STATE_SCRIPT} with Dolt backend"
+fi
+
+# --- Add to .gitignore ---
+
+GITIGNORE=".gitignore"
+if [ -f "$GITIGNORE" ]; then
+  if ! grep -q '.forge/beads/dolt' "$GITIGNORE" 2>/dev/null; then
+    echo "" >> "$GITIGNORE"
+    echo "# Dolt bead database (local state)" >> "$GITIGNORE"
+    echo ".forge/beads/dolt/" >> "$GITIGNORE"
+    log "Added .forge/beads/dolt/ to .gitignore"
+  fi
+fi
+
+# --- Done ---
+
+log "Setup complete. Dolt bead backend is ready."
+log ""
+log "Quick start:"
+log "  bash ${BEAD_STATE_SCRIPT} create '' 'My first bead'"
+log "  bash ${BEAD_STATE_SCRIPT} list"
+log "  bash ${BEAD_STATE_SCRIPT} history <id>"
+log ""
+log "For team sync, configure a DoltHub remote:"
+log "  cd ${DOLT_DIR} && dolt remote add origin <dolthub-url>"
+log "  bash ${BEAD_STATE_SCRIPT} sync"

package/templates/addons/beads-dolt-backend/manifest.yaml

@@ -0,0 +1,13 @@
+name: beads-dolt-backend
+description: "Upgrade bead storage to Dolt DB for versioned state and team sync"
+version: 1
+patches:
+  forge_yaml:
+    beads.backend: dolt
+    addons:
+      - "+beads-dolt-backend"
+files:
+  - source: dolt-setup.sh
+    target: .forge/addons/dolt-setup.sh
+post_install:
+  - "bash .forge/addons/dolt-setup.sh"

package/templates/addons/browser-testing/files/browser-smoke.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# browser-smoke.sh — Run Playwright visual smoke tests at mobile + desktop viewports
+# Part of the browser-testing forge addon
+
+SCREENSHOT_DIR=".forge/state/screenshots"
+DEV_PORT="${DEV_PORT:-5173}"
+DEV_URL="http://localhost:${DEV_PORT}"
+TIMEOUT=30
+STARTED_SERVER=false
+PASS=0
+FAIL=0
+ERRORS=()
+
+mkdir -p "${SCREENSHOT_DIR}/mobile" "${SCREENSHOT_DIR}/desktop"
+
+# --- Helpers ---
+
+log()  { echo "[browser-smoke] $*"; }
+warn() { echo "[browser-smoke] WARN: $*" >&2; }
+fail() { echo "[browser-smoke] FAIL: $*" >&2; ERRORS+=("$*"); FAIL=$((FAIL + 1)); }
+pass() { log "PASS: $*"; PASS=$((PASS + 1)); }
+
+cleanup() {
+  if [ "$STARTED_SERVER" = true ]; then
+    log "Stopping dev server (PID ${DEV_PID:-unknown})..."
+    kill "$DEV_PID" 2>/dev/null || true
+    wait "$DEV_PID" 2>/dev/null || true
+  fi
+}
+trap cleanup EXIT
+
+# --- Check Playwright ---
+
+if ! npx playwright --version > /dev/null 2>&1; then
+  log "Playwright not found. Installing chromium..."
+  npx playwright install chromium || {
+    fail "Could not install Playwright. Aborting."
+    exit 1
+  }
+fi
+
+# --- Dev Server ---
+
+check_server() {
+  curl -sf --max-time 3 "${DEV_URL}" > /dev/null 2>&1
+}
+
+if check_server; then
+  log "Dev server already running at ${DEV_URL}"
+else
+  log "Starting dev server..."
+  npm run dev > /tmp/forge-dev-server.log 2>&1 &
+  DEV_PID=$!
+  STARTED_SERVER=true
+
+  # Wait for server to be ready
+  for i in $(seq 1 "$TIMEOUT"); do
+    if check_server; then
+      log "Dev server ready after ${i}s"
+      break
+    fi
+    if ! kill -0 "$DEV_PID" 2>/dev/null; then
+      fail "Dev server process exited unexpectedly. Check /tmp/forge-dev-server.log"
+      echo '{"pass":0,"fail":1,"errors":["Dev server failed to start"]}' > "${SCREENSHOT_DIR}/results.json"
+      exit 1
+    fi
+    sleep 1
+  done
+
+  if ! check_server; then
+    fail "Dev server did not respond within ${TIMEOUT}s"
+    echo '{"pass":0,"fail":1,"errors":["Dev server timeout"]}' > "${SCREENSHOT_DIR}/results.json"
+    exit 1
+  fi
+fi
+
+# --- Determine pages to test ---
+
+PAGES=("/")
+
+# Add pages from changed route files if in a git repo
+if git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
+  while IFS= read -r file; do
+    # Extract route path from SvelteKit-style route files
+    if [[ "$file" =~ src/routes/(.+)/\+page ]]; then
+      route="/${BASH_REMATCH[1]}"
+      # Skip parameterized routes (contain [...] or [[...]])
+      if [[ ! "$route" =~ \[ ]]; then
+        PAGES+=("$route")
+      fi
+    fi
+  done < <(git diff --name-only HEAD~1 2>/dev/null || true)
+fi
+
+# Deduplicate
+PAGES=($(printf '%s\n' "${PAGES[@]}" | sort -u))
+
+log "Testing ${#PAGES[@]} page(s): ${PAGES[*]}"
+
+# --- Run tests ---
+
+run_viewport_test() {
+  local page="$1"
+  local label="$2"
+  local width="$3"
+  local height="$4"
+
+  local safe_name
+  safe_name=$(echo "$page" | sed 's|/|_|g; s|^_||')
+  [ -z "$safe_name" ] && safe_name="home"
+
+  local screenshot_path="${SCREENSHOT_DIR}/${label}/${safe_name}.png"
+
+  log "Testing ${page} at ${label} (${width}x${height})..."
+
+  local script="
+    const { chromium } = require('playwright');
+    (async () => {
+      const browser = await chromium.launch();
+      const context = await browser.newContext({
+        viewport: { width: ${width}, height: ${height} }
+      });
+      const page = await context.newPage();
+      try {
+        const response = await page.goto('${DEV_URL}${page}', {
+          waitUntil: 'networkidle',
+          timeout: ${TIMEOUT}000
+        });
+        const status = response ? response.status() : 0;
+        await page.screenshot({ path: '${screenshot_path}', fullPage: true });
+        if (status >= 400) {
+          console.error('HTTP ' + status);
+          process.exit(2);
+        }
+        // Check for horizontal overflow (mobile)
+        if (${width} <= 768) {
+          const hasOverflow = await page.evaluate(() => {
+            return document.documentElement.scrollWidth > document.documentElement.clientWidth;
+          });
+          if (hasOverflow) {
+            console.error('OVERFLOW');
+            process.exit(3);
+          }
+        }
+        process.exit(0);
+      } catch (err) {
+        console.error(err.message);
+        try { await page.screenshot({ path: '${screenshot_path}', fullPage: true }); } catch (_) {}
+        process.exit(1);
+      } finally {
+        await browser.close();
+      }
+    })();
+  "
+
+  local exit_code=0
+  node -e "$script" 2>/tmp/forge-browser-err.txt || exit_code=$?
+
+  case $exit_code in
+    0) pass "${page} @ ${label}" ;;
+    2)
+      local status
+      status=$(cat /tmp/forge-browser-err.txt)
+      fail "${page} @ ${label}: HTTP error (${status})"
+      ;;
+    3) fail "${page} @ ${label}: horizontal overflow detected on mobile" ;;
+    *) fail "${page} @ ${label}: $(cat /tmp/forge-browser-err.txt)" ;;
+  esac
+}
+
+for page in "${PAGES[@]}"; do
+  run_viewport_test "$page" "mobile"  375  812
+  run_viewport_test "$page" "desktop" 1440 900
+done
+
+# --- Report ---
+
+TOTAL=$((PASS + FAIL))
+
+cat > "${SCREENSHOT_DIR}/results.json" <<EOF
+{
+  "total": ${TOTAL},
+  "pass": ${PASS},
+  "fail": ${FAIL},
+  "pages": ${#PAGES[@]},
+  "errors": [$(printf '"%s",' "${ERRORS[@]}" 2>/dev/null | sed 's/,$//')]
+}
+EOF
+
+log "Results: ${PASS}/${TOTAL} passed, ${FAIL} failed"
+log "Screenshots saved to ${SCREENSHOT_DIR}/"
+log "Results written to ${SCREENSHOT_DIR}/results.json"
+
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/templates/addons/browser-testing/files/visual-qa.md

@@ -0,0 +1,103 @@
+# Visual QA Agent — Browser Testing Addon
+
+You are a visual QA agent. Your job is to verify UI changes at two viewport sizes using Playwright.
+
+## Viewports
+
+| Label   | Width  | Height |
+|---------|--------|--------|
+| mobile  | 375px  | 812px  |
+| desktop | 1440px | 900px  |
+
+## Workflow
+
+### 1. Start the Dev Server
+
+Check if the dev server is already running:
+
+```bash
+curl -sf http://localhost:5173 > /dev/null 2>&1 || npm run dev &
+sleep 3
+```
+
+If the project uses a different port, check `forge.yaml` or `package.json` for the correct `dev` command and port.
+
+### 2. Identify Pages to Test
+
+Read the current changeset (`git diff --name-only HEAD~1`) and determine which routes/pages are affected. Map changed files to their corresponding URLs. At minimum, always test:
+
+- `/` (home page)
+- Any route whose component files were modified
+
+### 3. Take Before Screenshots (Baseline)
+
+If a baseline branch is available (e.g., `main`), check it out temporarily and capture screenshots:
+
+```
+.forge/state/screenshots/before/<page>-mobile.png
+.forge/state/screenshots/before/<page>-desktop.png
+```
+
+Switch back to the working branch after capturing baselines.
+
+### 4. Take After Screenshots
+
+Capture the current state at both viewports:
+
+```
+.forge/state/screenshots/after/<page>-mobile.png
+.forge/state/screenshots/after/<page>-desktop.png
+```
+
+### 5. Visual Regression Check
+
+Compare before/after screenshots. Flag issues:
+
+- **Layout shifts**: Elements that moved unexpectedly between viewports
+- **Overflow**: Content that bleeds outside its container, especially on mobile
+- **Truncation**: Text cut off without ellipsis or scroll
+- **Z-index conflicts**: Overlapping elements that shouldn't overlap
+- **Missing responsive breakpoints**: Desktop layout appearing on mobile
+- **Touch target size**: Interactive elements smaller than 44x44px on mobile
+
+### 6. Responsive Layout Verification
+
+For each page, verify at both viewports:
+
+- Navigation is accessible (hamburger menu on mobile, full nav on desktop)
+- Images scale proportionally without distortion
+- Forms are usable (inputs are full-width on mobile, appropriately sized on desktop)
+- Modals/dialogs fit within the viewport
+- Scroll behavior is correct (no horizontal scroll on mobile)
+- Font sizes are readable (minimum 14px on mobile)
+
+### 7. Report Results
+
+Write a summary to `.forge/state/screenshots/report.md` with:
+
+- Pass/fail per page per viewport
+- Screenshot paths for any failures
+- Specific observations about visual issues
+- Recommendations for fixes
+
+## Screenshot Storage
+
+All screenshots go in `.forge/state/screenshots/`:
+
+```
+.forge/state/screenshots/
+  before/
+    home-mobile.png
+    home-desktop.png
+  after/
+    home-mobile.png
+    home-desktop.png
+  report.md
+```
+
+## Error Handling
+
+- If the dev server fails to start, report the error and skip browser tests
+- If a page returns 404/500, capture the error page screenshot and flag it
+- If Playwright is not installed, run `npx playwright install chromium` first
+- Timeout after 30 seconds per page navigation

package/templates/addons/browser-testing/manifest.yaml

@@ -0,0 +1,20 @@
+name: browser-testing
+description: "Playwright visual QA at mobile + desktop viewports"
+version: 1
+requires:
+  commands:
+    dev: true
+patches:
+  forge_yaml:
+    verification.browser.enabled: true
+    addons:
+      - "+browser-testing"
+  agents:
+    - "+qa-visual"
+files:
+  - source: visual-qa.md
+    target: .forge/addons/visual-qa.md
+  - source: browser-smoke.sh
+    target: .forge/addons/browser-smoke.sh
+post_install:
+  - "npx playwright install chromium"