@osfactory/har 0.8.0 → 0.10.0

package/dist/templates/agent-skills/har-maintain.md

@@ -0,0 +1,34 @@
+# Maintain / repair the har harness
+
+The `.har/` harness has drifted from the repository (stack changed, launch/verify broken, stale scripts or docs). Bring it back in sync — do every step yourself.
+
+## 1. Run maintain
+
+```bash
+har env maintain
+```
+
+This compares the harness against the current templates and repository, refreshes har-owned files, and prints an adaptation prompt (also written to `.har/ADAPT-PROMPT.md`).
+
+## 2. Perform the adaptation yourself
+
+Read `.har/ADAPT-PROMPT.md` and execute its instructions now, in this session: reconcile `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENT.md` with the repository's current stack, ports, and commands. Preserve intentional project-specific customizations — fix drift, don't blindly reset.
+
+## 3. Finalize and prove it works
+
+```bash
+har env maintain --finalize
+har env launch 1
+har env verify 1 --full
+```
+
+Fix the harness until launch and full verify pass. Tear down afterwards if the slot isn't needed (`har env teardown 1`).
+
+## 4. Commit
+
+After the user confirms:
+
+```bash
+git add .har/ AGENT.md
+git commit -m "chore: maintain har harness"
+```

package/dist/templates/agent-skills/har-wt.md

@@ -0,0 +1,47 @@
+# Work in a har worktree slot
+
+This repository uses a `.har/` harness. All code changes happen inside a **har session worktree**, never in the main checkout. Follow this flow for the current task.
+
+Use har's worktree, not your own: do not create git worktrees yourself and do not use any built-in worktree/isolation feature of your agent harness — the har slot already provides the worktree plus ports, env, and lifecycle.
+
+## 1. Pick a slot
+
+```bash
+har env status        # or ./.har/agent-cli.sh 1 status
+```
+
+- One slot ≈ one task. If slot 1 is occupied by unrelated work, use slot 2+ (limit: `agentSlots` in `.har/stages.json`).
+- Never replace an occupied slot (`--replace`/`--force`) without the user explicitly approving it.
+
+## 2. Launch — BEFORE editing any file
+
+```bash
+har env launch <id>   # or ./.har/launch.sh <id>
+```
+
+Launch creates a fresh session worktree from HEAD and prints its **work dir** (also recorded in `.har/slots/agent-<id>.json`, path like `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>`). If a previous launch failed partway, retry with `--resume` instead of replacing.
+
+## 3. Do ALL work in the work dir
+
+- `cd` into the work dir; every read-modify-write of project files happens there.
+- The main checkout must stay clean (`git status` there shows no changes from you).
+- Edits hot-reload in the running slot; use `./.har/agent-cli.sh <id> restart` if a change doesn't take.
+- Commit early and often on the session branch — teardown keeps the branch, not uncommitted work.
+- After launch, read `.har/CLAUDE.agent.md` in the worktree for slot URLs and the definition of done.
+
+## 4. Verify through the harness
+
+```bash
+har env verify <id>          # fast loop while iterating
+har env verify <id> --full   # required before declaring work done
+```
+
+Do not substitute ad-hoc test commands for harness verification. Any edit after a full verify — even one character — requires re-running it.
+
+## 5. Finish
+
+```bash
+har env complete <id>   # full verify + validation record + teardown, keeps the session branch
+```
+
+Report to the user: verification result, the session branch name (so they can push / open a PR), and the slot preview URLs if the app is running.

package/dist/templates/agent-skills/setup-har.md

