@halecraft/verify 1.0.0 → 1.2.0

package/README.md

@@ -40,14 +40,14 @@ import { defineConfig } from "@halecraft/verify";
 
 export default defineConfig({
   tasks: [
-    { key: "format", run: "pnpm lint" },
-    { key: "types", run: "pnpm typecheck" },
-    { key: "test", run: "pnpm test" },
+    { key: "format", run: "biome check ." },
+    { key: "types", run: "tsc --noEmit" },
+    { key: "test", run: "vitest run" },
   ],
 });
 ```
 
-Note that you can shave off ~150ms for each command if you skip your package manager (e.g. `./node_modules/.bin/eslint` instead of `pnpm lint`).
+**Note:** Commands automatically have access to binaries in `node_modules/.bin` directories. You can write `run: "biome check ."` instead of `run: "./node_modules/.bin/biome check ."`. This works in monorepos too—verify walks up the directory tree to find all `node_modules/.bin` directories, just like npm/pnpm/yarn do when running package.json scripts.
 
 ### Run Verification
 
@@ -58,6 +58,16 @@ pnpm exec verify
 # Run specific task
 pnpm exec verify format
 
+# Run nested task with full path
+pnpm exec verify types:tsc
+
+# Run nested task with shortcut (if unambiguous)
+pnpm exec verify tsc
+# → Resolving "tsc" to "types:tsc"
+
+# Pass arguments to underlying command
+pnpm exec verify logic -- -t "specific test name"
+
 # Run with verbose output
 pnpm exec verify --verbose
 
@@ -87,11 +97,16 @@ interface VerificationNode {
   name?: string;
 
   // Command to run (leaf nodes only)
-  // Supports: string, object with cmd/args/cwd, or [cmd, args] tuple
+  // Supports: string, object with cmd/args/cwd/env/timeout
   run?:
     | string
-    | { cmd: string; args: string[]; cwd?: string }
-    | [string, string[]];
+    | {
+        cmd: string;
+        args: string[];
+        cwd?: string;
+        env?: Record<string, string | null>;
+        timeout?: number;
+      };
 
   // Child tasks (for grouping)
   children?: VerificationNode[];
@@ -105,6 +120,13 @@ interface VerificationNode {
   // Tasks that must pass for this task's failure to be reported
   reportingDependsOn?: string[];
 
+  // Timeout in milliseconds (for string commands)
+  timeout?: number;
+
+  // Environment variables for this task and its children
+  // Set to null to unset an inherited variable
+  env?: Record<string, string | null>;
+
   // Custom success message template (optional)
   successLabel?: string;
 
@@ -222,13 +244,99 @@ Control how child tasks are executed:
 - `sequential`: Run tasks one after another
 - `fail-fast`: Run sequentially, stop on first failure
 
+### Command Timeouts
+
+Prevent hung processes by setting a timeout (in milliseconds):
+
+```typescript
+import { defineConfig } from "@halecraft/verify";
+
+export default defineConfig({
+  tasks: [
+    // String command with timeout
+    { key: "test", run: "vitest run", timeout: 60000 }, // 60 seconds
+
+    // Object command with timeout
+    {
+      key: "build",
+      run: {
+        cmd: "tsup",
+        args: [],
+        timeout: 120000, // 2 minutes
+      },
+    },
+  ],
+});
+```
+
+When a command exceeds its timeout:
+
+- The process is killed with `SIGTERM` (including child processes)
+- The task is marked as failed with `timedOut: true`
+- The summary shows: `task: timed out after 60000ms`
+
+**Note:** For object commands, the `timeout` on the command takes precedence over the node-level `timeout`.
+
+### Environment Variables
+
+Set environment variables at the config level (applies to all tasks) or at the task level (inherits to children):
+
+```typescript
+import { defineConfig } from "@halecraft/verify";
+
+export default defineConfig({
+  // Global env vars - applied to all tasks
+  env: {
+    NO_COLOR: "1", // Recommended: disable colors for cleaner output parsing
+    CI: "true",
+  },
+  tasks: [
+    { key: "format", run: "biome check ." },
+    {
+      key: "test",
+      // Enable colors for test output by unsetting NO_COLOR
+      env: { NO_COLOR: null },
+      children: [
+        { key: "unit", run: "vitest run" },
+        {
+          key: "e2e",
+          run: "playwright test",
+          // E2E-specific env (still inherits CI: "true")
+          env: { PLAYWRIGHT_BROWSERS_PATH: "0" },
+        },
+      ],
+    },
+  ],
+});
+```
+
+**Environment merge order** (most specific wins):
+
+1. `process.env` - System environment
+2. `config.env` - Global config-level
+3. Parent task `env` - Inherited from parent tasks
+4. Node `env` - Current task
+5. Command `env` - VerificationCommand object only
+
+**Unsetting variables:** Set a value to `null` to explicitly unset an inherited variable:
+
+```typescript
+{
+  key: "test",
+  env: { NO_COLOR: null }, // Re-enables colors for this task
+  run: "vitest run",
+}
+```
+
+**Note:** Generated configs (via `--init`) include `env: { NO_COLOR: "1" }` by default to ensure consistent output parsing.
+
 ## CLI Options
 
 ```
 Usage:
