@halecraft/verify 1.1.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
 
@@ -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;
 
@@ -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

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,27 @@ 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,
+    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;
 }
@@ -74,6 +77,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 +104,8 @@ interface VerifyOptions {
     topLevelOnly?: boolean;
     /** Force sequential output (disable live dashboard) */
     noTty?: boolean;
+    /** Arguments to pass through to the underlying command (requires single task filter) */
+    passthrough?: string[];
 }
 /**
  * Package discovery options for monorepos
@@ -115,6 +128,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
@@ -304,7 +323,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[];
 
@@ -605,7 +624,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
      */

package/dist/index.js

@@ -10,11 +10,12 @@ var ConfigError = class extends Error {
     this.name = "ConfigError";
   }
 };
+var EnvSchema = z.record(z.string(), z.string().nullable()).optional();
 var VerificationCommandSchema = z.object({
   cmd: z.string(),
   args: z.array(z.string()),
   cwd: z.string().optional(),
-  env: z.record(z.string(), z.string()).optional(),
+  env: EnvSchema,
   timeout: z.number().positive().optional()
 });
 var VerificationNodeSchema = z.lazy(
@@ -30,7 +31,8 @@ var VerificationNodeSchema = z.lazy(
     successLabel: z.string().optional(),
     failureLabel: z.string().optional(),
     reportingDependsOn: z.array(z.string()).optional(),
-    timeout: z.number().positive().optional()
+    timeout: z.number().positive().optional(),
+    env: EnvSchema
   })
 );
 var VerifyOptionsSchema = z.object({
@@ -40,7 +42,8 @@ var VerifyOptionsSchema = z.object({
   cwd: z.string().optional(),
   noColor: z.boolean().optional(),
   topLevelOnly: z.boolean().optional(),
-  noTty: z.boolean().optional()
+  noTty: z.boolean().optional(),
+  passthrough: z.array(z.string()).optional()
 });
 var PackageDiscoveryOptionsSchema = z.object({
   patterns: z.array(z.string()).optional(),
@@ -50,7 +53,8 @@ var PackageDiscoveryOptionsSchema = z.object({
 var VerifyConfigSchema = z.object({
   tasks: z.array(VerificationNodeSchema),
   packages: PackageDiscoveryOptionsSchema.optional(),
-  options: VerifyOptionsSchema.optional()
+  options: VerifyOptionsSchema.optional(),
+  env: EnvSchema
 });
 function validateConfig(value, configPath) {
   const result = VerifyConfigSchema.safeParse(value);
@@ -118,7 +122,8 @@ function mergeOptions(configOptions, cliOptions) {
     cwd: cliOptions?.cwd ?? configOptions?.cwd ?? process.cwd(),
     noColor: cliOptions?.noColor ?? configOptions?.noColor ?? false,
     topLevelOnly: cliOptions?.topLevelOnly ?? configOptions?.topLevelOnly ?? false,
-    noTty: cliOptions?.noTty ?? configOptions?.noTty ?? false
+    noTty: cliOptions?.noTty ?? configOptions?.noTty ?? false,
+    passthrough: cliOptions?.passthrough ?? configOptions?.passthrough
   };
 }
 
@@ -508,7 +513,7 @@ function extractOptimizedCommand(cwd, scriptContent) {
     const match = scriptContent.match(tool.pattern);
     if (match && binaryExists(cwd, tool.binary)) {
       const args = tool.getArgs(match, scriptContent);
-      const command = args ? `./node_modules/.bin/${tool.binary} ${args}` : `./node_modules/.bin/${tool.binary}`;
+      const command = args ? `${tool.binary} ${args}` : tool.binary;
       return { command, parser: tool.parser };
     }
   }
@@ -585,7 +590,7 @@ function detectTasks(cwd) {
   const packageManager = detectPackageManager(cwd);
   const tasks = detectFromPackageJson(cwd);
   return tasks.map((task) => {
-    if (task.command.startsWith("./")) {
+    if (!task.command.startsWith("npm run ")) {
       return task;
     }
     return {
@@ -621,12 +626,15 @@ function generateSkeleton(format) {
   return `${importStatement}
 
 export default defineConfig({
+  env: {
+    NO_COLOR: "1",
+  },
   tasks: [
     // Add your verification tasks here
     // Example:
-    // { 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" },
   ],
 })
 `;
@@ -641,6 +649,9 @@ function generateConfigContent(tasks, format) {
   return `${importStatement}
 
 export default defineConfig({
+  env: {
+    NO_COLOR: "1",
+  },
   tasks: [
 ${taskLines.join(",\n")},
   ],
@@ -1453,6 +1464,7 @@ function createReporter(options) {
 
 // src/runner.ts
 import { spawn } from "child_process";
+import { dirname, join as join4, resolve as resolve3 } from "path";
 import treeKill2 from "tree-kill";
 
 // src/dependency-tracker.ts
@@ -1634,9 +1646,9 @@ var ReportingDependencyTracker = class {
     if (this.results.has(pathOrKey)) {
       return Promise.resolve();
     }
-    return new Promise((resolve3) => {
+    return new Promise((resolve4) => {
       const waiters = this.waiters.get(pathOrKey) ?? [];
-      waiters.push(resolve3);
+      waiters.push(resolve4);
       this.waiters.set(pathOrKey, waiters);
     });
   }
@@ -1704,17 +1716,78 @@ var ReportingDependencyTracker = class {
 };
 
 // src/runner.ts
-function normalizeCommand(run, nodeTimeout) {
+function mergeEnv(base, overlay) {
+  if (!overlay) return { ...base };
+  const result = { ...base };
+  for (const [key, value] of Object.entries(overlay)) {
+    if (value === null) {
+      result[key] = null;
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function buildFinalEnv(processEnv, path, overlay) {
+  const result = {};
+  for (const [key, value] of Object.entries(processEnv)) {
+    if (value !== void 0) {
+      result[key] = value;
+    }
+  }
+  result.PATH = path;
+  if (overlay) {
+    for (const [key, value] of Object.entries(overlay)) {
+      if (value === null) {
+        delete result[key];
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+  return result;
+}
+function shellEscape(arg) {
+  if (/[\s"'`$\\!&|;<>(){}[\]*?#~]/.test(arg)) {
+    return `"${arg.replace(/"/g, '\\"')}"`;
+  }
+  return arg;
+}
+function buildNodeModulesPath(cwd) {
+  const pathSeparator = process.platform === "win32" ? ";" : ":";
+  const existingPath = process.env.PATH ?? "";
+  const binPaths = [];
+  let current = resolve3(cwd);
+  while (true) {
+    binPaths.push(join4(current, "node_modules", ".bin"));
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return [...binPaths, existingPath].join(pathSeparator);
+}
+function normalizeCommand(run, nodeTimeout, passthrough, inheritedEnv) {
   if (typeof run === "string") {
+    let cmd = run;
+    if (passthrough && passthrough.length > 0) {
+      const escapedArgs = passthrough.map(shellEscape).join(" ");
+      cmd = `${run} ${escapedArgs}`;
+    }
     return {
-      cmd: run,
+      cmd,
       args: [],
       shell: true,
-      timeout: nodeTimeout
+      timeout: nodeTimeout,
+      env: inheritedEnv
     };
   }
+  const args = passthrough ? [...run.args, ...passthrough] : run.args;
+  const env = mergeEnv(inheritedEnv ?? {}, run.env);
   return {
-    ...run,
+    cmd: run.cmd,
+    args,
+    cwd: run.cwd,
+    env: Object.keys(env).length > 0 ? env : void 0,
     shell: false,
     // Command-level timeout takes precedence over node-level timeout
     timeout: run.timeout ?? nodeTimeout
@@ -1722,12 +1795,18 @@ function normalizeCommand(run, nodeTimeout) {
 }
 async function executeCommand(command, cwd, tracker, path) {
   const start = Date.now();
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const useShell = command.shell || process.platform === "win32";
+    const effectiveCwd = command.cwd ?? cwd;
+    const finalEnv = buildFinalEnv(
+      process.env,
+      buildNodeModulesPath(effectiveCwd),
+      command.env
+    );
     const proc = spawn(command.cmd, command.args, {
       shell: useShell,
-      cwd: command.cwd ?? cwd,
-      env: { ...process.env, NO_COLOR: "1", ...command.env }
+      cwd: effectiveCwd,
+      env: finalEnv
     });
     if (tracker && path) {
       tracker.registerProcess(path, proc);
@@ -1760,7 +1839,7 @@ async function executeCommand(command, cwd, tracker, path) {
       }
       const durationMs = Date.now() - start;
       const killed = signal === "SIGTERM" || code === 143 || (tracker?.wasKilled(path ?? "") ?? false);
-      resolve3({
+      resolve4({
         code: code ?? 1,
         output,
         durationMs,
@@ -1777,7 +1856,7 @@ async function executeCommand(command, cwd, tracker, path) {
         tracker.unregisterProcess(path);
       }
       const durationMs = Date.now() - start;
-      resolve3({
+      resolve4({
         code: 1,
         output: `Failed to execute command: ${err.message}`,
         durationMs,
@@ -1812,11 +1891,13 @@ var VerificationRunner = class {
   options;
   callbacks;
   dependencyTracker;
-  constructor(options = {}, registry = defaultRegistry, callbacks = {}) {
+  configEnv;
+  constructor(options = {}, registry = defaultRegistry, callbacks = {}, configEnv = {}) {
     this.options = options;
     this.registry = registry;
     this.callbacks = callbacks;
     this.dependencyTracker = new ReportingDependencyTracker();
+    this.configEnv = configEnv;
   }
   /**
    * Run all verification tasks
@@ -1825,7 +1906,8 @@ var VerificationRunner = class {
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const wallStart = Date.now();
     this.dependencyTracker.initialize(tasks);
-    const results = await this.runNodes(tasks, "");
+    const baseEnv = mergeEnv({}, this.configEnv);
+    const results = await this.runNodes(tasks, "", "parallel", baseEnv);
     const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
     const durationMs = Date.now() - wallStart;
     const allOk = results.every((r) => r.ok);
@@ -1840,7 +1922,7 @@ var VerificationRunner = class {
   /**
    * Run a list of nodes with the appropriate strategy
    */
-  async runNodes(nodes, parentPath, strategy = "parallel") {
+  async runNodes(nodes, parentPath, strategy = "parallel", inheritedEnv = {}) {
     const filteredNodes = nodes.filter(
       (node) => hasMatchingDescendant(node, parentPath, this.options.filter)
     );
@@ -1850,19 +1932,21 @@ var VerificationRunner = class {
     switch (strategy) {
       case "parallel":
         return Promise.all(
-          filteredNodes.map((node) => this.runNode(node, parentPath))
+          filteredNodes.map(
+            (node) => this.runNode(node, parentPath, inheritedEnv)
+          )
         );
       case "sequential": {
         const results = [];
         for (const node of filteredNodes) {
-          results.push(await this.runNode(node, parentPath));
+          results.push(await this.runNode(node, parentPath, inheritedEnv));
         }
         return results;
       }
       case "fail-fast": {
         const results = [];
         for (const node of filteredNodes) {
-          const result = await this.runNode(node, parentPath);
+          const result = await this.runNode(node, parentPath, inheritedEnv);
           results.push(result);
           if (!result.ok) {
             break;
@@ -1875,8 +1959,9 @@ var VerificationRunner = class {
   /**
    * Run a single node (leaf or group)
    */
-  async runNode(node, parentPath) {
+  async runNode(node, parentPath, inheritedEnv = {}) {
     const path = buildTaskPath(parentPath, node.key);
+    const nodeEnv = mergeEnv(inheritedEnv, node.env);
     this.dependencyTracker.markActive(path);
     this.callbacks.onTaskStart?.(path, node.key);
     if (node.children && node.children.length > 0) {
@@ -1884,7 +1969,8 @@ var VerificationRunner = class {
       const childResults = await this.runNodes(
         node.children,
         path,
-        node.strategy ?? "parallel"
+        node.strategy ?? "parallel",
+        nodeEnv
       );
       const durationMs2 = Date.now() - start;
       const allOk = childResults.every((r) => r.ok || r.suppressed);
@@ -1923,7 +2009,13 @@ var VerificationRunner = class {
       this.callbacks.onTaskComplete?.(result2);
       return result2;
     }
-    const command = normalizeCommand(node.run, node.timeout);
+    const passthrough = this.options.passthrough;
+    const command = normalizeCommand(
+      node.run,
+      node.timeout,
+      passthrough,
+      nodeEnv
+    );
     const cwd = this.options.cwd ?? process.cwd();
     const { code, output, durationMs, killed, timedOut } = await executeCommand(
       command,
@@ -2021,10 +2113,15 @@ async function verify(config, cliOptions) {
   }
   const reporter = createReporter(options);
   reporter.onStart?.(config.tasks);
-  const runner = new VerificationRunner(options, void 0, {
-    onTaskStart: (path, key) => reporter.onTaskStart(path, key),
-    onTaskComplete: (result2) => reporter.onTaskComplete(result2)
-  });
+  const runner = new VerificationRunner(
+    options,
+    void 0,
+    {
+      onTaskStart: (path, key) => reporter.onTaskStart(path, key),
+      onTaskComplete: (result2) => reporter.onTaskComplete(result2)
+    },
+    config.env
+  );
   const result = await runner.run(config.tasks);
   reporter.onFinish?.();
   reporter.outputLogs(result.tasks, options.logs ?? "failed");