@osfactory/har 0.9.0 → 0.11.0

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

@@ -35,6 +35,8 @@ seeded data, or a simulator flow, document it here and wire the smoke into
 
 Quick loop: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}`
 
+Stages are the harness's single vocabulary for checks: templates and custom stages compile to generic kinds in `.har/stages.json`, and you interact with them only through the registry (`har_run_stage`, `verify`), never stack-specific tooling. Authoring guide: `.har/STAGES.md`.
+
 ## Project commands
 
 ```bash

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

@@ -0,0 +1,91 @@
+# HAR Stages — authoring guide
+
+Stages are the harness's single vocabulary for runnable checks and lifecycle
+actions. Everything — shipped templates (`playwright`, `rocketsim`), 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.
+
+## 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/`.
+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 stage templates
+
+`har env add-stage --list` shows available templates; `har env add-stage
+playwright` (web) or `har env add-stage rocketsim` (iOS) installs one. A
+template is just packaging: it copies files, merges `package.json` fragments,
+and registers stages through the exact same registry as `--custom`.

package/dist/templates/har-boilerplate-ios/agent-slot.sh

@@ -311,14 +311,43 @@ escape_step_output() {
   printf '%s' "$1" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const s=d.trim().split('\n').slice(0,50).join('\n');process.stdout.write(JSON.stringify(s))})" 2>/dev/null || echo '""'
 }
 