-  verify [options] [filter...]
+  verify [flags...] [task] [--] [passthrough...]
 
-Options:
+Flags:
   --json              Output results as JSON
   --verbose, -v       Show all task output
   --quiet, -q         Show only final result
@@ -236,13 +344,83 @@ Options:
   --no-tty            Force sequential output (disable live dashboard)
   --logs=MODE         Log verbosity: all, failed, none (default: failed)
   --config, -c PATH   Path to config file (or output path for --init)
-  --filter, -f PATH   Filter to specific task paths
   --init              Initialize a new verify.config.ts file
   --force             Overwrite existing config file (with --init)
   --yes, -y           Skip interactive prompts, auto-accept detected tasks
   --help, -h          Show this help message
 ```
 
+### Passthrough Arguments
+
+You can pass arguments directly to the underlying command using `--` (double-dash):
+
+```bash
+# Run a specific vitest test
+verify logic -- -t "should handle edge case"
+
+# Run with coverage
+verify logic -- --coverage
+
+# Multiple passthrough args
+verify logic -- -t "foo" --reporter=verbose
+
+# Combine with verify flags
+verify logic --verbose -- -t "foo"
+```
+
+**Requirements:**
+- Passthrough arguments require exactly one task filter
+- The task must be a leaf node (has a `run` command)
+- Arguments are appended to the command string
+
+**How it works:**
+- For string commands: args are shell-escaped and appended to the command
+- For object commands: args are appended to the `args` array
+
+### Exit Codes
+
+- `0` - All tasks passed
+- `1` - Some tasks failed
+- `2` - Configuration/usage error (invalid task name, missing config)
+
+### Task Name Validation
+
+Verify validates task names before running any tasks. If you specify a task that doesn't exist, you'll get a helpful error:
+
+```bash
+$ verify test
+Error: Task "test" not found.
+
+Did you mean "types:tsc"?
+
+Available tasks:
+  format
+  logic
+  types
+  types:tsc
+  types:tsgo
+  build
+```
+
+**Child task shortcuts:** You can use just the child key if it's unambiguous:
+
+```bash
+$ verify tsc
+→ Resolving "tsc" to "types:tsc"
+✓ verified types:tsc
+```
+
+If the shortcut is ambiguous (multiple tasks have the same child key), you'll get an error listing the options:
+
+```bash
+$ verify test  # if both unit:test and e2e:test exist
+Error: Task "test" is ambiguous.
+
+Matches multiple tasks:
+  unit:test
+  e2e:test
+```
+
 ## Programmatic API
 
 ```typescript
