tryscript 0.0.1 → 0.1.0

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

@@ -2,222 +2,72 @@
 
 Golden testing for CLI applications - a TypeScript port of [trycmd](https://github.com/assert-rs/trycmd).
 
-## Requirements
+## Overview
 
-- **Node.js 20+** (tested with v20, v22, v24)
+tryscript enables golden testing for any CLI application. Write test cases in Markdown with console code blocks, and tryscript runs the commands, compares output, and reports differences.
 
-## Installation
+````markdown
+# Test: Hello World
 
-```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:
-
-```markdown
-\`\`\`console
-$ <command>
-<expected output>
-? <exit code>
-\`\`\`
-```
-
-### Example
-
-```markdown
-# Test: Echo command
-
-\`\`\`console
+```console
 $ echo "hello world"
 hello world
 ? 0
-\`\`\`
-
-# Test: Exit with error
-
-\`\`\`console
-$ exit 1
-? 1
-\`\`\`
 ```
+````
 
-## Elision Patterns
-
-Use elision patterns to match dynamic or platform-specific output:
-
-| 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`           |
+## Features
 
-### Example with Elision
-
-```markdown
-\`\`\`console
-$ time-command
-Elapsed: [..]ms
-? 0
-\`\`\`
-```
+- **Markdown test format** - Tests are readable documentation
+- **Elision patterns** - Match dynamic output with `[..]`, `...`, `[EXE]`, `[ROOT]`, `[CWD]`
+- **Custom patterns** - Define regex patterns for timestamps, versions, UUIDs
+- **Update mode** - Regenerate golden files with `--update`
+- **Self-bootstrapping** - tryscript tests itself
 
-## Configuration
-
-### YAML Frontmatter
-
-Add configuration at the top of your test file:
+## Quick Start
 
-```markdown
----
-bin: ./my-cli
-env:
-  NO_COLOR: "1"
-timeout: 5000
----
+```bash
+# Install
+pnpm add tryscript
 
-# Test: Custom binary
+# Run tests
+npx tryscript tests/
 
-\`\`\`console
-$ my-cli --version
-1.0.0
-? 0
-\`\`\`
+# Update golden files
+npx tryscript --update
 ```
 
-### Config File
+## Documentation
 
-Create `tryscript.config.ts` in your project root:
+See [packages/tryscript/README.md](packages/tryscript/README.md) for full documentation.
 
-```typescript
-import { defineConfig } from 'tryscript';
+## Project Structure
 
-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}',
-  },
-});
 ```
-
-## CLI Options
-
+tryscript/
+├── packages/
+│   └── tryscript/     # Main package
+│       ├── src/       # TypeScript source
+│       └── tests/     # Self-tests
+└── docs/              # Documentation
 ```
-tryscript [options] [files...]
-
-Arguments:
-  files               Test files to run (default: **/*.tryscript.md)
-
-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
-```
-
-## Update Mode
 
-When your CLI output changes, update all test files at once:
+## Development
 
 ```bash
-npx tryscript --update
-```
-
-This rewrites test files with the actual output from running the commands.
+# Install dependencies
+pnpm install
 
-## Programmatic API
+# Build
+pnpm build
 
-```typescript
-import { parseTestFile, runBlock, createExecutionContext, matchOutput } from 'tryscript';
+# Run tests
+pnpm test
 
-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:
-
-```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'"
-  }
-}
+# Run self-tests
+pnpm -r tryscript tests/
 ```
 
-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

package/dist/bin.cjs

@@ -1,21 +1,85 @@
 #!/usr/bin/env node
 
 
-const require_src = require('./src-CeUA446P.cjs');
+const require_src = require('./src-CP4-Q-U5.cjs');
 let node_url = require("node:url");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 let node_fs_promises = require("node:fs/promises");
 let commander = require("commander");
-let picocolors = require("picocolors");
-picocolors = require_src.__toESM(picocolors);
 let fast_glob = require("fast-glob");
 fast_glob = require_src.__toESM(fast_glob);
+let picocolors = require("picocolors");
+picocolors = require_src.__toESM(picocolors);
 let diff = require("diff");
 let atomically = require("atomically");
 
+//#region src/cli/lib/shared.ts
+/**
+* Shared color utilities for consistent terminal output.
+*/
+const colors = {
+	success: (s) => picocolors.default.green(s),
+	error: (s) => picocolors.default.red(s),
+	info: (s) => picocolors.default.cyan(s),
+	warn: (s) => picocolors.default.yellow(s),
+	muted: (s) => picocolors.default.gray(s),
+	bold: (s) => picocolors.default.bold(s)
+};
+/**
+* Status indicators with emoji.
+*/
+const status = {
+	pass: picocolors.default.green("✓"),
+	fail: picocolors.default.red("✗"),
+	skip: picocolors.default.yellow("○"),
+	update: picocolors.default.yellow("↻")
+};
+/**
+* Configure Commander.js with colored help text.
+* Applies consistent styling: cyan titles, green commands, yellow options.
+*/
+function withColoredHelp(cmd) {
+	cmd.configureHelp({
+		styleTitle: (str) => picocolors.default.bold(picocolors.default.cyan(str)),
+		styleCommandText: (str) => picocolors.default.green(str),
+		styleOptionText: (str) => picocolors.default.yellow(str),
+		showGlobalOptions: true
+	});
+	return cmd;
+}
+/**
+* Log a warning message to stderr.
+*/
+function logWarn(message) {
+	console.error(colors.warn(message));
+}
+/**
+* Log an error message to stderr.
+*/
+function logError(message) {
+	console.error(colors.error(message));
+}
+
+//#endregion
 //#region src/lib/reporter.ts
 /**
+* Test result reporting utilities.
+*
+* Handles output formatting for test results, diffs, and summaries.
+*/
+const statusIcon = {
+	pass: picocolors.default.green("✓"),
+	fail: picocolors.default.red("✗")
+};
+/**
+* Format a duration in milliseconds for display.
+*/
+function formatDuration(ms) {
+	if (ms < 1e3) return `${ms}ms`;
+	return `${(ms / 1e3).toFixed(2)}s`;
+}
+/**
 * Create a unified diff between expected and actual output.
 */
 function createDiff(expected, actual, filename) {
@@ -27,26 +91,19 @@ function createDiff(expected, actual, filename) {
 	}).join("\n");
 }
 /**
-* Format a duration in milliseconds for display.
-*/
-function formatDuration(ms) {
-	if (ms < 1e3) return `${ms}ms`;
-	return `${(ms / 1e3).toFixed(2)}s`;
-}
-/**
 * Report results for a single file.
 */
 function reportFile(result, options) {
 	const filename = result.file.path;
-	const status = result.passed ? picocolors.default.green(picocolors.default.bold("PASS")) : picocolors.default.red(picocolors.default.bold("FAIL"));
+	const status$1 = result.passed ? picocolors.default.green(picocolors.default.bold("PASS")) : picocolors.default.red(picocolors.default.bold("FAIL"));
 	if (options.quiet && result.passed) return;
-	console.error(`${status} ${filename}`);
+	console.error(`${status$1} ${filename}`);
 	for (const blockResult of result.results) {
 		const name = blockResult.block.name ?? `Line ${blockResult.block.lineNumber}`;
 		if (blockResult.passed) {
-			if (!options.quiet) console.error(`  ${picocolors.default.green("✓")} ${name}`);
+			if (!options.quiet) console.error(`  ${statusIcon.pass} ${name}`);
 		} else {
-			console.error(`  ${picocolors.default.red("✗")} ${name}`);
+			console.error(`  ${statusIcon.fail} ${name}`);
 			if (blockResult.error) console.error(`    ${picocolors.default.red(blockResult.error)}`);
 			else {
 				if (blockResult.actualExitCode !== blockResult.block.expectedExitCode) console.error(`    Expected exit code ${blockResult.block.expectedExitCode}, got ${blockResult.actualExitCode}`);
@@ -115,6 +172,12 @@ function buildUpdatedBlock(block, result) {
 
 //#endregion
 //#region src/cli/commands/run.ts
+/**
+* Register the run command.
+*/
+function registerRunCommand(program) {
+	program.command("run").description("Run golden tests").argument("[files...]", "Test files to run (default: **/*.tryscript.md)").option("--update", "Update golden files with actual output").option("--diff", "Show diff on failure (default: true)").option("--no-diff", "Hide diff on failure").option("--fail-fast", "Stop on first failure").option("--filter <pattern>", "Filter tests by name pattern").option("--verbose", "Show detailed output including passing test output").option("--quiet", "Suppress non-essential output (only show failures)").action(runCommand);
+}
 async function runCommand(files, options) {
 	const startTime = Date.now();
 	const opts = {
@@ -131,7 +194,7 @@ async function runCommand(files, options) {
 		dot: false
 	});
 	if (testFiles.length === 0) {
-		console.error(picocolors.default.yellow("No test files found"));
+		logWarn("No test files found");
 		process.exit(1);
 	}
 	const globalConfig = await require_src.loadConfig(process.cwd());
@@ -146,18 +209,29 @@ async function runCommand(files, options) {
 			const filterPattern = new RegExp(opts.filter, "i");
 			blocksToRun = blocksToRun.filter((b) => b.name ? filterPattern.test(b.name) : true);
 		}
+		const onlyBlocks = blocksToRun.filter((b) => b.only);
+		if (onlyBlocks.length > 0) blocksToRun = onlyBlocks;
 		if (blocksToRun.length === 0) continue;
 		const ctx = await require_src.createExecutionContext(config, filePath);
 		const results = [];
 		try {
 			for (const block of blocksToRun) {
 				const result = await require_src.runBlock(block, ctx);
-				const matches = require_src.matchOutput(result.actualOutput, block.expectedOutput, {
-					root: ctx.tempDir,
-					cwd: ctx.tempDir
+				if (result.skipped) {
+					results.push(result);
+					continue;
+				}
+				const outputMatches = require_src.matchOutput(block.expectedStderr ? result.actualStdout ?? "" : result.actualOutput, block.expectedOutput, {
+					root: ctx.testDir,
+					cwd: ctx.cwd
+				}, config.patterns ?? {});
+				let stderrMatches = true;
+				if (block.expectedStderr) stderrMatches = require_src.matchOutput(result.actualStderr ?? "", block.expectedStderr, {
+					root: ctx.testDir,
+					cwd: ctx.cwd
 				}, config.patterns ?? {});
 				const exitCodeMatches = result.actualExitCode === block.expectedExitCode;
-				result.passed = matches && exitCodeMatches && !result.error;
+				result.passed = outputMatches && stderrMatches && exitCodeMatches && !result.error;
 				if (!result.passed && opts.diff) result.diff = createDiff(block.expectedOutput, result.actualOutput, `${filePath}:${block.lineNumber}`);
 				results.push(result);
 				if (!result.passed && opts.failFast) {
@@ -165,6 +239,7 @@ async function runCommand(files, options) {
 					break;
 				}
 			}
+			await require_src.runAfterHook(ctx);
 		} finally {
 			await require_src.cleanupExecutionContext(ctx);
 		}
@@ -178,7 +253,7 @@ async function runCommand(files, options) {
 		reportFile(fileResult, opts);
 		if (opts.update && !fileResult.passed) {
 			const { updated, changes } = await updateTestFile(testFile, results);
-			if (updated) console.error(picocolors.default.yellow(`  ↻ Updated: ${changes.join(", ")}`));
+			if (updated) console.error(colors.warn(`  ${status.update} Updated: ${changes.join(", ")}`));
 		}
 	}
 	const summary = {
@@ -266,19 +341,24 @@ function isInteractive$1() {
 	return process.stdout.isTTY === true;
 }
 /**
+* Display the README content.
+* Exported for use as the default command.
+*/
+function showReadme(options) {
+	try {
+		const formatted = formatMarkdown$1(loadReadme(), !options?.raw && isInteractive$1());
+		console.log(formatted);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.error(picocolors.default.red(`Error: ${message}`));
+		process.exit(1);
+	}
+}
+/**
 * Register the readme command.
 */
 function registerReadmeCommand(program) {
-	program.command("readme").description("Display README documentation").option("--raw", "Output raw markdown without formatting").action((options) => {
-		try {
-			const formatted = formatMarkdown$1(loadReadme(), !options.raw && isInteractive$1());
-			console.log(formatted);
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			console.error(picocolors.default.red(`Error: ${message}`));
-			process.exit(1);
-		}
-	});
+	program.command("readme").description("Display README documentation").option("--raw", "Output raw markdown without formatting").action(showReadme);
 }
 
 //#endregion
@@ -372,12 +452,21 @@ function registerDocsCommand(program) {
 
 //#endregion
 //#region src/cli/cli.ts
+/**
+* CLI entry point for tryscript.
+*
+* Configures Commander.js with colored help and registers all subcommands.
+*/
 function run(argv) {
-	const program = new commander.Command().name("tryscript").version(require_src.VERSION, "--version", "Show version number").description("Golden testing for CLI applications").showHelpAfterError("(use --help for usage)").argument("[files...]", "Test files to run (default: **/*.tryscript.md)").option("--update", "Update golden files with actual output").option("--diff", "Show diff on failure (default: true)").option("--no-diff", "Hide diff on failure").option("--fail-fast", "Stop on first failure").option("--filter <pattern>", "Filter tests by name pattern").option("--verbose", "Show detailed output including passing test output").option("--quiet", "Suppress non-essential output (only show failures)").action(runCommand);
+	const program = withColoredHelp(new commander.Command().name("tryscript").version(require_src.VERSION, "--version", "Show version number").description("Golden testing for CLI applications").showHelpAfterError("(use --help for usage)"));
+	registerRunCommand(program);
 	registerReadmeCommand(program);
 	registerDocsCommand(program);
+	program.action(() => {
+		program.help();
+	});
 	program.parseAsync(argv).catch((err) => {
-		console.error(picocolors.default.red(`Error: ${err.message}`));
+		logError(`Error: ${err.message}`);
 		process.exit(2);
 	});
 }