@@ -0,0 +1,59 @@
+# Set up the har harness in this repository
+
+You are onboarding this repository onto har (an agent-harness orchestrator). Do every step yourself — do not ask the user to paste prompts or run commands unless a step needs their approval.
+
+## 1. Ensure the har CLI is installed
+
+```bash
+har --version
+```
+
+If missing, install it and re-check:
+
+```bash
+npm install -g @osfactory/har
+```
+
+## 2. Pick a harness profile
+
+Inspect the repository and choose the profile that matches how agents will run it:
+
+| Profile | Use when |
+|---------|----------|
+| `default` | Web app / server with a long-running process (Next.js, Rails, Django, APIs) |
+| `cli` | CLI tool, library, or npm package — no dev server to keep alive |
+| `ios` | iOS / Swift app built with xcodebuild + Simulator |
+
+Tell the user which profile you picked and why before continuing.
+
+## 3. Initialize the harness
+
+```bash
+har env init --profile <profile>   # omit --profile for default
+```
+
+If `.har/` already exists, stop and suggest `/har-maintain` instead.
+
+## 4. Perform the adaptation yourself
+
+`har env init` prints an adaptation prompt and writes it to `.har/ADAPT-PROMPT.md`. Read that file and **execute its instructions yourself, now, in this session** — tailor `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENT.md` to this repository's real stack, ports, and commands. Do not use `--auto` and do not ask the user to paste anything.
+
+## 5. Prove the harness works
+
+```bash
+har env launch 1
+har env verify 1
+```
+
+Fix the harness scripts until both pass. Then tear down or keep the slot as the user prefers (`har env teardown 1` keeps the branch).
+
+## 6. Commit
+
+After the user confirms, commit the harness:
+
+```bash
+git add .har/ AGENT.md CLAUDE.md .claude/ .cursor/ 2>/dev/null || git add .har/ AGENT.md
+git commit -m "chore: add har agent harness"
+```
+
+Optionally recommend `har hooks install` (commit gate) and `har hooks install --claude` (worktree guard for Claude Code).

package/dist/templates/agent-skills/skills.manifest.json

@@ -0,0 +1,48 @@
+{
+  "version": 1,
+  "skills": [
+    {
+      "id": "setup-har",
+      "body": "setup-har.md",
+      "title": "Set up the har harness in this repository",
+      "claude": {
+        "frontmatter": {
+          "name": "setup-har",
+          "description": "Install the har CLI and scaffold the .har/ agent harness in this repository (init, adapt, launch, verify, commit). User-invoked onboarding.",
+          "disable-model-invocation": true,
+          "allowed-tools": "Bash(har *) Bash(npm *) Bash(git *) Read Grep Glob Edit Write"
+        }
+      },
+      "cursor": { "command": true },
+      "codex": { "promptName": "har-setup" }
+    },
+    {
+      "id": "har-wt",
+      "body": "har-wt.md",
+      "title": "Work in a har worktree slot",
+      "claude": {
+        "frontmatter": {
+          "name": "har-wt",
+          "description": "Use BEFORE making any code change in this repository. Launches a har harness slot, which creates an isolated git session worktree — all edits must happen there, never in the main checkout — and verifies the work through the harness when done."
+        }
+      },
+      "cursor": { "command": true },
+      "codex": { "promptName": "har-wt" }
+    },
+    {
+      "id": "har-maintain",
+      "body": "har-maintain.md",
+      "title": "Maintain / repair the har harness",
+      "claude": {
+        "frontmatter": {
+          "name": "har-maintain",
+          "description": "Repair or update the .har/ harness when it has drifted from the repository (stack changes, broken launch/verify, stale scripts). Runs har env maintain and applies the adaptation.",
+          "disable-model-invocation": true,
+          "allowed-tools": "Bash(har *) Bash(git *) Read Grep Glob Edit Write"
+        }
+      },
+      "cursor": { "command": true },
+      "codex": { "promptName": "har-maintain" }
+    }
+  ]
+}