@@ -293,6 +471,7 @@ interface TaskResult {
   summaryLine: string; // Parsed summary
   suppressed?: boolean; // True if output was suppressed
   suppressedBy?: string; // Path of dependency that caused suppression
+  timedOut?: boolean; // True if task exceeded its timeout
   children?: TaskResult[]; // Child results (for group nodes)
 }
 ```
@@ -301,14 +480,38 @@ interface TaskResult {
 
 Built-in parsers for common tools:
 
-- **vitest** - Vitest test runner
-- **tsc** - TypeScript compiler
-- **biome** - Biome linter/formatter
+- **vitest** - Vitest/Jest test runner
+- **tsc** - TypeScript compiler (tsc/tsgo)
+- **biome** - Biome/ESLint linter/formatter
 - **gotest** - Go test runner
 - **generic** - Fallback for unknown tools
 
 Parsers automatically extract metrics (passed/failed counts, duration) and provide concise summaries.
 
+### Parser ID Constants
+
+Use `parsers` for type-safe parser references instead of magic strings:
+
+```typescript
+import { defineConfig, parsers } from "@halecraft/verify";
+
+export default defineConfig({
+  tasks: [
+    { key: "test", run: "vitest run", parser: parsers.vitest },
+    { key: "types", run: "tsc --noEmit", parser: parsers.tsc },
+    { key: "lint", run: "biome check .", parser: parsers.biome },
+  ],
+});
+```
+
+Available constants:
+
+- `parsers.vitest` - `"vitest"`
+- `parsers.tsc` - `"tsc"`
+- `parsers.biome` - `"biome"`
+- `parsers.gotest` - `"gotest"`
+- `parsers.generic` - `"generic"`
+
 ## License
 
 MIT

package/bin/verify.mjs

@@ -1,140 +1,110 @@
 #!/usr/bin/env node
 
-import { runInit, verifyFromConfig } from "../dist/index.js"
-
-/**
- * Parse CLI arguments
- */
-function parseArgs(args) {
-  const options = {
-    json: false,
-    verbose: false,
-    quiet: false,
-    logs: undefined,
-    filter: [],
-    config: undefined,
-    help: false,
-    init: false,
-    force: false,
-    yes: false,
-    topLevelOnly: false,
-    noTty: false,
-  }
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i]
-
-    if (arg === "--json") {
-      options.json = true
-    } else if (arg === "--verbose" || arg === "-v") {
-      options.verbose = true
-    } else if (arg === "--quiet" || arg === "-q") {
-      options.quiet = true
-    } else if (arg === "--help" || arg === "-h") {
-      options.help = true
-    } else if (arg === "--init") {
-      options.init = true
-    } else if (arg === "--force") {
-      options.force = true
-    } else if (arg === "--yes" || arg === "-y") {
-      options.yes = true
-    } else if (arg === "--top-level" || arg === "-t") {
-      options.topLevelOnly = true
-    } else if (arg === "--no-tty") {
-      options.noTty = true
-    } else if (arg.startsWith("--logs=")) {
-      options.logs = arg.slice(7)
-    } else if (arg === "--logs") {
-      options.logs = args[++i]
-    } else if (arg.startsWith("--config=")) {
-      options.config = arg.slice(9)
-    } else if (arg === "--config" || arg === "-c") {
-      options.config = args[++i]
-    } else if (arg.startsWith("--filter=")) {
-      options.filter.push(arg.slice(9))
-    } else if (arg === "--filter" || arg === "-f") {
-      options.filter.push(args[++i])
-    } else if (!arg.startsWith("-")) {
-      // Positional argument treated as filter
-      options.filter.push(arg)
-    }
-  }
-
-  return options
-}
-
-/**
- * Print help message
- */
-function printHelp() {
-  console.log(`
-@halecraft/verify - Hierarchical verification runner
-
-Usage:
-  verify [options] [filter...]
-
-Options:
-  --json              Output results as JSON
-  --verbose, -v       Show all task output
-  --quiet, -q         Show only final result
-  --top-level, -t     Show only top-level tasks (hide descendants)
-  --no-tty            Force sequential output (disable live dashboard)
-  --logs=MODE         Log verbosity: all, failed, none (default: failed)
-  --config, -c PATH   Path to config file (or output path for --init)
-  --filter, -f PATH   Filter to specific task paths
-  --init              Initialize a new verify.config.ts file
-  --force             Overwrite existing config file (with --init)
-  --yes, -y           Skip interactive prompts, auto-accept detected tasks
-  --help, -h          Show this help message
-
-Examples:
-  verify                    Run all verifications
-  verify logic              Run only 'logic' tasks
-  verify logic:ts           Run only 'logic:ts' task
-  verify --top-level        Show only top-level tasks
-  verify --json             Output JSON for CI
-  verify --logs=all         Show all output
-  verify --init             Create config interactively
-  verify --init -y          Create config with all detected tasks
-  verify --init --force     Overwrite existing config
-
-Config:
-  Create a verify.config.ts file in your project root:
-
-  import { defineConfig } from '@halecraft/verify'
+import { cli } from "cleye"
+import {
+  AmbiguousTaskError,
+  runInit,
+  TaskNotFoundError,
+  verifyFromConfig,
+} from "../dist/index.js"
+
+const argv = cli(
+  {
+    name: "verify",
+    version: "1.0.0",
+    description: "Hierarchical verification runner with parallel execution",
+
+    parameters: [
+      "[task]",           // Optional single task filter
+      "--",               // End-of-flags separator
+      "[passthrough...]", // Args to pass to underlying command
+    ],
 
-  export default defineConfig({
-    tasks: [
-      { key: 'format', run: 'pnpm verify:format' },
-      { key: 'types', run: 'pnpm verify:types' },
-      {
-        key: 'logic',
-        children: [
-          { key: 'ts', run: 'vitest run' },
-          { key: 'go', run: 'go test ./...' },
-        ],
+    flags: {
+      json: {
+        type: Boolean,
+        description: "Output results as JSON",
+        default: false,
       },
-    ],
-  })
-`)
-}
+      verbose: {
+        type: Boolean,
+        alias: "v",
+        description: "Show all task output",
+        default: false,
+      },
+      quiet: {
+        type: Boolean,
+        alias: "q",
+        description: "Show only final result",
+        default: false,
+      },
+      topLevel: {
+        type: Boolean,
+        alias: "t",
+        description: "Show only top-level tasks (hide descendants)",
+        default: false,
+      },
+      noTty: {
+        type: Boolean,
+        description: "Force sequential output (disable live dashboard)",
+        default: false,
+      },
+      logs: {
+        type: String,
+        description: "Log verbosity: all, failed, none (default: failed)",
+      },
+      config: {
+        type: String,
+        alias: "c",
+        description: "Path to config file (or output path for --init)",
+      },
+      init: {
+        type: Boolean,
+        description: "Initialize a new verify.config.ts file",
+        default: false,
+      },
+      force: {
+        type: Boolean,
+        description: "Overwrite existing config file (with --init)",
+        default: false,
+      },
+      yes: {
+        type: Boolean,
+        alias: "y",
+        description: "Skip interactive prompts, auto-accept detected tasks",
+        default: false,
+      },
+    },
+
+    help: {
+      examples: [
+        "verify                    Run all verifications",
+        "verify logic              Run only 'logic' tasks",
+        "verify logic:ts           Run only 'logic:ts' task",
+        "verify logic -- -t foo    Run 'logic' with passthrough args",
+        "verify --top-level        Show only top-level tasks",
+        "verify --json             Output JSON for CI",
+        "verify --logs=all         Show all output",
+        "verify --init             Create config interactively",
+        "verify --init -y          Create config with all detected tasks",
+        "verify --init --force     Overwrite existing config",
+      ],
+    },
+  },
+  undefined,
+  undefined,
+)
 
 async function main() {
-  const args = process.argv.slice(2)
-  const options = parseArgs(args)
-
-  if (options.help) {
-    printHelp()
-    process.exit(0)
-  }
+  const { flags, _ } = argv
 
   // Handle --init command
-  if (options.init) {
+  if (flags.init) {
     try {
       const result = await runInit({
-        config: options.config,
-        force: options.force,
-        yes: options.yes,
+        config: flags.config,
+        force: flags.force,
+        yes: flags.yes,
         cwd: process.cwd(),
       })
       process.exit(result.success ? 0 : 1)
@@ -148,22 +118,38 @@ async function main() {
     }
   }
 
+  // Get task filter from named parameter
+  const task = _.task
+  const passthrough = _.passthrough
+
+  // Validate: passthrough requires a single task filter
+  if (passthrough && passthrough.length > 0 && !task) {
+    console.error("Error: Passthrough arguments (after --) require a task filter")
+    console.error("Usage: verify <task> -- [args...]")
+    process.exit(2)
+  }
+
   // Build verify options
   const verifyOptions = {
-    format: options.json ? "json" : "human",
+    format: flags.json ? "json" : "human",
     logs:
-      options.logs ??
-      (options.verbose ? "all" : options.quiet ? "none" : "failed"),
-    filter: options.filter.length > 0 ? options.filter : undefined,
-    cwd: options.config,
-    topLevelOnly: options.topLevelOnly,
-    noTty: options.noTty,
+      flags.logs ?? (flags.verbose ? "all" : flags.quiet ? "none" : "failed"),
+    filter: task ? [task] : undefined,
+    cwd: flags.config,
+    topLevelOnly: flags.topLevel,
+    noTty: flags.noTty,
+    passthrough: passthrough && passthrough.length > 0 ? passthrough : undefined,
   }
 
   try {
     const result = await verifyFromConfig(process.cwd(), verifyOptions)
     process.exit(result.ok ? 0 : 1)
   } catch (error) {
+    // Handle task not found / ambiguous task errors with exit code 2
+    if (error instanceof TaskNotFoundError || error instanceof AmbiguousTaskError) {
+      console.error(`Error: ${error.message}`)
+      process.exit(2)
+    }
     if (error instanceof Error) {
       console.error(`Error: ${error.message}`)
     } else {