@osfactory/har 0.1.1

package/dist/templates/stage-templates/rocketsim/.har/stages/rocketsim-flows.sh

@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+# RocketSim user-flow runner for an agent slot.
+# Discovers and runs all flow scripts under flows/ (or a specific one from args).
+# Outputs JSON to stdout, human-readable progress to stderr.
+#
+# Usage: ./.har/stages/rocketsim-flows.sh <agent-id> [flow-name]
+#   flow-name (optional): run only flows/<flow-name>.sh instead of all flows
+#
+# Prerequisite: ./.har/launch.sh <agent-id> AND app installed+running on simulator
+# See: ./.har/stages/ROCKETSIM.md for the full authoring guide.
+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: rocketsim-flows.sh <agent-id> [flow-name]}"
+FLOW_FILTER="${2:-}"
+
+validate_agent_id "$AGENT_ID"
+
+log() { echo "==> [rocketsim agent-$AGENT_ID] $*" >&2; }
+
+# ── Preflight ─────────────────────────────────────────────────────────────────
+if ! command -v rocketsim >/dev/null 2>&1; then
+  echo "Error: rocketsim CLI not found." >&2
+  echo "  Install from RocketSim → Settings → CLI & Agent → Install Command Line Tool" >&2
+  echo "  Then re-run: ./.har/stages/rocketsim-flows.sh ${AGENT_ID}" >&2
+  exit 1
+fi
+
+# Check RocketSim + Simulator health
+if ! rocketsim doctor --quiet 2>/dev/null; then
+  log "Warning: rocketsim doctor reported issues — flows may be unreliable."
+  log "  Run 'rocketsim doctor' for details."
+fi
+
+# ── Resolve agent env ─────────────────────────────────────────────────────────
+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")"
+
+# ── Discover flows ─────────────────────────────────────────────────────────────
+FLOWS_DIR="$WORK_DIR/flows"
+
+if [ ! -d "$FLOWS_DIR" ]; then
+  echo "Warning: flows/ directory not found in $WORK_DIR" >&2
+  echo "  Create flow scripts under flows/ — see .har/stages/ROCKETSIM.md" >&2
+  node -e "process.stdout.write(JSON.stringify({
+    status: 'pass',
+    stageId: 'rocketsim-flows',
+    kind: 'test',
+    agent_id: ${AGENT_ID},
+    total_ms: 0,
+    flows: [],
+    message: 'No flows directory — nothing to run'
+  }, null, 2) + '\n');"
+  exit 0
+fi
+
+if [ -n "$FLOW_FILTER" ]; then
+  FLOW_SCRIPTS=("$FLOWS_DIR/${FLOW_FILTER%.sh}.sh")
+  if [ ! -f "${FLOW_SCRIPTS[0]}" ]; then
+    echo "Error: flow not found: flows/${FLOW_FILTER%.sh}.sh" >&2
+    exit 1
+  fi
+else
+  mapfile -t FLOW_SCRIPTS < <(find "$FLOWS_DIR" -maxdepth 1 -name "*.sh" ! -name ".*" | sort)
+fi
+
+if [ ${#FLOW_SCRIPTS[@]} -eq 0 ]; then
+  log "No flow scripts found in flows/ — add .sh files to define user flows."
+  node -e "process.stdout.write(JSON.stringify({
+    status: 'pass',
+    stageId: 'rocketsim-flows',
+    kind: 'test',
+    agent_id: ${AGENT_ID},
+    total_ms: 0,
+    flows: [],
+    message: 'No flows defined yet'
+  }, null, 2) + '\n');"
+  exit 0
+fi
+
+# ── Artifact directory ────────────────────────────────────────────────────────
+ARTIFACT_DIR="$REPO_ROOT/.har/artifacts/rocketsim-flows"
+mkdir -p "$ARTIFACT_DIR"
+
+# ── Run flows ─────────────────────────────────────────────────────────────────
+log "Running ${#FLOW_SCRIPTS[@]} flow(s) against simulator..."
+
+OVERALL_PASS=true
+START_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+FLOW_RESULTS="[]"
+
+for FLOW_SCRIPT in "${FLOW_SCRIPTS[@]}"; do
+  FLOW_NAME="$(basename "$FLOW_SCRIPT" .sh)"
+  printf "  → %-40s" "$FLOW_NAME..." >&2
+
+  FLOW_ARTIFACT_DIR="$ARTIFACT_DIR/$FLOW_NAME"
+  mkdir -p "$FLOW_ARTIFACT_DIR"
+
+  FLOW_START=$(date +%s%3N 2>/dev/null || echo "0")
+
+  set +e
+  FLOW_OUTPUT=$(
+    HARNESS_DIR="$HARNESS_DIR" \
+    WORK_DIR="$WORK_DIR" \
+    AGENT_ID="$AGENT_ID" \
+    FLOW_ARTIFACT_DIR="$FLOW_ARTIFACT_DIR" \
+    HARNESS_BUNDLE_ID="${HARNESS_BUNDLE_ID:-}" \
+    HARNESS_SIMULATOR_NAME="${HARNESS_SIMULATOR_NAME:-}" \
+    bash "$FLOW_SCRIPT" 2>&1
+  )
+  FLOW_EXIT=$?
+  set -e
+
+  FLOW_END=$(date +%s%3N 2>/dev/null || echo "0")
+  FLOW_MS=$(( FLOW_END - FLOW_START ))
+
+  if [ "$FLOW_EXIT" = "0" ]; then
+    echo "✓ (${FLOW_MS}ms)" >&2
+    FLOW_PASS="true"
+  else
+    echo "✗ (${FLOW_MS}ms)" >&2
+    echo "$FLOW_OUTPUT" | head -20 | sed 's/^/    /' >&2
+    FLOW_PASS="false"
+    OVERALL_PASS=false
+  fi
+
+  # Save flow output to artifact
+  echo "$FLOW_OUTPUT" > "$FLOW_ARTIFACT_DIR/output.log"
+
+  FLOW_OUTPUT_ESC=$(echo "$FLOW_OUTPUT" | head -30 | \
+    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 '""')
+
+  FLOW_RESULTS=$(echo "$FLOW_RESULTS" | node -e "
+const fs = require('fs');
+let arr = JSON.parse(fs.readFileSync('/dev/stdin','utf8'));
+arr.push({
+  name: '$FLOW_NAME',
+  pass: $FLOW_PASS,
+  ms: $FLOW_MS,
+  output: $FLOW_OUTPUT_ESC,
+  artifacts: '$FLOW_ARTIFACT_DIR'
+});
+process.stdout.write(JSON.stringify(arr));
+" 2>/dev/null || echo "$FLOW_RESULTS")
+done
+
+END_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
+
+# ── Output ────────────────────────────────────────────────────────────────────
+node -e "
+const flows = $FLOW_RESULTS;
+const overall = flows.length > 0 && flows.every(f => f.pass);
+const out = {
+  status: overall ? 'pass' : 'fail',
+  stageId: 'rocketsim-flows',
+  kind: 'test',
+  agent_id: $AGENT_ID,
+  total_ms: $TOTAL_MS,
+  flows,
+  artifacts: [
+    { path: '.har/artifacts/rocketsim-flows', kind: 'directory' }
+  ]
+};
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+"
+
+if [ "$OVERALL_PASS" = "false" ]; then
+  exit 1
+fi

package/dist/templates/stage-templates/rocketsim/README.md

@@ -0,0 +1,66 @@
+# RocketSim Stage Template
+
+Add reusable RocketSim user-flow validation to your iOS harness.
+
+```bash
+har env add-stage rocketsim
+```
+
+## What this installs
+
+| File | Purpose |
+|------|---------|
+| `.har/stages/rocketsim-flows.sh` | Stage runner — discovers and runs all `flows/*.sh` scripts |
+| `.har/stages/ROCKETSIM.md` | Authoring guide: CLI reference, flow contract, naming conventions |
+| `flows/README.md` | Quick start for adding new flows |
+| `flows/example-smoke.sh` | Example smoke test — adapt for your app's main screen |
+
+## Workflow
+
+```
+        Code change
+             │
+       launch slot
+             │
+    build + unit-tests
+             │
+      rocketsim-flows  ◄── your flows/*.sh scripts
+             │
+          pass/fail
+```
+
+Full verify (`verify --full`) runs all flows after lint.
+
+## Requirements
+
+- [RocketSim](https://www.rocketsim.app/) installed and running
+- `rocketsim` CLI installed from RocketSim → Settings → CLI & Agent
+- At least one iOS Simulator booted (`xcrun simctl list devices | grep Booted`)
+- Your app installed on the simulator before running flows
+
+## Quick start after install
+
+```bash
+# 1. Install the stage
+har env add-stage rocketsim
+
+# 2. Check RocketSim health
+rocketsim doctor
+
+# 3. Build and install your app
+xcodebuild build ... && xcrun simctl install booted path/to/MyApp.app
+xcrun simctl launch booted com.example.myapp
+
+# 4. Run the example flow (adapt it for your main screen)
+./.har/stages/rocketsim-flows.sh 1 example-smoke
+
+# 5. Add real flows
+cp flows/example-smoke.sh flows/my-feature.sh
+# Edit flows/my-feature.sh to navigate your app and assert state
+
+# 6. Run all flows
+./.har/stages/rocketsim-flows.sh 1
+
+# 7. Validate everything
+./.har/verify.sh 1 --full
+```

package/dist/templates/stage-templates/rocketsim/flows/README.md

@@ -0,0 +1,36 @@
+# User Flow Scripts (RocketSim)
+
+This directory contains reusable bash scripts that validate your iOS app's user flows against a running simulator using the [RocketSim CLI](https://www.rocketsim.app/docs/features/agentic-development/rocketsim-cli/).
+
+The `rocketsim-flows` harness stage runs all scripts in this directory during full verification (`verify --full`). A single flow can also be run directly:
+
+```bash
+./.har/stages/rocketsim-flows.sh 1 <flow-name>
+```
+
+## Adding a new flow
+
+1. Create `flows/<name>.sh` (copy from `example-smoke.sh`)
+2. Make it executable: `chmod +x flows/<name>.sh`
+3. Run it: `./.har/stages/rocketsim-flows.sh 1 <name>`
+
+Read `.har/stages/ROCKETSIM.md` for the full authoring guide and CLI reference.
+
+## Naming convention
+
+| Pattern | Example |
+|---------|---------|
+| One flow per user journey | `onboarding.sh`, `login.sh`, `checkout.sh` |
+| Feature-specific flows | `settings-notifications.sh`, `profile-edit.sh` |
+| Smoke test (run first) | `example-smoke.sh` or `smoke.sh` |
+
+## How flows are run
+
+The runner (`rocketsim-flows.sh`) sets these variables for every flow:
+
+| Variable | Description |
+|----------|-------------|
+| `FLOW_ARTIFACT_DIR` | Save screenshots here (`$FLOW_ARTIFACT_DIR/success.png`, `failure.png`) |
+| `HARNESS_BUNDLE_ID` | App bundle ID from `harness.env` |
+| `HARNESS_SIMULATOR_NAME` | Simulator name from `harness.env` |
+| `WORK_DIR` | Path to the session worktree |

package/dist/templates/stage-templates/rocketsim/flows/example-smoke.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# flows/example-smoke.sh — Smoke test: verify the app launches and shows its main screen.
+#
+# Adapt this flow for your application:
+#   1. Replace "Main Screen Title" with a visible element on your app's main screen.
+#   2. Optionally add a tap and validate the next screen.
+#   3. Rename and copy to create more specific user journey flows.
+#
+# See .har/stages/ROCKETSIM.md for the full authoring guide.
+set -euo pipefail
+
+log() { echo "==> [example-smoke] $*" >&2; }
+
+# ── Preflight ─────────────────────────────────────────────────────────────────
+# The app must be running on the simulator. Install and launch it before running
+# this flow. Example:
+#   xcrun simctl install booted path/to/MyApp.app
+#   xcrun simctl launch booted "${HARNESS_BUNDLE_ID}"
+
+log "Checking simulator focus..."
+FOCUSED=$(rocketsim simulator focused 2>/dev/null || echo "")
+if [ -z "$FOCUSED" ]; then
+  log "✗ No focused simulator — run ./.har/setup-infra.sh first"
+  exit 1
+fi
+log "Simulator: $(echo "$FOCUSED" | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const j=JSON.parse(d);process.stdout.write(j.name||d.trim());}catch{process.stdout.write(d.trim());}})" 2>/dev/null || echo "$FOCUSED")"
+
+# ── Wait for app to be ready ──────────────────────────────────────────────────
+log "Waiting for app to settle..."
+rocketsim wait screen-changed --timeout 5 2>/dev/null || true
+sleep 1
+
+# ── Read visible elements ─────────────────────────────────────────────────────
+ELEMENTS=$(rocketsim elements --agent 2>/dev/null || echo "")
+
+if [ -z "$ELEMENTS" ]; then
+  log "✗ No elements found on screen — is the app running?"
+  rocketsim screenshot > "$FLOW_ARTIFACT_DIR/failure-no-elements.png" 2>/dev/null || true
+  exit 1
+fi
+
+log "Visible elements:"
+echo "$ELEMENTS" | head -20 | sed 's/^/    /' >&2
+
+# ── Assert main screen ────────────────────────────────────────────────────────
+# TODO: replace "Main Screen Title" with a StaticText or other element that
+# uniquely identifies your app's main screen after launch.
+EXPECTED_LABEL="Main Screen Title"
+
+if echo "$ELEMENTS" | grep -qi "$EXPECTED_LABEL"; then
+  log "✓ Found expected element: '$EXPECTED_LABEL'"
+  rocketsim screenshot > "$FLOW_ARTIFACT_DIR/success.png" 2>/dev/null || true
+else
+  log "✗ Expected element not found: '$EXPECTED_LABEL'"
+  log "  Adapt EXPECTED_LABEL in flows/example-smoke.sh to match your app's main screen."
+  rocketsim screenshot > "$FLOW_ARTIFACT_DIR/failure-missing-element.png" 2>/dev/null || true
+  exit 1
+fi
+
+log "Smoke test passed."

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

@@ -0,0 +1,38 @@
+{
+  "id": "rocketsim",
+  "stageId": "rocketsim-flows",
+  "verificationStages": [
+    "build",
+    "unit-tests",
+    "lint",
+    "rocketsim-flows"
+  ],
+  "stage": {
+    "id": "rocketsim-flows",
+    "kind": "test",
+    "description": "RocketSim user-flow validation (reusable bash flows against the running app)",
+    "script": "stages/rocketsim-flows.sh",
+    "requiresAgentId": true,
+    "artifacts": [
+      {
+        "path": ".har/artifacts/rocketsim-flows",
+        "kind": "directory",
+        "description": "Screenshots, per-flow results, and run summary"
+      }
+    ]
+  },
+  "files": [
+    { "src": ".har/stages/rocketsim-flows.sh", "dest": ".har/stages/rocketsim-flows.sh", "executable": true },
+    { "src": ".har/stages/ROCKETSIM.md",       "dest": ".har/stages/ROCKETSIM.md" },
+    { "src": "flows/README.md",                "dest": "flows/README.md" },
+    { "src": "flows/example-smoke.sh",         "dest": "flows/example-smoke.sh", "executable": true }
+  ],
+  "nextSteps": [
+    "rocketsim doctor",
+    "./.har/launch.sh 1",
+    "Build and install your app on the simulator",
+    "./.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"
+  ]
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@osfactory/har",
+  "version": "0.1.1",
+  "description": "LLM-powered CLI for reproducible agent development environments",
+  "keywords": [
+    "har",
+    "cli",
+    "mcp",
+    "agent",
+    "harness",
+    "llm",
+    "devops"
+  ],
+  "bin": {
+    "har": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "control/docker-compose.yml",
+    "control/docker-compose.build.yml"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node20 --outfile=dist/index.js --banner:js='#!/usr/bin/env node' && rm -rf dist/templates dist/prompts && cp -r src/templates dist/templates && mkdir -p dist/prompts && cp src/llm/prompts/*.md dist/prompts/",
+    "dev": "tsx src/index.ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build",
+    "release": "semantic-release"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.27.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^5.3.0",
+    "inquirer": "^10.1.2",
+    "js-yaml": "^4.1.0",
+    "ora": "^8.0.1",
+    "yargs": "^17.7.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.7",
+    "@types/jest": "^29.5.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.5.0",
+    "@types/yargs": "^17.0.33",
+    "@typescript-eslint/eslint-plugin": "^8.62.0",
+    "@typescript-eslint/parser": "^8.62.0",
+    "esbuild": "^0.23.0",
+    "eslint": "^8.57.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "jest": "^29.7.0",
+    "semantic-release": "^24.2.3",
+    "ts-jest": "^29.2.4",
+    "tsx": "^4.17.0",
+    "typescript": "^5.5.4"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/os-factory/har"
+  },
+  "homepage": "https://github.com/os-factory/har#readme",
+  "bugs": "https://github.com/os-factory/har/issues",
+  "author": "Antoine Frau",
+  "license": "AGPL-3.0-only",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}