https://github.com/rogerchappel/runcard
Generate deterministic local run cards so developers and agents know how to install, test, build, and smoke a repo.
https://github.com/rogerchappel/runcard
agentic-workflows cli developer-tools local-first runbook typescript
Last synced: about 1 month ago
JSON representation
Generate deterministic local run cards so developers and agents know how to install, test, build, and smoke a repo.
- Host: GitHub
- URL: https://github.com/rogerchappel/runcard
- Owner: rogerchappel
- License: mit
- Created: 2026-05-28T00:02:44.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-30T08:41:16.000Z (about 2 months ago)
- Last Synced: 2026-05-30T10:19:56.470Z (about 2 months ago)
- Topics: agentic-workflows, cli, developer-tools, local-first, runbook, typescript
- Language: TypeScript
- Size: 33.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# runcard
Generate deterministic local run cards for repositories.
`runcard scan` inspects repository files, normalizes the likely install/check/test/build/smoke/package commands, and writes a compact handoff for humans and coding agents. It does not run project commands during a scan.
## Install
```sh
npm install -g runcard
```
For local development in this repository:
```sh
npm ci
npm run build
node dist/cli.js scan --fixture node-cli --out .tmp/example --json .tmp/example/run-card.json
```
## Use
Scan the current repository and write `RUN_CARD.md`:
```sh
runcard scan
```
Write both markdown and JSON to a chosen output directory:
```sh
runcard scan --root /path/to/repo --out /path/to/repo/.runcard --json /path/to/repo/.runcard/run-card.json
```
Smoke the bundled Node fixture:
```sh
runcard scan --fixture node-cli --out .tmp/smoke --json .tmp/smoke/run-card.json
```
## What It Detects
- Node: `package.json`, package manager lockfiles, npm/pnpm/yarn/bun scripts.
- Python: `pyproject.toml`, `requirements.txt`, `tox.ini`, `pytest.ini`, `noxfile.py`, ruff and pytest hints.
- Rust: `Cargo.toml`, `Cargo.lock`, `cargo check`, `cargo test`.
- Go: `go.mod`, `go.sum`, `go test ./...`, `go build ./...`.
- Make: public Makefile targets.
- Shell: `.sh` files and scripts under `scripts/`.
Commands are ranked into `install`, `check`, `test`, `build`, `smoke`, `package`, `run`, and `other`. Missing test or smoke paths are flagged with suggestions because those gaps slow down agent handoffs.
## Verify
```sh
npm run release:check
```
That runs typechecking, fixture-backed tests, the fixture smoke scan, and `npm pack --dry-run`.
## Limitations
- Detection is static and deterministic; runcard does not execute repository commands while scanning.
- V1 ranking favors conventional file names and script names over deep framework inspection.
- JSON schema is versioned as `schemaVersion: 1`, but should be treated as early until the first stable release.
## Documentation
- [Product requirements](docs/PRD.md)
- [Implementation tasks](docs/TASKS.md)
- [Factory orchestration](docs/ORCHESTRATION.md)
- [Machine-readable orchestration](docs/orchestration.json)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution expectations. Changes should be small, reviewable, and verified before review.
## Security
See [SECURITY.md](SECURITY.md) for vulnerability reporting guidance.
## License
MIT