ghostrun-cli 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to GhostRun are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [1.0.0] — 2026-04-14
+
+### Added
+
+**Core CLI**
+- `ghostrun learn <url>` — record browser flows interactively with Playwright
+- `ghostrun run <flow>` — replay flows, with `--output json` for machine-readable results
+- `ghostrun run <flow> --report html` — generate a self-contained HTML run report
+- `ghostrun list` — list all saved flows
+- `ghostrun flow:import` / `ghostrun flow:export` — share flows as JSON files
+- `ghostrun flow:rename <id> <new-name>` — rename a saved flow
+- `ghostrun flow:clone <id>` — duplicate a flow with a new ID
+- `ghostrun flow:from-curl "<curl command>"` — generate an API test flow from a curl command
+- `ghostrun flow:from-spec <openapi.json|yaml>` — generate flows from an OpenAPI/Swagger spec
+- `ghostrun env:set` / `ghostrun env:list` — manage named environment profiles (staging, prod, etc.)
+
+**API Testing**
+- `http:request` action — supports GET, POST, PUT, PATCH, DELETE with headers and body
+- `assert:response` action — assert status codes, JSON body values, response time
+- `extract:json` action — pull values from responses into variables for downstream steps
+- `set:variable` action — define variables inline within flows
+
+**Performance Testing**
+- `ghostrun perf:run <flow>` — run load tests with configurable VUs and duration
+- `ghostrun perf:run <flow> --report html` — HTML performance report with p50/p95/p99 charts
+- `ghostrun perf:compare <run1> <run2>` — side-by-side comparison of two perf runs
+
+**MCP Server**
+- Full MCP server (`mcp-server.js`) exposing 7 tools: `list_flows`, `get_flow`, `run_flow`, `get_run_result`, `list_runs`, `delete_flow`, `get_status`
+- `run_flow` delegates to the CLI via `--output json` — always in sync, no duplication
+- Works with Claude Desktop, Cursor, and any MCP-compatible client
+
+**Templates** (installed via `ghostrun store install`)
+- `github-login` — GitHub OAuth flow
+- `checkout-flow` — e-commerce checkout automation
+- `form-submit` — generic form fill and submit
+- `api-auth-flow` — token auth + protected endpoint test
+- `api-crud` — full CRUD lifecycle (create → read → update → delete)
+- `load-baseline` — warmup → ramp → sustained → cooldown perf baseline
+
+**Misc**
+- `ghostrun monitor <url>` — continuous uptime monitoring with alerts
+- `ghostrun init` — initialize GhostRun with guided setup
+- `ghostrun store list` / `ghostrun store install` — template marketplace
+- `--visible` flag on `learn` / `run` — show the browser window during execution
+- SQLite-backed storage (`~/.ghostrun/data/ghostrun.db`)
+- AI-powered failure summaries (requires `GHOSTRUN_ANTHROPIC_API_KEY`)
+
+---
+
+## Versioning
+
+GhostRun follows [Semantic Versioning](https://semver.org/):
+- **MAJOR** — breaking changes to CLI commands or flow JSON schema
+- **MINOR** — new commands, new flow actions, new MCP tools
+- **PATCH** — bug fixes, performance improvements, doc updates

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in GhostRun a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+**Examples of behavior that contributes to a positive environment:**
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+**Examples of unacceptable behavior:**
+
+- The use of sexualized language or imagery
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct.
+
+## Scope
+
+This Code of Conduct applies within all project spaces — GitHub issues, pull requests, and discussions — and in public spaces when an individual is representing the project.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainer at [builtbysharan.com](https://builtbysharan.com). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to GhostRun
+
+Thanks for taking the time to contribute! GhostRun is an open-source project and contributions of all kinds are welcome.
+
+---
+
+## Getting started
+
+```bash
+git clone https://github.com/TechBuiltBySharan/ghostrun
+cd ghostrun
+npm install
+npm run build        # compile ghostrun.ts → ghostrun.js
+node ghostrun.js help
+```
+
+---
+
+## Project structure
+
+```
+ghostrun.ts          # Main CLI — all commands live here (~6400 lines)
+mcp-server.ts        # MCP server — delegates flow execution to ghostrun.js
+templates/           # Built-in flow templates (ghostrun store install)
+test-flows/          # Example API test flows for development
+packages/database/   # DatabaseManager (extracted from main CLI)
+landing/             # Landing page (ghostrun.builtbysharan.com)
+```
+
+The project is a single-file TypeScript CLI compiled with esbuild into `ghostrun.js`. The monorepo packages under `packages/` are stubs for a future refactor — the active code is in `ghostrun.ts`.
+
+---
+
+## How to contribute
+
+### Bug reports
+
+Open an issue with:
+- The exact command you ran
+- What you expected vs what happened
+- Your OS and Node version (`node --version`)
+- Any error output
+
+### Feature requests
+
+Open an issue describing the use case. Explain what you're trying to do, not just the feature itself.
+
+### Pull requests
+
+1. Fork the repo and create a branch: `git checkout -b fix/my-fix`
+2. Make your changes in `ghostrun.ts`
+3. Run `npm run build` to compile
+4. Test manually: `node ghostrun.js <your-command>`
+5. Open a PR with a clear description of what changed and why
+
+### Adding a flow template
+
+Templates live in `templates/` as `.flow.json` files. Copy an existing one as a starting point. They use `{{VARIABLE}}` placeholders for anything site-specific.
+
+---
+
+## Development tips
+
+```bash
+# Quick rebuild and test
+npm run build && node ghostrun.js help
+
+# Watch for changes (no watcher built in — just re-run build)
+npm run build
+
+# Run against the test API server
+node test-api-server.mjs &
+ghostrun flow:import test-flows/health-check.flow.json
+ghostrun run "API Health Check"
+```
+
+---
+
+## Code style
+
+- TypeScript, no external formatter enforced
+- Keep functions focused — one command per `async function run*()`
+- New commands need: a function, a `case` in the switch, and a help entry
+- No new runtime dependencies without discussion (bundle size matters)
+
+---
+
+## Questions?
+
+Open an issue or reach out at [builtbysharan.com](https://builtbysharan.com).