@osfactory/har 0.24.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +39 -254
  2. package/dist/index.js +446 -283
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,294 +1,79 @@
1
1
  <p align="center">
2
- <img src="logo.png" alt="har logo" width="120">
2
+ <img src="logo.png" alt="HAR logo" width="120">
3
3
  </p>
4
4
 
5
- # har — Your AI harness orchestrator
5
+ # HAR — Harnesses for coding agents
6
6
 
7
7
  [![Release](https://img.shields.io/github/v/release/os-factory/har)](https://github.com/os-factory/har/releases)
8
8
  [![CI](https://github.com/os-factory/har/actions/workflows/test.yml/badge.svg)](https://github.com/os-factory/har/actions/workflows/test.yml)
9
- [![Documentation](https://img.shields.io/badge/docs-harproject.cloud-38c976)](https://harproject.cloud/)
9
+ [![Documentation](https://img.shields.io/badge/docs-harproject.dev-38c976)](https://harproject.dev/)
10
10
 
11
- **Make any repository agent-ready without binding it to one coding agent, test runner, or hosted platform.**
11
+ **Give coding agents a real place to work.**
12
12
 
13
- HAR is an open-source CLI and MCP control plane for project-owned development harnesses. It scaffolds an editable `.har/` runtime contract so humans and MCP-capable coding agents can discover how to launch, verify, reset, inspect, and tear down a repository.
13
+ HAR is an open-source, agent-agnostic standard for building multi-agent coding workflows. It makes your repository agent-ready, so you can run a whole fleet of coding agents in parallel, with deterministic validation gates, verifiable proof, and full observability across every agent.
14
14
 
15
- HAR does not own the coding LLM and does not replace CI/CD. It gives agents a stable, machine-readable way to use the workflow your team already trusts.
16
-
17
- Planning tools decide what to build. HAR binds that durable work identity to an
18
- isolated execution attempt and verifiable evidence: runs, artifacts, telemetry,
19
- and the exact Git tree that passed.
20
-
21
- ## How It Works
22
-
23
- 1. **Project-owned harness** — `.har/` contains editable scripts, docs, environment metadata, logs, artifacts, and optional stage definitions.
24
- 2. **CLI control plane** — `har env ...` scaffolds, maintains, launches, verifies, reports status, and tears down local or self-hosted harness runs.
25
- 3. **MCP adapter** — agents use HAR MCP tools to describe the project, run generic stages, read logs, list artifacts, and inspect status without learning repo-specific shell details.
26
- 4. **Generic stages** — setup, launch, verify, test, inspect, reset, teardown, and custom stages expose normalized status, logs, durations, artifacts, and URLs.
27
- 5. **Configurable agent slots** — parallel environment limits are defined in `.har/stages.json` (`agentSlots`) and `.har/harness.env`, not by the HAR CLI.
28
- 6. **Optional stage templates** — add workflows like Playwright with `har env add-stage playwright`. They compile to generic stages (`test`, `custom`, etc.), not hardcoded HAR APIs.
29
- 7. **Durable work evidence** — optionally launch with `--work-id` so slot sessions, retries, cost, and exact-tree validations remain attributable after teardown.
30
-
31
- ![Mission Control Factory overview](docs/public/assets/factory-overview.png)
15
+ Works with **Claude Code** · **Cursor** · **Codex** · any MCP agent.
32
16
 
33
17
  ## Install
34
18
 
35
- **From npm:**
36
-
37
19
  ```bash
38
- npm install -g @osfactory/har@latest
20
+ npm install -g @osfactory/har
39
21
  ```
40
22
 
41
- **From source:**
42
-
43
- ```bash
44
- git clone https://github.com/os-factory/har har-project && cd har-project
45
- npm install && npm run build && npm link
46
- ```
47
-
48
- Read the [full documentation](https://harproject.cloud/). See [AGENT.md](./AGENT.md) for architecture and coding-agent guidance, and [CONTRIBUTING.md](./CONTRIBUTING.md) for the full development workflow, testing on sample projects, and project layout. To report security issues, see [SECURITY.md](./SECURITY.md).
49
-
50
- ## Harness profiles
51
-
52
- `har env init` scaffolds `.har/` from a boilerplate profile. Pick the one that matches what agents need to run — you only choose this once at init time.
53
-
54
- | Profile | Best for | What you get |
55
- |---------|----------|--------------|
56
- | `default` | Web apps (Next.js, Rails, Django, etc.) | Docker Compose for shared infra, PM2 for the primary app, per-slot ports and preview URLs |
57
- | `cli` | CLI tools, libraries, npm packages | No PM2 or port wiring — agents run project commands in an isolated git worktree; optional Docker for databases |
58
- | `ios` | iOS / Swift mobile apps | xcodebuild + iOS Simulator; configure scheme, project, and simulator in `harness.env` |
59
-
60
- ```bash
61
- # Web app (default — omit --profile)
62
- cd my-web-app && har env init
63
-
64
- # CLI tool or library
65
- cd my-cli && har env init --profile cli
66
-
67
- # iOS app
68
- cd MyApp && har env init --profile ios
69
- har env add-stage rocketsim # optional: UI flow validation on the simulator
70
- ```
71
-
72
- After init, paste the adaptation prompt into your coding agent (interactive terminals offer a clipboard copy; also saved to `.har/ADAPT-PROMPT.md`) to tailor scripts to your stack. For built-in Claude adaptation: `har env init --auto` (requires `ANTHROPIC_API_KEY`).
73
-
74
- Optional stage templates depend on the profile: `har env add-stage playwright` for browser E2E on web apps, `har env add-stage rocketsim` for simulator user-flow checks on iOS.
75
-
76
- ## Quick start
23
+ ## Get started
77
24
 
78
25
  ```bash
79
26
  cd my-app
80
- har env init # or --profile cli / --profile ios
81
-
82
- # Paste the printed prompt into your coding agent to adapt .har/ and AGENT.md
83
- git add .har/ AGENT.md
84
- git commit -m "Add agent harness"
85
-
86
- har env launch 1
87
- har env verify 1
88
- ```
89
-
90
- To correlate execution with an issue or ticket:
91
-
92
- ```bash
93
- har env launch 1 --work-id "github:acme/widget#123" --work-source github
94
- har env complete 1
95
- ```
96
-
97
- Shell fallback when the CLI is not installed: `./.har/setup-infra.sh`, `./.har/launch.sh 1`, `./.har/verify.sh 1`.
98
-
99
- See [Harness profiles](#harness-profiles) above if your repo is a CLI/library or iOS app rather than a web app.
100
-
101
- ## Agent skills (/setup-har, /har-wt, /har-maintain)
102
-
103
- `har env init` can scaffold **project-owned skills/commands** for coding agents, so the har workflow is one slash command away for every teammate who clones the repo:
104
-
105
- | Skill | Who invokes it | What it does |
106
- |-------|----------------|--------------|
107
- | `/setup-har` | You, once | Installs har if missing, picks a profile, runs `har env init`, performs the adaptation prompt itself, proves launch + verify, commits |
108
- | `/har-wt` | The agent, on every coding task | Launches a harness slot, does all edits in the session worktree (never the main checkout), verifies through the harness |
109
- | `/har-maintain` | You, when the harness drifts | Runs `har env maintain`, applies the adaptation, finalizes and re-verifies |
110
-
111
- Targets are auto-detected at `init`/`maintain` (or forced with `--agents claude,cursor,codex`); you can also manage them standalone:
112
-
113
- ```bash
114
- har agents install --claude --cursor # .claude/skills/ + .cursor/commands/ (committed to the repo)
115
- har agents install --codex # ~/.codex/prompts/ (global — Codex has no per-repo prompts)
116
- har agents remove --claude
117
- ```
118
-
119
- Scaffolded files carry a `managed by har` header and are refreshed by `har env maintain`; files you edit by hand are left alone.
120
-
121
- **Optional enforcement (Claude Code):** make `/har-wt` self-triggering instead of memory-dependent —
122
-
123
- ```bash
124
- har hooks install --claude
125
- ```
126
-
127
- installs a `PreToolUse` guard (`.har/hooks/claude-worktree-guard.sh` + an entry in `.claude/settings.json`) that blocks `Edit`/`Write` in the **main checkout** of a har repo and points the agent to `/har-wt`. Edits inside session worktrees pass through. Remove with `har hooks uninstall --claude`; humans can bypass with `HAR_SKIP_WT_GUARD=1`.
128
-
129
- ## Repo layout after init
130
-
131
- ```
132
- my-app/
133
- ├── AGENT.md # Short pointer for coding agents (you approve this)
134
- └── .har/
135
- ├── README.md # Full harness documentation (maintained by har)
136
- ├── manifest.json # Generator metadata
137
- ├── stages.json # Optional generic stage registry
138
- ├── setup-infra.sh
139
- ├── launch.sh
140
- ├── verify.sh
141
- ├── agent-cli.sh
142
- ├── logs/
143
- ├── artifacts/
144
- ├── harness.env
145
- ├── CLAUDE.agent.md
146
- └── ...
147
- ```
148
-
149
- ## Generic Stage Contract
150
-
151
- HAR stages are project-defined operations with stable identifiers and normalized results. A stage can be as simple as `verify` or as specific as `browser-e2e`, `migration-check`, `accessibility`, or `load-smoke`.
152
-
153
- The important boundary is that HAR runs and reports stages generically. It does not need a special Playwright, migration, accessibility, or load-test API in the core product. The authoring contract (command vs script stages, the script contract, how `verificationStages` controls `verify --full`) ships into every harness as `.har/STAGES.md`.
154
-
155
- ### Custom stages
156
-
157
- Register the project's real checks so they run in `verify --full` and surface to every agent:
158
-
159
- ```bash
160
- har env add-stage unit-tests --custom --kind test --command "npm test" --verification
161
- har env add-stage db-integrity --custom --script # scaffolds .har/stages/db-integrity.sh
162
- ```
163
-
164
- ### Playwright (optional)
165
-
166
- ```bash
167
- har env init
168
- har env add-stage playwright # registers browser-e2e + scaffolds tests/
169
- npm install && npx playwright install
170
- ./.har/launch.sh 1
171
- ./.har/stages/browser-e2e.sh 1
27
+ har env init # scaffold .har/ and print a prompt for your coding agent
28
+ har env launch 1 # isolated worktree + running stack for agent slot 1
29
+ har env verify 1 --full # run the project's real checks, record what passed
172
30
  ```
173
31
 
174
- See `.har/stages/PLAYWRIGHT.md` in the target repo after applying the template.
32
+ That’s it. Your agents discover launch, verify, and teardown through the project’s `.har/` contract — not by guessing shell commands.
175
33
 
176
- ## CLI commands
34
+ Full walkthrough: [Quick start](https://harproject.dev/docs/getting-started/quick-start/).
177
35
 
178
- | Command | Description |
179
- |---------|-------------|
180
- | `har env init` | Scaffold `.har/` + print coding-agent adaptation prompt |
181
- | `har env add-stage playwright` | Add a stage template (`playwright`, `rocketsim`; `--list` shows all) |
182
- | `har env add-stage <id> --custom` | Register a project-specific stage (`--command "npm test"` or `--script`) |
183
- | `har env maintain` | Validate harness + print maintenance prompt |
184
- | `har env launch 1` | Launch agent slot 1 |
185
- | `har env verify 1` | Run verification |
186
- | `har env status` | Show status for all agent slots (`--json` for structured output) |
187
- | `har env runs list` | List persisted run history (`--json`) |
188
- | `har env runs get <runId>` | Fetch one run record |
189
- | `har env teardown 1` | Tear down agent slot 1 |
190
- | `har agents install` | Scaffold agent skills (`/setup-har`, `/har-wt`, `/har-maintain`) for Claude Code / Cursor / Codex |
191
- | `har agents remove` | Remove har-managed agent skill files |
192
- | `har preferences configure` | Select user defaults for rules, skills, and commit-gate onboarding |
193
- | `har hooks install` | Install the git commit gate (`--claude` for the Claude Code worktree guard) |
194
- | `har control up` | Start local Mission Control dashboard (Docker Compose) |
195
- | `har control register` | Register a repo with Mission Control |
196
- | `har control sync` | Sync runs + slot status to Mission Control |
197
- | `har control watch` | Continuously sync registered repos |
198
- | `har mcp` | Start the HAR MCP server (stdio) |
36
+ ## How it works
199
37
 
200
- Options: `--force`, `--auto` (built-in Claude adaptation), `--smoke`, `--yes`
201
- (accept recommended onboarding actions), `--verbose`, `--profile <default|cli|ios>`
38
+ 1. **Discover** — The agent reads one stable interface instead of guessing project-specific shell commands.
39
+ 2. **Isolate** — Every task gets a clean slot: dedicated session worktree, ports, and local services.
40
+ 3. **Build** — The agent edits inside the harness, without touching the main checkout.
41
+ 4. **Verify** — Project checks become a deterministic pipeline with normalized status, logs, and artifacts.
42
+ 5. **Hand off** — Reviewers get a branch plus evidence: what ran and the exact validated tree.
202
43
 
203
- ## MCP Surface
44
+ ## Why HAR
204
45
 
205
- Start the server from a repository (or pass `repo` on each tool call):
46
+ - **Project-owned** — The workflow lives with the code, not inside a vendor dashboard.
47
+ - **Agent-agnostic** — One stable contract for CLI users, MCP agents, and future tools.
48
+ - **Evidence-first** — Every run can leave logs, artifacts, status, and a validated tree hash.
206
49
 
207
- ```bash
208
- har mcp
209
- ```
210
-
211
- Example Cursor MCP config:
212
-
213
- ```json
214
- {
215
- "mcpServers": {
216
- "har": {
217
- "command": "har",
218
- "args": ["mcp", "--repo", "/path/to/my-app"]
219
- }
220
- }
221
- }
222
- ```
50
+ ## What HAR is not
223
51
 
224
- Core tools (generic — no stack-specific operations like `run_playwright`):
52
+ - A coding model
53
+ - A replacement for CI/CD
54
+ - A new test runner
55
+ - A hosted platform lock-in
225
56
 
226
- | Tool | Purpose |
227
- |------|---------|
228
- | `har_describe_project` | Manifest, scripts, stages, agent slot limits, stack hints |
229
- | `har_init_harness` | Scaffold `.har/` (optionally skip LLM) |
230
- | `har_launch_environment` | Launch slot; return preview URLs |
231
- | `har_run_stage` | Run one stage by id or kind |
232
- | `har_run_verification` | Run the verification pipeline |
233
- | `har_get_status` | Slot/process status |
234
- | `har_get_logs` | Recent logs for a slot |
235
- | `har_teardown_environment` | Stop a slot |
236
- | `har_list_artifacts` | List files under `.har/artifacts/` |
237
- | `har_list_runs` | List persisted run records from `.har/runs/` |
238
- | `har_get_run` | Fetch one run record by `runId` |
239
-
240
- ## Mission Control (local dashboard)
241
-
242
- Free OSS dashboard for observing harness runs, worktrees, and agent slots on your machine:
243
-
244
- ```bash
245
- har control up # pulls theosfactory/har-control:<cli-version> + Postgres at http://localhost:3847
246
- har env init # remembers the repo for sync when Control starts
247
- har control sync # push runs + slot status
248
- ```
57
+ HAR coordinates the work around the model so agents can focus on the code — and reviewers can trust the result.
249
58
 
250
- **Do not run `har control up` and `cd control && har env launch 1` on port 3847 at the same time.** Use the harness for agent dev (hot reload); use `har control up` for the packaged Docker dashboard. Preflight on each side detects the conflict and suggests `har control down` or an alternate harness slot/port.
59
+ ## Documentation
251
60
 
252
- See [`control/AGENT.md`](./control/AGENT.md) for dashboard development. Hosted team features are **HAR Cloud** (paid).
61
+ Everything beyond install and first commands lives at **[https://harproject.dev/](https://harproject.dev/)**:
253
62
 
254
- Agents can still use GitHub, Linear, observability, and other MCP servers directly. HAR focuses on the repository harness and run state.
63
+ - [Introduction](https://harproject.dev/docs/getting-started/introduction/) · [Core concepts](https://harproject.dev/docs/getting-started/concepts/)
64
+ - [CLI reference](https://harproject.dev/docs/reference/cli/) · [MCP tools](https://harproject.dev/docs/reference/mcp/)
65
+ - [Mission Control](https://harproject.dev/docs/guides/mission-control/) · [Architecture](https://harproject.dev/docs/project/architecture/)
255
66
 
256
- ## HAR Cloud
67
+ ## Contributing
257
68
 
258
- The open-source CLI and MCP harness are the core. Paid HAR Cloud should add hosted operational value that teams do not want to build themselves:
259
-
260
- - Hosted branch previews and remote harness runs
261
- - Run history, logs, artifacts, screenshots, traces, and result timelines
262
- - QA handoff, approvals, and shareable preview links
263
- - Slack, Linear, GitHub, and observability integrations
264
- - Team dashboards for status, policy, audit trails, and cost controls
265
-
266
- HAR Cloud should coordinate and observe the factory. The repo-owned `.har/` contract remains portable.
267
-
268
- ## For Coding Agents
269
-
270
- Agents should read **`AGENT.md`** first, then **`.har/README.md`**. Prefer **HAR MCP tools** (in Cursor) or **`har env …`** for launch, verify, and teardown — they persist run history. Use `./.har/*.sh` only when the CLI is not installed.
69
+ See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup, the dogfood harness loop, and architecture. Coding agents working on this repo should start with [AGENT.md](./AGENT.md). Maintainer release process: [RELEASING.md](./RELEASING.md).
271
70
 
272
71
  ## License
273
72
 
274
- **Dual licensing.** This project uses different licenses for code, documentation, and branding.
275
-
276
- | Material | License | Details |
277
- |----------|---------|---------|
278
- | Software (CLI, MCP server, Mission Control code, tooling) | [AGPL-3.0-only](./LICENSE) | Copyleft; network use (SaaS) triggers source-offer obligations |
279
- | Documentation and written guides | [CC BY-SA 4.0](./DOCUMENTATION-LICENSE.md) | Share and adapt with attribution and share-alike |
280
- | Name, logo, trademarks | All rights reserved | See [TRADEMARK.md](./TRADEMARK.md) |
73
+ Software is [AGPL-3.0-only](./LICENSE). Documentation is [CC BY-SA 4.0](./DOCUMENTATION-LICENSE.md). Trademarks are reserved — see [TRADEMARK.md](./TRADEMARK.md). Commercial use without AGPL obligations needs a separate agreement — see [LICENSE-COMMERCIAL.md](./LICENSE-COMMERCIAL.md).
281
74
 
282
- **Commercial use without AGPL obligations** — closed-source products, managed hosting, training/certification programs, trademark use, or other rights beyond the public licenses require a separate agreement. See [LICENSE-COMMERCIAL.md](./LICENSE-COMMERCIAL.md).
283
-
284
- Copyright © 2026 [Antoine Frau](https://github.com/antoineFrau/har).
285
-
286
- Contributors agree to the [Contributor License Agreement](./CLA.md).
287
-
288
- **Note:** Earlier releases may have been published under MIT. Those versions remain under MIT; new releases from this license change forward are under AGPL-3.0-only unless you obtain a commercial license.
75
+ Copyright © 2026 [Antoine Frau](https://github.com/antoineFrau). Contributors agree to the [CLA](./CLA.md).
289
76
 
290
77
  ## Security
291
78
 
292
- Report vulnerabilities via [SECURITY.md](./SECURITY.md) (GitHub private advisory preferred).
293
-
294
- Inspired by [Lightdash's agent-harness](https://github.com/lightdash/lightdash/tree/main/agent-harness).
79
+ Report vulnerabilities via [SECURITY.md](./SECURITY.md).