@osfactory/har 0.1.1

package/dist/templates/har-boilerplate/verify.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+# Progressive verification pipeline for an agent environment.
+# Outputs JSON to stdout, human-readable progress to stderr.
+#
+# Usage: ./.har/verify.sh <agent-id> [--full]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
+
+AGENT_ID="${1:?Usage: verify.sh <agent-id> [--full]}"
+FULL=""
+
+for arg in "${@:2}"; do
+  [ "$arg" = "--full" ] && FULL=1
+done
+
+validate_agent_id "$AGENT_ID"
+
+API_PORT=$(( HARNESS_API_BASE_PORT + AGENT_ID * 10 ))
+
+ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT")" || {
+  echo "No .env.agent.${AGENT_ID} found. Run: ./.har/launch.sh ${AGENT_ID}" >&2
+  exit 1
+}
+
+set -a
+# shellcheck source=/dev/null
+source "$ENV_FILE"
+set +a
+
+WORK_DIR="$(resolve_agent_work_dir "$ENV_FILE")"
+API_PORT="${API_PORT:-$(( HARNESS_API_BASE_PORT + AGENT_ID * 10 ))}"
+
+echo "==> Verifying agent ${AGENT_ID} (work dir: ${WORK_DIR})..." >&2
+
+OVERALL_PASS=true
+START_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+RESULTS_JSON="[]"
+
+run_step() {
+  local name="$1"
+  local cmd="$2"
+  local start end elapsed exit_code output
+
+  printf "  → %-40s" "$name..." >&2
+  start=$(date +%s%3N 2>/dev/null || echo "0")
+
+  set +e
+  output=$(cd "$WORK_DIR" && set -a && . "$ENV_FILE" && set +a && eval "$cmd" 2>&1)
+  exit_code=$?
+  set -e
+
+  end=$(date +%s%3N 2>/dev/null || echo "0")
+  elapsed=$(( end - start ))
+
+  local pass_bool step_output_escaped
+  if [ "$exit_code" = "0" ]; then
+    echo "✓ (${elapsed}ms)" >&2
+    pass_bool="true"
+  else
+    echo "✗ (${elapsed}ms)" >&2
+    echo "$output" | head -30 | sed 's/^/    /' >&2
+    pass_bool="false"
+    OVERALL_PASS=false
+  fi
+
+  step_output_escaped=$(echo "$output" | head -50 | \
+    node -e "let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>process.stdout.write(JSON.stringify(d.trim())))" \
+    2>/dev/null || echo '""')
+
+  RESULTS_JSON=$(echo "$RESULTS_JSON" | node -e "
+const fs = require('fs');
+let arr = JSON.parse(fs.readFileSync('/dev/stdin','utf8'));
+arr.push({name:'$name',pass:$pass_bool,ms:$elapsed,output:$step_output_escaped});
+process.stdout.write(JSON.stringify(arr));
+" 2>/dev/null || echo "$RESULTS_JSON")
+
+  if [ "$pass_bool" = "false" ] && [ -z "$FULL" ]; then
+    return 1
+  fi
+}
+
+run_http_step() {
+  local name="$1"
+  local url="$2"
+  local start end elapsed exit_code output
+
+  printf "  → %-40s" "$name..." >&2
+  start=$(date +%s%3N 2>/dev/null || echo "0")
+
+  set +e
+  output=$(curl -sf "$url" 2>&1)
+  exit_code=$?
+  set -e
+
+  end=$(date +%s%3N 2>/dev/null || echo "0")
+  elapsed=$(( end - start ))
+
+  local pass_bool step_output_escaped
+  if [ "$exit_code" = "0" ]; then
+    echo "✓ (${elapsed}ms)" >&2
+    pass_bool="true"
+  else
+    echo "✗ (${elapsed}ms)" >&2
+    pass_bool="false"
+    OVERALL_PASS=false
+  fi
+
+  step_output_escaped=$(echo "$output" | head -50 | \
+    node -e "let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>process.stdout.write(JSON.stringify(d.trim())))" \
+    2>/dev/null || echo '""')
+
+  RESULTS_JSON=$(echo "$RESULTS_JSON" | node -e "
+const fs = require('fs');
+let arr = JSON.parse(fs.readFileSync('/dev/stdin','utf8'));
+arr.push({name:'$name',pass:$pass_bool,ms:$elapsed,output:$step_output_escaped});
+process.stdout.write(JSON.stringify(arr));
+" 2>/dev/null || echo "$RESULTS_JSON")
+
+  if [ "$pass_bool" = "false" ] && [ -z "$FULL" ]; then
+    return 1
+  fi
+}
+
+# ── Verification stages ─────────────────────────────────────────────────────
+# TODO: Customize these steps for your project.
+# Edit this section directly — do not use a separate config file.
+
+run_step "typecheck" "echo 'TODO: npm run typecheck'" || { [ -z "$FULL" ] && true; }
+run_step "unit-tests" "echo 'TODO: npm test'" || { [ -z "$FULL" ] && true; }
+run_http_step "api-health" "http://localhost:${API_PORT}${HARNESS_HEALTH_CHECK_PATH}" || { [ -z "$FULL" ] && true; }
+
+if [ -n "$FULL" ]; then
+  run_step "lint" "echo 'TODO: npm run lint'" || true
+  run_step "browser-e2e" "run_browser_e2e_if_present \"$SCRIPT_DIR\" \"$AGENT_ID\"" || true
+fi
+
+# ── Output results ────────────────────────────────────────────────────────────
+
+END_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
+
+node -e "
+const results = $RESULTS_JSON;
+const overall = results.length > 0 && results.every(r => r.pass);
+const out = {
+  status: overall ? 'pass' : 'fail',
+  agent_id: $AGENT_ID,
+  total_ms: $TOTAL_MS,
+  stages: results,
+};
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+" 2>/dev/null || echo "{\"status\":\"fail\",\"agent_id\":${AGENT_ID},\"stages\":[]}"
+
+if [ "$OVERALL_PASS" = "false" ]; then
+  exit 1
+fi

package/dist/templates/har-boilerplate-cli/CLAUDE.agent.md

@@ -0,0 +1,41 @@
+# Agent ${AGENT_ID} — Development Environment
+
+> [`AGENT.md`](../AGENT.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
+
+## Environment
+
+| | |
+|--|--|
+| **Agent ID** | ${AGENT_ID} |
+| **Work dir** | Fresh session worktree per launch — see the launch output or `.har/slots/agent-${AGENT_ID}.json` |
+
+**Never edit the main checkout** — launch FIRST, then make ALL file edits under the work dir from the launch output. Relaunching replaces the session (branch kept) and requires explicit confirmation (`--replace` / `confirmReplace`); dirty worktrees also need `--force` after user approval — never autonomously.
+
+```bash
+./.har/agent-cli.sh ${AGENT_ID} status
+```
+
+## Definition of done
+
+- [ ] Full verification returns `"status": "pass"` (`har env verify ${AGENT_ID} --full`, MCP `har_run_verification` with `full: true`, or `./.har/verify.sh ${AGENT_ID} --full`)
+- [ ] When `stages/browser-e2e.sh` exists, full verify includes Playwright — adapt specs under `tests/` for UI changes
+- [ ] New behavior has automated test coverage
+- [ ] Changes committed **in the session worktree** with a clear message
+- [ ] Finish with `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — records the validation and tears down while **keeping the session branch** for the user to push / open a PR
+
+Quick loop: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}`
+
+## Project commands
+
+```bash
+# TODO: adapt for this repository
+# npm run typecheck
+# npm test
+```
+
+## Do not
+
+- Work around a failing harness command with ad-hoc setup — fix the harness or report the failure
+- Edit `.env.agent.${AGENT_ID}` by hand
+- Run `verify` before `launch` when e2e needs a running server
+- Edit the main checkout — all edits go under the session work dir

package/dist/templates/har-boilerplate-cli/README.md

@@ -0,0 +1,112 @@
+# .har — Agent Harness (CLI / library profile)
+
+This directory is the **agent harness** for this repository. It lets AI coding agents run the project in isolated git worktrees with optional Docker-backed shared infra.
+
+Generated and maintained by [`har`](https://github.com/antoineFrau/har). Run `har env maintain` when the repo stack changes.
+
+**The harness is how you run this project.** Launch a slot to exercise the code in isolation; don't hand-roll setup. If a harness command fails, fix the harness or report it — don't silently fall back to ad-hoc commands.
+
+## What's in here
+
+| File | Purpose |
+|------|---------|
+| `README.md` | This file — index of the harness |
+| `manifest.json` | Generator metadata (version, profile, checksums) — do not edit |
+| `harness.env` | Shared config: worktree default, `HARNESS_INFRA_SERVICES`, migrate/seed commands |
+| `stages.json` | Machine-readable registry of runnable harness stages |
+| `stages/` | Optional custom stage scripts registered from `stages.json` |
+| `runs/` | Run history from `har env` / MCP only — `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json` (gitignore) |
+| `artifacts/` | Stage outputs: reports, traces, screenshots, logs |
+| `agent-slot.sh` | Shared agent-id validation (reads limits from `harness.env`) |
+| `setup-infra.sh` | Start optional Docker Compose stack + template database |
+| `launch.sh` | Launch one agent slot (git worktree by default, deps, env file) |
+| `verify.sh` | Verification pipeline (typecheck, tests, lint, build) |
+| `teardown.sh` | Tear down one agent slot (worktree + env file) |
+| `agent-cli.sh` | Inspect slot status, run commands in the work dir |
+| `docker-compose.agent.yml` | Shared infrastructure containers (services listed in `HARNESS_INFRA_SERVICES`) |
+| `CLAUDE.agent.md` | Detailed instructions for coding agents |
+| `justfile` | Optional shortcuts (requires `just`) |
+
+No PM2 or `ecosystem.agent.template.cjs` in this profile — agents run project commands directly in their worktree.
+
+## Quick start
+
+**Preferred — har CLI or MCP** (persists run history under `.har/runs/`):
+
+```bash
+har env launch 1
+har env verify 1
+har env verify 1 --full
+har env teardown 1
+```
+
+In Cursor with HAR MCP configured: use `har_launch_environment`, `har_run_verification`, and `har_teardown_environment`.
+
+**Shell fallback** (no CLI/MCP installed):
+
+```bash
+./.har/setup-infra.sh          # when HARNESS_INFRA_SERVICES is non-empty
+./.har/launch.sh 1
+./.har/verify.sh 1
+./.har/verify.sh 1 --full      # + lint, build, browser-e2e (if Playwright installed)
+./.har/teardown.sh 1
+```
+
+Read **`stages.json`** and **`verificationStages`**. Optional: `har env add-stage playwright`.
+
+## Verification contract
+
+| Mode | Command | Typical steps |
+|------|---------|---------------|
+| Quick | `har env verify <id>` or `verify.sh <id>` | typecheck, unit tests |
+| Full | `har env verify <id> --full` or `verify.sh <id> --full` | + lint, build, **browser-e2e** when `stages/browser-e2e.sh` exists |
+
+Use `har env launch 1 --no-worktree` or `./.har/launch.sh 1 --no-worktree` only when working in the repo root.
+
+## Run history
+
+| Entry point | Writes `.har/runs/`? |
+|-------------|------------------------|
+| `./.har/*.sh` | No |
+| `har env …` / MCP | Yes — main checkout `.har/runs/YYYY-MM-DD/` |
+
+With worktree slots, tests run in the worktree; run JSON lives in the main repo. See `workDir` in each record.
+
+## For coding agents
+
+**Start here:** read [`AGENT.md`](../AGENT.md) at the repo root for a short pointer, then [`.har/CLAUDE.agent.md`](./CLAUDE.agent.md) for full instructions.
+
+Prefer HAR MCP tools or `har env …` for launch, verify, and teardown. Use `./.har/*.sh` only when the CLI is not installed.
+
+Work in the isolated git worktree created by launch. Use `./.har/agent-cli.sh <id> exec ...` to run ad-hoc project commands in that work dir.
+
+When the project needs Postgres, Redis, or similar, add the service to `docker-compose.agent.yml` (or keep one from the menu), list it in `HARNESS_INFRA_SERVICES` in `harness.env`, and use `setup-infra.sh` — never run raw `docker compose` for shared infra. Shared services run once on fixed ports and serve every agent slot.
+
+## Maintaining this harness
+
+When the project stack changes (new test commands, database needs, env vars):
+
+```bash
+har env maintain
+```
+
+The authoring agent updates scripts and this README. Review changes before committing.
+
+**Do not** put runtime behavior in YAML — edit the scripts directly.
+
+## Session lifecycle
+
+Every `launch` starts a **fresh session**: a new git worktree from the current HEAD at
+`~/worktrees/<base-branch>-<sha4>-har-agent-<id>-<rand4>`, on a branch of the same name.
+The session is recorded in `.har/slots/agent-<id>.json` (the slot registry) — status,
+verify, and teardown resolve the work dir through it. Make ALL file edits under the
+work dir printed by launch, never in the main checkout.
+
+- Relaunching a slot **replaces** its previous session; replacement requires `--replace` /
+  `confirmReplace=true` (or an interactive prompt). Uncommitted changes also need `--force`
+  after explicit user approval.
+- `teardown` removes the worktree but **keeps the session branch** so you can push it
+  or open a PR (`--delete-branch` to drop it).
+- `har env complete <id>` finishes a session: full verify (recorded as a validation),
+  then teardown — branch kept.
+- `--no-worktree` runs the slot from the repo root instead (single-agent mode).

package/dist/templates/har-boilerplate-cli/agent-cli.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# Namespaced CLI for managing a CLI/library agent slot.
+#
+# Usage: ./.har/agent-cli.sh <agent-id> <command> [args...]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$SCRIPT_DIR/agent-slot.sh"
+
+AGENT_ID="${1:?Usage: agent-cli.sh <agent-id> <command> [args...]}"
+COMMAND="${2:?Usage: agent-cli.sh <agent-id> <command> [args...]}"
+
+validate_agent_id "$AGENT_ID"
+
+WORKTREE_DIR="$(existing_slot_worktree "$AGENT_ID")"
+DB_PORT="${AGENT_DB_PORT:-15432}"
+export PGPASSWORD="password"
+
+resolve_work_dir() {
+  local env_file
+  env_file="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT")" || {
+    echo "No active environment for agent ${AGENT_ID}" >&2
+    echo "  Run: ./.har/launch.sh ${AGENT_ID}" >&2
+    exit 1
+  }
+  # shellcheck source=/dev/null
+  source "$env_file"
+  resolve_agent_work_dir "$env_file" "$AGENT_ID"
+}
+
+case "$COMMAND" in
+  status)
+    ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT" || true)"
+    REGISTRY_FILE="$(slot_registry_file "$AGENT_ID")"
+
+    if [ -n "$ENV_FILE" ]; then
+      # shellcheck source=/dev/null
+      source "$ENV_FILE"
+      WT="$(existing_slot_worktree "$AGENT_ID")"
+      echo "Agent ${AGENT_ID}: active"
+      echo "  Work dir:  $(resolve_agent_work_dir "$ENV_FILE" "$AGENT_ID")"
+      [ -n "$WT" ] && [ -d "$WT" ] && echo "  Worktree:  $WT"
+      BRANCH="$(read_slot_field "$REGISTRY_FILE" branch || true)"
+      PURPOSE="$(read_slot_field "$REGISTRY_FILE" purpose || true)"
+      CREATED="$(read_slot_field "$REGISTRY_FILE" createdAt || true)"
+      [ -n "$PURPOSE" ] && echo "  Purpose:   $PURPOSE"
+      [ -n "$BRANCH" ] && echo "  Branch:    $BRANCH"
+      [ -n "$CREATED" ] && echo "  Since:     $CREATED"
+      [ -n "$WT" ] && echo "  Git:       $(slot_dirty_summary "$WT")"
+    else
+      echo "No active environment for agent ${AGENT_ID}"
+      echo "  Run: ./.har/launch.sh ${AGENT_ID}"
+    fi
+    ;;
+
+  logs)
+    echo "CLI profile has no managed processes (no PM2)." >&2
+    echo "Run project commands in the work dir, e.g.:" >&2
+    echo "  ./.har/agent-cli.sh ${AGENT_ID} exec npm test" >&2
+    exit 1
+    ;;
+
+  restart)
+    echo "CLI profile has no managed processes to restart." >&2
+    echo "Re-run launch or use exec for project-specific commands." >&2
+    exit 1
+    ;;
+
+  psql)
+    QUERY="${3:-}"
+    if ! har_infra_enabled db; then
+      echo "PostgreSQL infra is disabled in harness.env" >&2
+      exit 1
+    fi
+    if [ -n "$QUERY" ]; then
+      har_pg psql -d "agent_${AGENT_ID}" -c "$QUERY"
+    else
+      har_pg psql -d "agent_${AGENT_ID}"
+    fi
+    ;;
+
+  health)
+    API_PORT=$(( HARNESS_API_BASE_PORT + AGENT_ID * 10 ))
+    if [ -n "${HARNESS_HEALTH_CHECK_PATH:-}" ]; then
+      curl -sf "http://localhost:${API_PORT}${HARNESS_HEALTH_CHECK_PATH}" | node -e "
+const d = require('fs').readFileSync('/dev/stdin','utf8');
+try { console.log(JSON.stringify(JSON.parse(d), null, 2)); } catch { console.log(d); }
+" || curl -v "http://localhost:${API_PORT}${HARNESS_HEALTH_CHECK_PATH}"
+    else
+      echo "No health check path configured in harness.env"
+    fi
+    ;;
+
+  url)
+    FE_PORT=$(( HARNESS_FE_BASE_PORT + AGENT_ID * 10 ))
+    API_PORT=$(( HARNESS_API_BASE_PORT + AGENT_ID * 10 ))
+    WORK_DIR="$(resolve_work_dir 2>/dev/null || echo "$REPO_ROOT")"
+    echo "Work dir:  $WORK_DIR"
+    [ -d "$WORKTREE_DIR" ] && echo "Worktree:  $WORKTREE_DIR"
+    [ -n "${HARNESS_HEALTH_CHECK_PATH:-}" ] && echo "API:       http://localhost:${API_PORT}${HARNESS_HEALTH_CHECK_PATH}"
+    har_infra_enabled db && echo "Database:  agent_${AGENT_ID} @ localhost:${DB_PORT}"
+    har_infra_enabled minio && echo "MinIO:     http://localhost:19001"
+    har_infra_enabled headless-browser && echo "Browser:   http://localhost:13001"
+    har_infra_enabled mailpit && echo "Mailpit:   http://localhost:18025"
+    ;;
+
+  reset-db)
+    if ! har_infra_enabled db; then
+      echo "PostgreSQL infra is disabled in harness.env" >&2
+      exit 1
+    fi
+    echo "==> Resetting database for agent ${AGENT_ID}..."
+    har_pg psql -d postgres -c \
+      "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname='agent_${AGENT_ID}';" \
+      >/dev/null
+    har_pg dropdb --if-exists "agent_${AGENT_ID}"
+    har_pg createdb -T "$HARNESS_TEMPLATE_DB" "agent_${AGENT_ID}"
+    echo "✓ Database reset to clean state"
+    ;;
+
+  slow-queries)
+    if ! har_infra_enabled db; then
+      echo "PostgreSQL infra is disabled in harness.env" >&2
+      exit 1
+    fi
+    har_pg psql -d "agent_${AGENT_ID}" -c "
+SELECT round(mean_exec_time::numeric, 2) AS mean_ms,
+       calls,
+       left(query, 120) AS query
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC
+LIMIT 20;" 2>/dev/null || echo "pg_stat_statements extension not available"
+    ;;
+
+  exec)
+    shift 2
+    if [ $# -eq 0 ]; then
+      echo "Usage: agent-cli.sh ${AGENT_ID} exec <command>" >&2
+      exit 1
+    fi
+    WORK_DIR="$(resolve_work_dir)"
+    if har_infra_enabled db; then
+      PGHOST=localhost PGPORT="$DB_PORT" PGUSER=postgres PGDATABASE="agent_${AGENT_ID}" \
+        bash -c "cd '$WORK_DIR' && $*"
+    else
+      bash -c "cd '$WORK_DIR' && $*"
+    fi
+    ;;
+
+  *)
+    echo "Unknown command: $COMMAND" >&2
+    echo ""
+    echo "Commands: status, url, exec <cmd>"
+    har_infra_enabled db && echo "          psql [query], reset-db, slow-queries"
+    exit 1
+    ;;
+esac