tryscript 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joshua Levy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,223 +1,132 @@
 # tryscript
 
-Golden testing for CLI applications - a TypeScript port of [trycmd](https://github.com/assert-rs/trycmd).
-
-## Requirements
-
-- **Node.js 20+** (tested with v20, v22, v24)
-
-## Installation
+[![CI](https://github.com/jlevy/tryscript/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/tryscript/actions/workflows/ci.yml)
+[![Coverage](https://raw.githubusercontent.com/jlevy/tryscript/main/badges/packages/tryscript/coverage-total.svg)](https://raw.githubusercontent.com/jlevy/tryscript/main/badges/packages/tryscript/coverage-total.svg)
+[![npm version](https://img.shields.io/npm/v/tryscript)](https://www.npmjs.com/package/tryscript)
+[![X Follow](https://img.shields.io/twitter/follow/ojoshe)](https://x.com/ojoshe)
 
-```bash
-npm install tryscript
-# or
-pnpm add tryscript
-```
-
-## Quick Start
-
-Create a test file with the `.tryscript.md` extension:
-
-```markdown
-# Test: Help command
-
-\`\`\`console
-$ my-cli --help
-Usage: my-cli [options]
-
-Options:
-  --version  Show version
-  --help     Show help
-? 0
-\`\`\`
-```
-
-Run the tests:
-
-```bash
-npx tryscript tests/
-```
-
-## Test File Format
-
-Test files are Markdown documents with console code blocks. Each code block represents a test case:
+Golden testing for CLI applications - a TypeScript port of [trycmd](https://github.com/assert-rs/trycmd).
 
-```markdown
-\`\`\`console
-$ <command>
-<expected output>
-? <exit code>
-\`\`\`
-```
+## What It Does
 
-### Example
+Write CLI tests as Markdown. tryscript runs commands, captures output, and compares against expected results. Tests become documentation; documentation becomes tests.
 
-```markdown
-# Test: Echo command
+````markdown
+# Test: Basic echo
 
-\`\`\`console
+```console
 $ echo "hello world"
 hello world
 ? 0
-\`\`\`
+```
 
-# Test: Exit with error
+# Test: Grep with pattern matching
 
-\`\`\`console
-$ exit 1
-? 1
-\`\`\`
+```console
+$ ls -la | grep ".md"
+[..]README.md
+...
+? 0
 ```
+````
 
-## Elision Patterns
+The `[..]` matches any text on that line. The `...` matches zero or more lines. These "elision patterns" let tests handle dynamic output gracefully.
 
-Use elision patterns to match dynamic or platform-specific output:
+## Quick Start
 
-| Pattern  | Description                              | Example                    |
-| -------- | ---------------------------------------- | -------------------------- |
-| `[..]`   | Match any characters on the current line | `Built in [..]ms`          |
-| `...`    | Match zero or more complete lines        | `...\nDone`                |
-| `[EXE]`  | Match `.exe` on Windows, empty otherwise | `my-cli[EXE] --help`       |
-| `[ROOT]` | Match the test's root directory          | `[ROOT]/output.txt`        |
-| `[CWD]`  | Match the current working directory      | `[CWD]/file.txt`           |
+```bash
+# Install
+pnpm add -D tryscript
 
-### Example with Elision
+# Run tests
+npx tryscript run tests/
 
-```markdown
-\`\`\`console
-$ time-command
-Elapsed: [..]ms
-? 0
-\`\`\`
+# Update expected output when behavior changes
+npx tryscript run --update tests/
 ```
 
-## Configuration
+## Features
 
-### YAML Frontmatter
+- **Markdown format** - Tests are readable documentation
+- **Elision patterns** - Handle variable output: `[..]`, `...`, `[CWD]`, `[ROOT]`, `[EXE]`
+- **Custom patterns** - Define regex patterns for timestamps, versions, UUIDs
+- **Update mode** - Regenerate expected output with `--update`
+- **Sandbox mode** - Isolate tests in temp directories
+- **Code coverage** - Track coverage from subprocess execution with `--coverage`
 
-Add configuration at the top of your test file:
+## Example Test File
 
-```markdown
+````markdown
 ---
-bin: ./my-cli
 env:
   NO_COLOR: "1"
-timeout: 5000
+sandbox: true
 ---
 
-# Test: Custom binary
-
-\`\`\`console
-$ my-cli --version
-1.0.0
-? 0
-\`\`\`
-```
-
-### Config File
-
-Create `tryscript.config.ts` in your project root:
+# Test: CLI help
 
-```typescript
-import { defineConfig } from 'tryscript';
+```console
+$ my-cli --help
+Usage: my-cli [options] <command>
 
-export default defineConfig({
-  bin: './dist/cli.js',
-  env: {
-    NO_COLOR: '1',
-  },
-  timeout: 30000,
-  patterns: {
-    VERSION: '\\d+\\.\\d+\\.\\d+',
-    UUID: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}',
-  },
-});
+Options:
+  --version  Show version
+  --help     Show this help
+...
+? 0
 ```
 
-## CLI Options
+# Test: Version output
 
+```console
+$ my-cli --version
+my-cli v[..]
+? 0
 ```
-tryscript [options] [files...]
 
-Arguments:
-  files               Test files to run (default: **/*.tryscript.md)
+# Test: Error handling
 
-Options:
-  --version           Show version number
-  --update            Update golden files with actual output
-  --diff              Show diff on failure (default: true)
-  --no-diff           Hide diff on failure
-  --fail-fast         Stop on first failure
-  --filter <pattern>  Filter tests by name pattern
-  --verbose           Show detailed output
-  --quiet             Suppress non-essential output
-  --help              Show help
+```console
+$ my-cli unknown-command 2>&1
+Error: unknown command 'unknown-command'
+? 1
 ```
+````
 
-## Update Mode
-
-When your CLI output changes, update all test files at once:
+## CLI Reference
 
 ```bash
-npx tryscript --update
+tryscript run [files...]  # Run golden tests
+tryscript docs            # Show syntax quick reference
+tryscript readme          # Show this documentation
+tryscript --help          # Show all options
 ```
 
-This rewrites test files with the actual output from running the commands.
+For complete syntax reference, run `tryscript docs` or see the [reference documentation](https://github.com/jlevy/tryscript/blob/main/docs/tryscript-reference.md).
 
-## Programmatic API
+### Common Options
 
-```typescript
-import { parseTestFile, runBlock, createExecutionContext, matchOutput } from 'tryscript';
+| Option | Description |
+| --- | --- |
+| `--update` | Update test files with actual output |
+| `--fail-fast` | Stop on first failure |
+| `--filter <regex>` | Filter tests by name |
+| `--verbose` | Show detailed output |
+| `--coverage` | Collect code coverage (requires c8) |
 
-const content = await fs.readFile('test.tryscript.md', 'utf-8');
-const testFile = parseTestFile(content, 'test.tryscript.md');
-
-const ctx = await createExecutionContext({}, 'test.tryscript.md');
-for (const block of testFile.blocks) {
-  const result = await runBlock(block, ctx);
-  const matches = matchOutput(
-    result.actualOutput,
-    block.expectedOutput,
-    { root: ctx.tempDir, cwd: ctx.tempDir },
-  );
-  console.log(`${block.name}: ${matches ? 'PASS' : 'FAIL'}`);
-}
-```
-
-## Measuring Coverage
-
-When testing CLI tools as subprocesses, standard coverage tools don't track execution. Use [c8](https://github.com/bcoe/c8) which leverages Node's V8 coverage collection:
+## Development
 
 ```bash
-npm install -D c8
-```
-
-Add scripts to your `package.json`:
-
-```json
-{
-  "scripts": {
-    "test:golden": "tryscript 'tests/**/*.tryscript.md'",
-    "test:golden:coverage": "c8 --src src --all --include 'dist/**' tryscript 'tests/**/*.tryscript.md'"
-  }
-}
+# Clone and install
+git clone https://github.com/jlevy/tryscript.git
+cd tryscript
+pnpm install
+
+# Build and test
+pnpm build
+pnpm test
 ```
 
-Key c8 flags:
-- `--src src` — Map coverage back to source files
-- `--all` — Include files with 0% coverage
-- `--include 'dist/**'` — Track your built CLI output
-
-This captures coverage from actual CLI usage—the most realistic testing possible.
-
-## Comparison with trycmd
-
-tryscript is a TypeScript port of the Rust [trycmd](https://github.com/assert-rs/trycmd) crate. Key differences:
-
-- **Language**: TypeScript/Node.js instead of Rust
-- **Format**: Uses console code blocks (trycmd uses `.toml` or `.trycmd` files)
-- **Integration**: Works with Node.js test frameworks (Vitest, Jest)
-
 ## License
 
 MIT