@osfactory/har-plugin

Boilerplate for HAR verification plugins — installable bundles that register stages coding agents must pass.

Use this repository as a GitHub template, publish it to npm, or install it straight from git. Consumers never learn a new MCP tool: plugins only add stages to .har/stages.json.

# Try the example (after you have a harness in some repo)
har env init --profile cli --yes   # if needed
har env add-plugin @osfactory/har-plugin --skip-ci
# or from a checkout:
har env add-plugin /path/to/har-plugin --skip-ci

For coding agents: AGENTS.md (what fits a plugin + how to build one) · CLAUDE.md
Full authoring guide: docs/AUTHORING.md
HAR plugins docs: https://harproject.dev/docs/guides/plugins/#publish-your-own-plugin

---

What is a HAR plugin?

Plugin	Files + template.manifest.json applied once with har env add-plugin
Stage	What runs on har env verify / MCP har_run_stage

HAR itself stays a closed control plane. Your plugin ships scaffolding (scripts, config, optional CI) and registers generic stage kinds (test, verify, …).

Quick start (create your own)

1. Use this template (GitHub → Use this template) or clone the repo.

2. Rename the example — see the table in docs/AUTHORING.md.

3. Implement .har/stages/<your-stage>.sh (keep the JSON-on-stdout contract).

4. Validate: npm run check-manifest, then har env add-plugin . on a fixture repo.

5. Publish to npm or push to GitHub; document:

   har env add-plugin @your-org/your-plugin
   har env add-plugin github:your-org/your-plugin

Package layout

har-plugin/
├── AGENTS.md                 # agent guide — fit, examples, checklist
├── CLAUDE.md                 # points agents at AGENTS.md
├── package.json              # npm identity (@osfactory/har-plugin)
├── template.manifest.json    # required — what add-plugin applies
├── .har/stages/
│   ├── example-check.sh      # stage script (executable)
│   └── EXAMPLE.md            # copied into target repos as docsPath
├── .github/workflows/
│   └── example.yml           # optional CI (skip with --skip-ci)
├── docs/AUTHORING.md         # how to customize and publish
└── scripts/check-manifest.mjs

template.manifest.json is the contract HAR validates. Prefer stages: [...] for one or more stages. Optional merge.package.json can add npm scripts/deps.

Install channels

Spec	Example
Bundled with HAR CLI	har env add-plugin playwright (after upstream merge)
npm	har env add-plugin @osfactory/har-plugin
Git	har env add-plugin github:os-factory/har-plugin
Local path	har env add-plugin ./har-plugin

Resolution order: path → git → bundled id → npm. The package root must contain template.manifest.json.

Example stage behaviour

The shipped example-check stage always passes after logging a placeholder message. Replace it before publishing a real plugin. Artifacts go under .har/artifacts/example-check/.

Related

• os-factory/har — HAR CLI / MCP
• Plugin marketplace
• Stages guide — custom stages without a plugin

License

MIT