package/dist/templates/claude-worktree-guard.sh.template

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Managed by `har hooks install --claude` — do not edit; reinstall to update.
+# Claude Code PreToolUse guard: block file edits in the MAIN checkout of a har repo.
+# Edits belong in a har session worktree (launch one with /har-wt). Fails open on errors.
+
+[ "$HAR_SKIP_WT_GUARD" = "1" ] && exit 0
+
+input="$(cat 2>/dev/null)" || exit 0
+[ -n "$input" ] || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+file_path="$(printf '%s' "$input" | node -e '
+let d = "";
+process.stdin.on("data", (c) => (d += c)).on("end", () => {
+  try {
+    const t = JSON.parse(d).tool_input || {};
+    process.stdout.write(t.file_path || t.notebook_path || "");
+  } catch {}
+});' 2>/dev/null)" || exit 0
+[ -n "$file_path" ] || exit 0
+
+dir="$(dirname "$file_path")"
+while [ ! -d "$dir" ] && [ "$dir" != "/" ]; do dir="$(dirname "$dir")"; done
+toplevel="$(cd "$dir" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[ -n "$toplevel" ] || exit 0
+
+# Only guard har-managed repos.
+[ -f "$toplevel/.har/manifest.json" ] || [ -f "$toplevel/.har/stages.json" ] || exit 0
+
+# Linked worktrees (git-dir != common-dir) are session worktrees — allowed.
+gitdir="$(cd "$toplevel" && git rev-parse --absolute-git-dir 2>/dev/null)"
+commondir="$(cd "$toplevel" && git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
+if [ -n "$gitdir" ] && [ -n "$commondir" ] && [ "$gitdir" != "$commondir" ]; then
+  exit 0
+fi
+
+echo "har: edit blocked — $file_path is in the MAIN checkout of a har-managed repo. Run /har-wt to launch a harness slot and make all edits in its session worktree. (Human bypass: HAR_SKIP_WT_GUARD=1)" >&2
+exit 2

package/dist/templates/stage-templates/playwright/.har/stages/browser-e2e.sh

@@ -43,7 +43,7 @@ mkdir -p "$ARTIFACT_DIR"
 log "Running Playwright against $BASE_URL (API: $API_URL)"
 log "Work dir: $WORK_DIR"
 
-START_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+START_TOTAL=$(now_ms)
 
 set +e
 cd "$WORK_DIR"
@@ -51,7 +51,7 @@ PW_OUTPUT=$(npx playwright test 2>&1)
 PW_EXIT=$?
 set -e
 
-END_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+END_TOTAL=$(now_ms)
 TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
 
 echo "$PW_OUTPUT" >&2

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

@@ -78,7 +78,11 @@ if [ -n "$FLOW_FILTER" ]; then
     exit 1
   fi
 else
-  mapfile -t FLOW_SCRIPTS < <(find "$FLOWS_DIR" -maxdepth 1 -name "*.sh" ! -name ".*" | sort)
+  # while-read instead of mapfile: stock macOS bash is 3.2, which lacks mapfile.
+  FLOW_SCRIPTS=()
+  while IFS= read -r flow_script; do
+    FLOW_SCRIPTS+=("$flow_script")
+  done < <(find "$FLOWS_DIR" -maxdepth 1 -name "*.sh" ! -name ".*" | sort)
 fi
 
 if [ ${#FLOW_SCRIPTS[@]} -eq 0 ]; then
@@ -103,7 +107,7 @@ mkdir -p "$ARTIFACT_DIR"
 log "Running ${#FLOW_SCRIPTS[@]} flow(s) against simulator..."
 
 OVERALL_PASS=true
-START_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+START_TOTAL=$(now_ms)
 FLOW_RESULTS="[]"
 
 for FLOW_SCRIPT in "${FLOW_SCRIPTS[@]}"; do
@@ -113,7 +117,7 @@ for FLOW_SCRIPT in "${FLOW_SCRIPTS[@]}"; do
   FLOW_ARTIFACT_DIR="$ARTIFACT_DIR/$FLOW_NAME"
   mkdir -p "$FLOW_ARTIFACT_DIR"
 
-  FLOW_START=$(date +%s%3N 2>/dev/null || echo "0")
+  FLOW_START=$(now_ms)
 
   set +e
   FLOW_OUTPUT=$(
@@ -128,7 +132,7 @@ for FLOW_SCRIPT in "${FLOW_SCRIPTS[@]}"; do
   FLOW_EXIT=$?
   set -e
 
-  FLOW_END=$(date +%s%3N 2>/dev/null || echo "0")
+  FLOW_END=$(now_ms)
   FLOW_MS=$(( FLOW_END - FLOW_START ))
 
   if [ "$FLOW_EXIT" = "0" ]; then
@@ -162,7 +166,7 @@ process.stdout.write(JSON.stringify(arr));
 " 2>/dev/null || echo "$FLOW_RESULTS")
 done
 
-END_TOTAL=$(date +%s%3N 2>/dev/null || echo "0")
+END_TOTAL=$(now_ms)
 TOTAL_MS=$(( END_TOTAL - START_TOTAL ))
 
 # ── Output ────────────────────────────────────────────────────────────────────

package/package.json

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