@osfactory/har 0.64.2 → 1.0.0-rc.1

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

@@ -1,99 +0,0 @@
-# HAR Stages — authoring guide
-
-Stages are the harness's single vocabulary for runnable checks and lifecycle
-actions. Everything — shipped plugins (`playwright`, `rocketsim`, `kerno`, `gitleaks`, `trivy`, `semgrep`), your
-project's test/lint commands, bespoke validation scripts — registers in
-`.har/stages.json` with the same schema, and agents interact with stages only
-through that registry (CLI `har env verify`, MCP `har_run_stage` /
-`har_run_verification`), never through stack-specific tooling.
-
-Philosophy: *plugins install stages; agents only talk to the stage registry.*
-
-## The registry: `.har/stages.json`
-
-```jsonc
-{
-  "verificationStages": ["typecheck", "unit-tests", "api-health", "browser-e2e"],
-  "stages": [
-    {
-      "id": "browser-e2e",              // stable, shell-friendly slug
-      "kind": "test",                   // setup | launch | verify | test | inspect | reset | teardown | custom
-      "description": "Playwright E2E",
-      "script": "stages/browser-e2e.sh", // relative to .har/ — OR use "command"
-      "requiresAgentId": true,           // default true for test/verify/custom kinds
-      "artifacts": [{ "path": ".har/artifacts/browser-e2e", "kind": "directory" }]
-    },
-    {
-      "id": "unit-tests-fast",
-      "kind": "test",
-      "command": "npm test -- --agent {agentId}"   // {agentId} is substituted at run time
-    }
-  ]
-}
-```
-
-Optional stage fields: `cwd` (working directory), `env` (extra env vars),
-`group`, `acceptsArgs` (extra CLI args the stage accepts, e.g. `["--full"]`).
-
-## Two ways to define a stage
-
-**Command stages** — the default for simple checks (`npm test`, `swiftlint`,
-`make check`). One JSON entry, zero files:
-
-```bash
-har env add-stage unit-tests-fast --custom --kind test --command "npm test" --verification
-```
-
-**Script stages** — for anything that needs the slot's env, ports, or
-artifacts. Scaffold a contract-compliant skeleton:
-
-```bash
-har env add-stage db-integrity --custom --script --description "Check DB invariants"
-```
-
-then implement the TODO block in `.har/stages/db-integrity.sh`.
-
-## The stage script contract
-
-Every script under `.har/stages/` must:
-
-1. Source `harness.env` and `agent-slot.sh` from `.har/`. Before sourcing,
-   set `SCRIPT_DIR` to the `.har/` directory (not `stages/`) — `agent-slot.sh`
-   resolves the slot registry via `$SCRIPT_DIR/slots/...`.
-2. Take the agent slot id as `$1` (validate with `validate_agent_id`); extra
-   args may follow.
-3. Load the slot env via `resolve_agent_env_file` and run checks from the
-   agent's work dir (`resolve_agent_work_dir`).
-4. Write artifacts (reports, screenshots, logs) under `.har/artifacts/<id>/`.
-5. Print **only** the normalized JSON result object on stdout
-   (`status`, `stageId`, `agent_id`, `total_ms`, …); log progress to stderr.
-6. Exit with the real status code (0 = pass).
-
-The scaffolded skeleton implements all of this — replace its TODO block.
-
-## Verification membership
-
-Listing a stage id in `verificationStages` is what includes it in
-`har env verify <id> --full`. Ids that match a registered stage run via their
-script/command; ids without a registry entry (e.g. `typecheck`, `api-health`)
-are inline steps owned by `.har/verify.sh`. Lifecycle kinds
-(`setup`/`launch`/`reset`/`teardown`/`inspect`) and `verify` itself never run
-as part of verification, even if listed.
-
-## Commit gate
-
-The registry also holds the optional `commitGate` config (installed via
-`har hooks install`): `{ "commitGate": { "mode": "block" | "warn", "scope":
-"worktrees" | "all" } }` controls whether unverified change batches may be
-committed.
-
-## Shipped plugins
-
-`har env add-plugin --list` shows available plugins; `har env add-plugin
-playwright` (web), `har env add-plugin rocketsim` (iOS), or `har env
-add-plugin kerno` (backend), `har env add-plugin gitleaks` (secrets scanning, any
-stack), or `har env add-plugin trivy` (dependency + IaC security scan, any stack),
-or `har env add-plugin semgrep` (SAST, any stack)
-installs one. A
-plugin is just packaging: it copies files, merges `package.json` fragments,
-and registers stages through the exact same registry as `add-stage --custom`.

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

@@ -1,160 +0,0 @@
-#!/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
-    har_suggest_launch "$AGENT_ID"
-    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)"
-      CREATED="$(read_slot_field "$REGISTRY_FILE" createdAt || true)"
-      [ -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}"
-      har_suggest_launch "$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 make 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