https://github.com/rogerchappel/shellgarden
Fixture-backed shell command examples with deterministic local transcripts.
https://github.com/rogerchappel/shellgarden
cli doctest fixtures shell testing transcripts typescript
Last synced: 17 days ago
JSON representation
Fixture-backed shell command examples with deterministic local transcripts.
- Host: GitHub
- URL: https://github.com/rogerchappel/shellgarden
- Owner: rogerchappel
- License: mit
- Created: 2026-05-13T09:22:59.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-25T20:05:20.000Z (18 days ago)
- Last Synced: 2026-05-25T22:09:22.156Z (18 days ago)
- Topics: cli, doctest, fixtures, shell, testing, transcripts, typescript
- Language: TypeScript
- Homepage: https://github.com/rogerchappel/shellgarden#readme
- Size: 50.8 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
# ShellGarden ðŠī
ShellGarden keeps shell examples alive. Declare commands once, point them at tiny fixture directories, and harvest deterministic transcripts you can trust in READMEs, tests, and agent handoffs.
It is local-first: no telemetry, no hidden network calls, and no mutation outside the garden path you ask it to inspect.
## Install
```bash
npm install -g shellgarden
```
For local development:
```bash
npm install
npm run build
node dist/index.js --help
```
## Quick start
```bash
shellgarden init ./demo
cd demo
shellgarden check . --update
shellgarden check .
shellgarden report . --format json
shellgarden explain .
```
A garden config looks like this:
```json
{
"version": 1,
"name": "docs-examples",
"defaultTimeoutMs": 5000,
"gardens": [
{
"id": "read-file",
"fixture": "fixtures/read-file",
"commands": [
{
"id": "print-message",
"run": "cat message.txt",
"expectExit": 0,
"transcript": "transcripts/read-file-print-message.txt"
}
]
}
]
}
```
## Commands
- `shellgarden init ` creates a small demo garden.
- `shellgarden check [--format text|json] [--update] [--dry-run] [--strict-warnings] [--filter id]` executes safe examples and compares transcripts.
- `shellgarden report --format json` emits machine-readable results.
- `shellgarden run --execute` is an explicit execution alias; without `--execute`, it dry-runs.
- `shellgarden explain ` prints the execution plan and safety notes.
- `shellgarden list ` prints a tab-separated inventory of garden commands.
## Exit codes
- `0` â garden is clean.
- `1` â findings exceeded policy, such as exit or transcript mismatch.
- `2` â invalid input/config.
## Safety model
ShellGarden runs commands only inside declared fixture directories. It rejects path escapes and blocks obviously risky commands (`sudo`, destructive `rm`, common network tools, broad chmods, and system writes). The environment is normalized with UTC locale/timezone settings and output paths are replaced with ``.
This is not a sandbox. Treat garden commands like test scripts: review them before accepting contributions. See [docs/SAFETY.md](docs/SAFETY.md) for the full boundary model.
## Examples
Try the repository fixtures:
```bash
node dist/index.js check fixtures/pass
node dist/index.js report fixtures/pass --format json
node dist/index.js explain fixtures/pass
```
The `fixtures/warn`, `fixtures/fail`, and `fixtures/unsafe` gardens document warning, policy failure, and safety-blocked cases.
## Verify
```bash
npm test
npm run check
npm run smoke
npm run package:smoke
npm run release:check
```
## Why this exists
README commands rot quietly. Agents copy stale examples loudly. ShellGarden gives small projects a way to keep examples executable, deterministic, and easy to inspect.