https://github.com/rogerchappel/cmdmap
Local-first CLI that maps repo commands with evidence and safety classification.
https://github.com/rogerchappel/cmdmap
agent-tools cli command-discovery developer-tools local-first makefile safety typescript
Last synced: 28 days ago
JSON representation
Local-first CLI that maps repo commands with evidence and safety classification.
- Host: GitHub
- URL: https://github.com/rogerchappel/cmdmap
- Owner: rogerchappel
- License: mit
- Created: 2026-05-11T08:38:54.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-03T23:15:56.000Z (29 days ago)
- Last Synced: 2026-06-04T02:09:52.693Z (29 days ago)
- Topics: agent-tools, cli, command-discovery, developer-tools, local-first, makefile, safety, typescript
- Language: TypeScript
- Size: 45.9 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
# cmdmap
`cmdmap` turns a repo's scattered command surfaces into an agent-safe command map: what exists, why it was found, how risky it looks, and what to run first. It is a small local-first CLI for those "new repo, no idea what is safe" moments.
## Quick start
```bash
npm install
npm run build
node dist/src/cli.js scan . --out docs/COMMANDS.md
node dist/src/cli.js scan fixtures/polyrepo --format json
node dist/src/cli.js explain "npm run release:check"
```
Once installed globally or through `npx`, use `cmdmap` directly:
```bash
cmdmap scan . --out docs/COMMANDS.md
cmdmap scan . --format json --fail-on risky
cmdmap rules
```
## What it discovers
V1 scans these local files without executing project commands:
- `package.json` scripts
- `Makefile` targets
- `Justfile` recipes
- `Taskfile.yml` / `Taskfile.yaml` tasks
- `pyproject.toml` scripts/tasks
- `Cargo.toml` default cargo workflows
- README command snippets
- files under `scripts/`
Every finding includes file and line evidence so humans and agents can inspect the source.
## Safety model
`cmdmap` is conservative by design:
- `test`, `build`, and `lint` commands are usually **safe** verification candidates.
- dev servers and unknown commands are **caution** because they may hang or have unclear side effects.
- release, publish, destructive, secret-related, and network-looking commands are **risky** by default.
- `cmdmap scan` never runs discovered commands.
- `--fail-on risky` exits with code `2` when risky commands are present, which is useful in CI.
This is heuristic static analysis, not a sandbox. Treat the output as a map, not permission.
## Configuration
Add `.cmdmaprc.json` at the repo root:
```json
{
"allowRisky": ["local-release-dry-run"],
"ignore": ["dev"],
"labels": {
"verify": ["test", "lint"]
},
"preferredSmokePath": ["lint", "test", "build"]
}
```
- `allowRisky`: known commands to downgrade after review.
- `ignore`: command names or command strings to omit.
- `labels`: custom command labels.
- `preferredSmokePath`: names or commands to prefer in the recommended path.
## Output examples
Markdown output is intended for docs and handoffs:
```bash
cmdmap scan . --out docs/COMMANDS.md
```
JSON output is stable enough for agents and CI artifacts:
```bash
cmdmap scan . --format json > command-map.json
```
Explain one command without scanning a repo:
```bash
cmdmap explain "npm publish"
```
## CI usage
```yaml
- run: npm ci
- run: npm run build
- run: node dist/src/cli.js scan . --format json --fail-on risky > command-map.json
- uses: actions/upload-artifact@v4
with:
name: command-map
path: command-map.json
```
## Limitations
- Does not execute or verify discovered commands.
- YAML/TOML parsing is intentionally lightweight in V1.
- Shell analysis is pattern-based and can miss indirect behavior.
- Cargo commands are inferred defaults from `Cargo.toml`.
- Risk allowlists should be reviewed by maintainers before automation relies on them.
## Development
```bash
npm test
npm run check
npm run build
npm run smoke
bash scripts/validate.sh
```
`fixtures/polyrepo` contains a deliberately mixed repo surface for parser and smoke coverage.