-# Run browser-e2e on verify --full when the Playwright stage template is installed.
-run_browser_e2e_if_present() {
+# Emit "<id>\t<command>" for each registered stage listed in stages.json
+# verificationStages (used by verify --full). Ids without a matching registered
+# stage are inline verify.sh steps and skipped here; lifecycle stages
+# (setup/launch/reset/teardown/inspect) and the verify stage itself never run.
+# Authoring contract: .har/STAGES.md
+list_registered_verification_stage_commands() {
   local script_dir="$1"
   local agent_id="$2"
-  local e2e="$script_dir/stages/browser-e2e.sh"
-  if [ -x "$e2e" ]; then
-    "$e2e" "$agent_id"
-  fi
+  local registry="$script_dir/stages.json"
+  [ -f "$registry" ] || return 0
+  HAR_STAGE_REGISTRY="$registry" HAR_SCRIPT_DIR="$script_dir" HAR_AGENT_ID="$agent_id" node <<'NODE' 2>/dev/null || true
+const fs = require('fs');
+const { HAR_STAGE_REGISTRY, HAR_SCRIPT_DIR, HAR_AGENT_ID } = process.env;
+const shq = (s) => "'" + String(s).replace(/'/g, "'\\''") + "'";
+let reg;
+try { reg = JSON.parse(fs.readFileSync(HAR_STAGE_REGISTRY, 'utf8')); } catch { process.exit(0); }
+const ids = Array.isArray(reg.verificationStages) ? reg.verificationStages : [];
+const stages = Array.isArray(reg.stages) ? reg.stages : [];
+const runnable = new Set(['test', 'custom']);
+for (const id of ids) {
+  const stage = stages.find((s) => s && s.id === id);
+  if (!stage || stage.id === 'verify' || !runnable.has(stage.kind)) continue;
+  const needsAgent = stage.requiresAgentId !== false;
+  let cmd;
+  if (stage.script) {
+    cmd = shq(HAR_SCRIPT_DIR + '/' + stage.script) + (needsAgent ? ' ' + shq(HAR_AGENT_ID) : '');
+  } else if (stage.command) {
+    cmd = stage.command.split('{agentId}').join(HAR_AGENT_ID);
+  } else {
+    continue;
+  }
+  if (stage.cwd) cmd = 'cd ' + shq(stage.cwd) + ' && ' + cmd;
+  const env = stage.env && typeof stage.env === 'object' ? stage.env : {};
+  const prefix = Object.entries(env).map(([k, v]) => k + '=' + shq(v)).join(' ');
+  process.stdout.write(id + '\t' + (prefix ? prefix + ' ' : '') + cmd + '\n');
+}
+NODE
 }
 
 # Optional project-owned "agent usable" smoke beyond health.

package/dist/templates/har-boilerplate-ios/stages/README.sh

@@ -1,12 +1,11 @@
 #!/usr/bin/env bash
-# Optional per-stage scripts live here.
-# Example: ./.har/stages/rocketsim-flows.sh <agent-id>
+# Per-stage scripts live here (e.g. ./.har/stages/browser-e2e.sh <agent-id>).
 #
-# Register custom stages in .har/stages.json with a project-owned command:
-#   "command": "./.har/stages/rocketsim-flows.sh {agentId}"
+# Read .har/STAGES.md for the authoring guide: the stage script contract,
+# command vs script stages, and how verificationStages controls verify --full.
 #
-# To add the RocketSim user-flow stage template:
-#   har env add-stage rocketsim
+# Scaffold a new one with:
+#   har env add-stage <id> --custom --script
 
-echo "Add stage scripts under .har/stages/ and register them in stages.json." >&2
+echo "Add stage scripts under .har/stages/ and register them in stages.json — see .har/STAGES.md." >&2
 exit 1

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

@@ -5,7 +5,8 @@
 # Usage: ./.har/verify.sh <agent-id> [--full]
 #
 # Quick (default): build smoke (compile-only)
-# Full (--full):   + unit tests, lint (SwiftLint), rocketsim-flows (if installed)
+# Full (--full):   + unit tests, lint (SwiftLint), and every registered stage
+#                  in stages.json verificationStages (see .har/STAGES.md)
 # Step lists are examples — not exhaustive. Adapt commands to this repo's stack.
 set -euo pipefail
 
@@ -150,8 +151,13 @@ if [ -n "$FULL" ]; then
 
   run_step "readiness" "run_readiness_if_configured \"$AGENT_ID\"" || true
 
-  # RocketSim user-flow validation — installed via: har env add-stage rocketsim
-  run_rocketsim_flows_if_present "$SCRIPT_DIR" "$AGENT_ID" || true
+  # Registered verification stages from .har/stages.json (see .har/STAGES.md).
+  # Every stage listed in verificationStages with a registered script/command
+  # runs here -- stage templates and custom stages alike.
+  while IFS=$'\t' read -r STAGE_ID STAGE_CMD; do
+    [ -n "$STAGE_ID" ] || continue
+    run_step "$STAGE_ID" "$STAGE_CMD" || true
+  done < <(list_registered_verification_stage_commands "$SCRIPT_DIR" "$AGENT_ID")
 fi
 
 END_TOTAL=$(now_ms)

package/dist/templates/stage-templates/custom-stage-skeleton.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# __STAGE_DESCRIPTION__
+# Custom HAR stage: __STAGE_ID__ (kind: __STAGE_KIND__)
+#
+# Stage script contract (full reference: .har/STAGES.md):
+#   - stdout: a single JSON result object (status, stageId, agent_id, ...)
+#   - stderr: human-readable progress
+#   - $1: agent slot id; extra args may follow
+#   - artifacts: write reports/screenshots/logs under .har/artifacts/__STAGE_ID__/
+#   - exit code: the real status (0 = pass)
+#
+# Usage: ./.har/stages/__STAGE_ID__.sh <agent-id> [extra args...]
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HARNESS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$HARNESS_DIR/.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$HARNESS_DIR/harness.env"
+# shellcheck source=/dev/null
+source "$HARNESS_DIR/agent-slot.sh"
+
+AGENT_ID="${1:?Usage: __STAGE_ID__.sh <agent-id> [extra args...]}"
+validate_agent_id "$AGENT_ID"
+
+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")"
+ARTIFACTS_DIR="$HARNESS_DIR/artifacts/__STAGE_ID__"
+mkdir -p "$ARTIFACTS_DIR"
+
+echo "==> [__STAGE_ID__ agent-${AGENT_ID}] running in ${WORK_DIR}" >&2
+START=$(now_ms)
+
+# ── TODO: implement the stage ────────────────────────────────────────────────
+# Run your checks from $WORK_DIR (the agent's isolated checkout); the slot's
+# ports and env are loaded from $ENV_FILE. Save artifacts to $ARTIFACTS_DIR.
+set +e
+OUTPUT=$(cd "$WORK_DIR" && echo "TODO: implement .har/stages/__STAGE_ID__.sh" && false)
+EXIT_CODE=$?
+set -e
+
+END=$(now_ms)
+STATUS="fail"
+[ "$EXIT_CODE" = "0" ] && STATUS="pass"
+OUTPUT_JSON=$(escape_step_output "$OUTPUT")
+
+node -e "process.stdout.write(JSON.stringify({
+  status: '$STATUS',
+  stageId: '__STAGE_ID__',
+  kind: '__STAGE_KIND__',
+  agent_id: $AGENT_ID,
+  total_ms: $(( END - START )),
+  output: $OUTPUT_JSON
+}, null, 2) + '\n');"
+
+exit "$EXIT_CODE"

package/dist/templates/stage-templates/playwright/template.manifest.json

@@ -40,5 +40,13 @@
   ],
   "merge": {
     "package.json": "package.fragment.json"
-  }
+  },
+  "nextSteps": [
+    "npm install",
+    "npx playwright install",
+    "./.har/launch.sh 1",
+    "./.har/stages/browser-e2e.sh 1",
+    "npx playwright show-report .har/artifacts/browser-e2e/playwright-report"
+  ],
+  "docsPath": ".har/stages/PLAYWRIGHT.md"
 }

package/dist/templates/stage-templates/rocketsim/template.manifest.json

@@ -34,5 +34,6 @@
     "./.har/stages/rocketsim-flows.sh 1",
     "Open .har/artifacts/rocketsim-flows/ for screenshots and per-flow results",
     "Add new flows in flows/ — read .har/stages/ROCKETSIM.md for the authoring guide"
-  ]
+  ],
+  "docsPath": ".har/stages/ROCKETSIM.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "LLM-powered CLI for reproducible agent development environments",
   "keywords": [
     "har",