readme-snippet-runner

KO | EN

gitlite — search

#hacktoberfest #ai #llm #go #machine-learning #rust #docker #nodejs #macos #java #awesome #awesome-list #mcp #openai

readme-snippet-runner

(★ 10)

Maintainer tooling for teams whose README copy-paste snippets drift from reality: it extracts fenced `js`/`ts` blocks...

readme-snippet-runner Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# readme-snippet-runner

Maintainer tooling for teams whose README copy-paste snippets drift from reality: it extracts fenced `js`/`ts` blocks and actually runs them locally or in CI—no Docker sandbox required—unlike heavier doc-test harnesses (mdsh, rundoc, full containerized snippet runners) that fight Windows paths or pull a VM for every fence.

## 60-second quickstart

### bash

```bash
# from the repository root
npm install
npm test
node dist/src/cli.js --help
node dist/src/cli.js fixtures/sample-readme.md
```

### PowerShell

```powershell
# from the repository root
npm install
npm test
node dist/src/cli.js --help
node dist/src/cli.js fixtures/sample-readme.md
```

## What it does (v0.1)

1. Parses Markdown fences (` ``` ` and `~~~`)
2. Runs `js` / `javascript` / `ts` / `typescript` with a per-snippet timeout
3. Blocks network by default: stubs `fetch` and denies `http`/`https`/`net`/`dns` requires (Node's permission flag no longer covers net on modern Node)
4. On Windows, **skips** `bash` / `sh` / `shell` fences and prints a clear reason (no silent ignore)

## CLI

```text
readme-snippet-runner [options] <file.md> [more.md...]

--timeout <ms>     Per-snippet timeout (default: 10000)
  --allow-network    Disable network blocking
  --json             JSON summary
  -h, --help         Help
```

Exit `1` if any runnable snippet fails or times out; exit `2` on usage/IO errors.

## GitHub Action

```yaml
- uses: ./
  with:
    files: README.md,docs/**/*.md
    timeout-ms: "10000"
    fail-on-error: "true"
```

### Action inputs

| Input | Default | Description |
| --- | --- | --- |
| `files` | `README.md` | Comma-separated paths or `*.md` globs |
| `timeout-ms` | `10000` | Per-snippet timeout |
| `fail-on-error` | `true` | Fail the job on snippet failure |
| `skip-bash` | `true` | Skip bash-like fences (always on Windows) |

### Action outputs

`ran`, `skipped`, `failed`

## Library

```js
import { extractSnippets, runSnippets } from "readme-snippet-runner";

const snippets = extractSnippets(markdown, "README.md");
const summary = await runSnippets(snippets, { timeoutMs: 5000 });
```

## Fixtures

`fixtures/sample-readme.md` proves JS + TS execution and bash skip messaging.

## Honest v0.2 limitations

- No bash/PowerShell execution yet (skipped with messages; Linux bash planned)
- Snippets run as CommonJS temp files (ESM `import` in fences needs care)
- Permission-model extras (`--permission`) still applied for FS hardening; network deny is enforced by the runner preamble because modern Node dropped `--allow-net`
- No package.json dependency install for snippets that `require()` third-party modules unless already present
- Glob expansion in the Action is intentionally simple (`*.md` walk), not full gitignore-aware globs
- Does not validate non-JS languages (python, go, etc.)

## License

MIT

readme-snippet-runner

readme-snippet-runner Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

readme-snippet-runner

readme-snippet-runner Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README