@halecraft/verify 1.1.0 → 1.3.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
 
@@ -65,6 +65,9 @@ pnpm exec verify types:tsc
 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
 
@@ -94,10 +97,16 @@ interface VerificationNode {
   name?: string;
 
   // Command to run (leaf nodes only)
-  // Supports: string, object with cmd/args/cwd/timeout
+  // Supports: string, object with cmd/args/cwd/env/timeout
   run?:
     | string
-    | { cmd: string; args: string[]; cwd?: string; timeout?: number };
+    | {
+        cmd: string;
+        args: string[];
+        cwd?: string;
+        env?: Record<string, string | null>;
+        timeout?: number;
+      };
 
   // Child tasks (for grouping)
   children?: VerificationNode[];
@@ -114,6 +123,10 @@ interface VerificationNode {
   // 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;
 
@@ -122,9 +135,9 @@ interface VerificationNode {
 }
 ```
 
-### Smart Output Suppression with `reportingDependsOn`
+### Dependency-Aware Failure Reporting with `reportingDependsOn`
 
-When a syntax error occurs, multiple tools often report the same underlying issue (Biome, tsc, esbuild all complaining about the same missing comma). The `reportingDependsOn` option reduces this noise by suppressing redundant failure output.
+When a syntax error occurs, multiple tools often report the same underlying issue (Biome, tsc, esbuild all complaining about the same missing comma). The `reportingDependsOn` option reduces this noise by marking dependent failures as blocked.
 
 ```typescript
 import { defineConfig } from "@halecraft/verify";
@@ -143,17 +156,17 @@ export default defineConfig({
 
 - All tasks still execute in parallel (no speed regression)
 - When a dependency fails (e.g., `format`), dependent tasks are terminated early for faster feedback
-- Dependent tasks that also fail are marked as "suppressed"
+- Dependent tasks that also fail are marked as "blocked"
 - Only the root cause failure shows detailed logs
-- Suppressed tasks show `⊘ suppressed` instead of `✗ failed`
+- Blocked tasks show `⊘ blocked` instead of `✗ failed`
 
 **Before (noisy):**
 
 ```
-✗ format (syntax error at line 14)
-✗ types (syntax error at line 14)
-✗ logic (syntax error at line 14)
-✗ build (syntax error at line 14)
+✗ format failed (syntax error at line 14)
+✗ types failed (syntax error at line 14)
+✗ logic failed (syntax error at line 14)
+✗ build failed (syntax error at line 14)
 
 ==== FORMAT FAIL ====
 [50 lines of biome output]
@@ -171,10 +184,10 @@ export default defineConfig({
 **After (clean):**
 
 ```
-✗ format (syntax error at line 14)
-⊘ types (suppressed - format failed)
-⊘ logic (suppressed - format failed)
-⊘ build (suppressed - format failed)
+✗ format failed (syntax error at line 14)
+⊘ types blocked (by format, 120ms)
+⊘ logic blocked (by format, 150ms)
+⊘ build blocked (by format, 130ms)
 
 ==== FORMAT FAIL ====
 [50 lines of biome output]
@@ -264,13 +277,66 @@ When a command exceeds its timeout:
 
 **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
@@ -278,13 +344,39 @@ 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
@@ -377,8 +469,8 @@ interface TaskResult {
   durationMs: number; // Duration in milliseconds
   output: string; // Raw output
   summaryLine: string; // Parsed summary
-  suppressed?: boolean; // True if output was suppressed
-  suppressedBy?: string; // Path of dependency that caused suppression
+  blocked?: boolean; // True if blocked by a dependency failure
+  blockedBy?: string; // Path of dependency that caused the block
   timedOut?: boolean; // True if task exceeded its timeout
   children?: TaskResult[]; // Child results (for group nodes)
 }

package/bin/verify.mjs

@@ -14,6 +14,12 @@ const argv = cli(
     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
+    ],
+
     flags: {
       json: {
         type: Boolean,
@@ -52,12 +58,6 @@ const argv = cli(
         alias: "c",
         description: "Path to config file (or output path for --init)",
       },
-      filter: {
-        type: [String],
-        alias: "f",
-        description: "Filter to specific task paths",
-        default: [],
-      },
       init: {
         type: Boolean,
         description: "Initialize a new verify.config.ts file",
@@ -81,6 +81,7 @@ const argv = cli(
         "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",
@@ -117,18 +118,28 @@ async function main() {
     }
   }
 
-  // Combine --filter flags with positional arguments
-  const allFilters = [...flags.filter, ..._]
+  // 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: flags.json ? "json" : "human",
     logs:
       flags.logs ?? (flags.verbose ? "all" : flags.quiet ? "none" : "failed"),
-    filter: allFilters.length > 0 ? allFilters : undefined,
+    filter: task ? [task] : undefined,
     cwd: flags.config,
     topLevelOnly: flags.topLevel,
     noTty: flags.noTty,
+    quiet: flags.quiet,
+    passthrough: passthrough && passthrough.length > 0 ? passthrough : undefined,
   }
 
   try {

package/dist/index.d.ts

@@ -8,8 +8,11 @@ interface VerificationCommand {
     args: string[];
     /** Working directory (defaults to cwd) */
     cwd?: string;
-    /** Environment variables to set */
-    env?: Record<string, string>;
+    /**
+     * Environment variables to set.
+     * Set to null to explicitly unset an inherited variable.
+     */
+    env?: Record<string, string | null>;
     /** Timeout in milliseconds (process killed with SIGTERM if exceeded) */
     timeout?: number;
 }
@@ -23,6 +26,7 @@ interface ParsedResult {
     metrics?: {
         passed?: number;
         failed?: number;
+        skipped?: number;
         total?: number;
         duration?: string;
         errors?: number;
@@ -64,7 +68,7 @@ interface VerificationNode {
     failureLabel?: string;
     /**
      * Tasks that must pass for this task's failure to be reported.
-     * If any dependency fails, this task's failure output is suppressed.
+     * If any dependency fails, this task's failure is marked as blocked.
      * Can specify task keys (e.g., "format") or full paths (e.g., "types:tsc").
      */
     reportingDependsOn?: string[];
@@ -74,6 +78,14 @@ interface VerificationNode {
      * For VerificationCommand objects, use the timeout field on the command itself.
      */
     timeout?: number;
+    /**
+     * Environment variables for this task and its children.
+     * Inherits from parent tasks and config-level env.
+     * Child tasks can override parent values.
+     * Set to null to explicitly unset an inherited variable.
+     * For VerificationCommand objects, command-level env takes precedence.
+     */
+    env?: Record<string, string | null>;
 }
 /**
  * Options for the verification runner
@@ -93,6 +105,10 @@ interface VerifyOptions {
     topLevelOnly?: boolean;
     /** Force sequential output (disable live dashboard) */
     noTty?: boolean;
+    /** Suppress in-progress output, show only final summary */
+    quiet?: boolean;
+    /** Arguments to pass through to the underlying command (requires single task filter) */
+    passthrough?: string[];
 }
 /**
  * Package discovery options for monorepos
@@ -115,6 +131,12 @@ interface VerifyConfig {
     packages?: PackageDiscoveryOptions;
     /** Default options */
     options?: VerifyOptions;
+    /**
+     * Global environment variables applied to all tasks.
+     * Set to null to explicitly unset an inherited variable.
+     * Recommend setting NO_COLOR: "1" here to disable colors in output.
+     */
+    env?: Record<string, string | null>;
 }
 /**
  * Result of a single verification task
@@ -139,15 +161,15 @@ interface TaskResult {
     /** Child results (for group nodes) */
     children?: TaskResult[];
     /**
-     * Whether this task's failure output was suppressed due to a dependency failure.
-     * The task still ran and failed, but its output is hidden to reduce noise.
+     * Whether this task's failure was blocked by a dependency failure.
+     * The task ran but its failure output is hidden because the root cause is the dependency.
      */
-    suppressed?: boolean;
+    blocked?: boolean;
     /**
-     * The path of the dependency task that caused this task to be suppressed.
-     * Only set when suppressed is true.
+     * The path of the dependency task that caused this task to be blocked.
+     * Only set when blocked is true.
      */
-    suppressedBy?: string;
+    blockedBy?: string;
     /**
      * Whether this task was terminated due to timeout.
      * Only set when the task exceeded its configured timeout.
@@ -304,7 +326,7 @@ interface DetectedTask {
 }
 /**
  * Detect tasks with proper package manager commands
- * Uses optimized direct paths when possible, falls back to package manager
+ * Uses optimized direct binary names when possible, falls back to package manager
  */
 declare function detectTasks(cwd: string): DetectedTask[];
 
@@ -450,6 +472,14 @@ interface Reporter {
     /** Called to output final summary */
     outputSummary(result: VerifyResult): void;
 }
+/**
+ * Terminal capability context — the single point where globals are read.
+ * Passed to pure decision functions for testability.
+ */
+interface TerminalContext {
+    isTTY: boolean;
+    env: Record<string, string | undefined>;
+}
 /**
  * Base Reporter - common functionality for all reporters
  */
@@ -457,7 +487,7 @@ declare abstract class BaseReporter implements Reporter {
     protected colorEnabled: boolean;
     protected stream: NodeJS.WriteStream;
     protected taskDepths: Map<string, number>;
-    constructor(options?: VerifyOptions);
+    constructor(options?: VerifyOptions, ctx?: TerminalContext);
     /**
      * Apply ANSI color code to string (if colors enabled)
      */
@@ -471,9 +501,9 @@ declare abstract class BaseReporter implements Reporter {
      */
     protected failMark(): string;
     /**
-     * Get suppressed mark (⊘ or SUPPRESSED)
+     * Get blocked mark (⊘ or BLOCK)
      */
-    protected suppressedMark(): string;
+    protected blockedMark(): string;
     /**
      * Get arrow symbol (→ or ->)
      */
@@ -490,6 +520,11 @@ declare abstract class BaseReporter implements Reporter {
      * Collect task depths from verification tree using walkNodes
      */
     protected collectTaskDepths(nodes: VerificationNode[]): void;
+    /**
+     * Format a completed task result line in name-first format.
+     * Shared by LiveDashboardReporter and SequentialReporter.
+     */
+    protected formatResultLine(name: string, result: TaskResult): string;
     /**
      * Extract summary from task result
      */
@@ -520,7 +555,7 @@ declare class LiveDashboardReporter extends BaseReporter {
     private taskOrder;
     private spinner;
     private lineCount;
-    constructor(options?: VerifyOptions);
+    constructor(options?: VerifyOptions, ctx?: TerminalContext);
     /**
      * Initialize task list from verification nodes
      */
@@ -555,7 +590,7 @@ declare class LiveDashboardReporter extends BaseReporter {
  */
 declare class SequentialReporter extends BaseReporter {
     private topLevelOnly;
-    constructor(options?: VerifyOptions);
+    constructor(options?: VerifyOptions, ctx?: TerminalContext);
     onStart(tasks: VerificationNode[]): void;
     /**
      * Check if task should be displayed based on topLevelOnly flag
@@ -589,7 +624,9 @@ declare class QuietReporter extends BaseReporter {
     outputSummary(result: VerifyResult): void;
 }
 /**
- * Create appropriate reporter based on options
+ * Create appropriate reporter based on options.
+ *
+ * Decision tree: JSON → Quiet → LiveDashboard → Sequential
  */
 declare function createReporter(options: VerifyOptions): Reporter;
 
@@ -605,7 +642,8 @@ declare class VerificationRunner {
     private options;
     private callbacks;
     private dependencyTracker;
-    constructor(options?: VerifyOptions, registry?: ParserRegistry, callbacks?: RunnerCallbacks);
+    private configEnv;
+    constructor(options?: VerifyOptions, registry?: ParserRegistry, callbacks?: RunnerCallbacks, configEnv?: Record<string, string | null>);
     /**
      * Run all verification tasks
      */
@@ -655,4 +693,4 @@ declare function verify(config: VerifyConfig, cliOptions?: Partial<VerifyOptions
  */
 declare function verifyFromConfig(cwd?: string, cliOptions?: Partial<VerifyOptions>): Promise<VerifyResult>;
 
-export { AmbiguousTaskError, ConfigError, type DetectedTask, type DiscoveredPackage, type ExecutionStrategy, type InitOptions, type InitResult, JSONReporter, LiveDashboardReporter, type NodeVisitor, type OutputFormat, type OutputParser, PATH_SEPARATOR, type PackageDiscoveryOptions, type ParsedResult, type ParserId, ParserRegistry, QuietReporter, type Reporter, type ResolvedFilter, type RunnerCallbacks, SequentialReporter, SequentialReporter as TTYReporter, TaskNotFoundError, type TaskResult, type VerificationCommand, type VerificationNode, VerificationRunner, type VerifyConfig, type VerifyOptions, type VerifyResult, biomeParser, buildTaskPath, collectPaths, createReporter, defaultRegistry, defineConfig, defineTask, detectTasks, discoverPackages, findBestSuggestion, findConfigFile, generateConfigContent, genericParser, gotestParser, hasPackageChanged, loadConfig, loadConfigFromCwd, mergeOptions, parsers, resolveFilters, runInit, tscParser, validateConfig, verify, verifyFromConfig, vitestParser, walkNodes };
+export { AmbiguousTaskError, ConfigError, type DetectedTask, type DiscoveredPackage, type ExecutionStrategy, type InitOptions, type InitResult, JSONReporter, LiveDashboardReporter, type NodeVisitor, type OutputFormat, type OutputParser, PATH_SEPARATOR, type PackageDiscoveryOptions, type ParsedResult, type ParserId, ParserRegistry, QuietReporter, type Reporter, type ResolvedFilter, type RunnerCallbacks, SequentialReporter, SequentialReporter as TTYReporter, TaskNotFoundError, type TaskResult, type TerminalContext, type VerificationCommand, type VerificationNode, VerificationRunner, type VerifyConfig, type VerifyOptions, type VerifyResult, biomeParser, buildTaskPath, collectPaths, createReporter, defaultRegistry, defineConfig, defineTask, detectTasks, discoverPackages, findBestSuggestion, findConfigFile, generateConfigContent, genericParser, gotestParser, hasPackageChanged, loadConfig, loadConfigFromCwd, mergeOptions, parsers, resolveFilters, runInit, tscParser, validateConfig, verify, verifyFromConfig, vitestParser, walkNodes };