@visulima/task-runner 1.0.0-alpha.3 → 1.0.0-alpha.4

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+## @visulima/task-runner [1.0.0-alpha.4](https://github.com/visulima/visulima/compare/@visulima/task-runner@1.0.0-alpha.3...@visulima/task-runner@1.0.0-alpha.4) (2026-04-08)
+
+### Features
+
+* Add native Rust bindings for package manager operations ([#596](https://github.com/visulima/visulima/issues/596)) ([2ec22d0](https://github.com/visulima/visulima/commit/2ec22d023eade3fed67fb811696fbd8f7b52569d))
+* **task-runner, vis:** project constraints, CI partitioning, affected scopes ([29295e9](https://github.com/visulima/visulima/commit/29295e989ecdfe2019469d1917a6c90a92e17bcf))
+* **task-runner:** add concurrent process runner with Rust NAPI bindings ([c4f5d93](https://github.com/visulima/visulima/commit/c4f5d930e81a5eb641ceb3ab925c3b10a885bb6a))
+* **vis:** expand devcontainer command with templates, validation, and config properties ([807e730](https://github.com/visulima/visulima/commit/807e730a43f0ea644d016b4f5506706972d2ff41))
+* **vis:** group CLI commands into logical categories for help output ([0a4cac8](https://github.com/visulima/visulima/commit/0a4cac859c8edf7aacdacca7b9a03219967d525a))
+* **vis:** replace inline TUI with full-screen Nx-style interactive task runner ([1409aad](https://github.com/visulima/visulima/commit/1409aad879c713051bba12298a3feb1d5ba852f2))
+
+### Bug Fixes
+
+* **ci:** make native-binding tests work with and without compiled binary ([9a40fb4](https://github.com/visulima/visulima/commit/9a40fb40d5cba9fcd2e0176eea8b7bf8d9792c7d))
+* **task-runner,tui:** guard null native events and increase CI test timeout ([e76a791](https://github.com/visulima/visulima/commit/e76a791d90043537e08be0545f706e35acaa555d))
+* **task-runner:** deno.json support, Windows Job Objects, docs, and review fixes ([4fb27f0](https://github.com/visulima/visulima/commit/4fb27f081b4b50b41dbb86b5b1a962b63f7a6df3))
+* **task-runner:** fix Windows cross-compilation by upgrading windows-sys to 0.61 ([b56b95e](https://github.com/visulima/visulima/commit/b56b95e2a39ca972398859e6eb87e528f4463d97))
+* **task-runner:** resolve eslint errors ([f0a21a6](https://github.com/visulima/visulima/commit/f0a21a689bc9e1d8b091a513e21cb11b77103ba4))
+* **task-runner:** use JS fallback for onEvent streaming, fix StaticRender ref ([1a7165c](https://github.com/visulima/visulima/commit/1a7165cd9eb71472895cd08682983fa25703dc93))
+* **tsconfig:** add node types and fix implicit any parameter ([1744d82](https://github.com/visulima/visulima/commit/1744d82a07fca03f2e6ff660b918e9b2623acf69))
+
+### Miscellaneous Chores
+
+* added og images ([02d9d1e](https://github.com/visulima/visulima/commit/02d9d1e47be3ce75679ea89e857dc4e4bfe4946b))
+* **task-runner:** add tsconfig.eslint.json for type-aware linting ([83e0bf2](https://github.com/visulima/visulima/commit/83e0bf23511a169b801f6edf652a8be7ee968c24))
+* **task-runner:** apply prettier formatting ([521afc2](https://github.com/visulima/visulima/commit/521afc22d94a2626c7246062cecfc0627f929ee4))
+* **task-runner:** expand inline if-return to block syntax ([0f48a96](https://github.com/visulima/visulima/commit/0f48a96ed11d7339c62f3f147c7b2c8fcc605b03))
+* **task-runner:** migrate .prettierrc.cjs to prettier.config.js ([cd1c045](https://github.com/visulima/visulima/commit/cd1c045e133f685a274924034ec70cf374edd5ba))
+
+### Build System
+
+* regenerate NAPI-RS bindings as ESM ([f202caf](https://github.com/visulima/visulima/commit/f202caf3dc383a2ec24815c4935d8d68c29f33d0))
+* switch NAPI-RS native builds to ESM output ([3d7cd61](https://github.com/visulima/visulima/commit/3d7cd615ad830392005915735c11771e0247ef3f))
+* **task-runner:** move publish-native-addons to shared scripts/ ([73b5482](https://github.com/visulima/visulima/commit/73b5482e1ca0707aa8f191429deffbd7324a632d))
+
+
+### Dependencies
+
+* **@visulima/humanizer:** upgraded to 3.0.0-alpha.9
+* **@visulima/path:** upgraded to 3.0.0-alpha.8
+
 ## @visulima/task-runner [1.0.0-alpha.3](https://github.com/visulima/visulima/compare/@visulima/task-runner@1.0.0-alpha.2...@visulima/task-runner@1.0.0-alpha.3) (2026-03-26)
 
 ### Features

package/README.md

@@ -27,11 +27,17 @@
 
 ## Features
 
+- **Concurrent process runner**: Run multiple commands in parallel with native Rust performance (NAPI bindings) and JS fallback
+- **Process tree management**: Proper cleanup via setsid/killpg (Unix) and Job Objects (Windows)
+- **Command parser pipeline**: `npm:build` shortcuts, `npm run watch-*` wildcard expansion, `{1}` argument placeholders
+- **Flow controllers**: Restart with backoff, stdin routing, timing summaries, teardown commands
+- **npm script-shell support**: Honors `npm config set script-shell` for custom shells (Git Bash, etc.)
+- **Long-running process support**: Configurable stdin mode (null/pipe/inherit), bounded output buffers
 - **Two caching modes**: Nx-style explicit inputs or Vite Task-style auto-fingerprinting
 - **Smart lockfile hashing**: Only hashes resolved versions relevant to each package (like Turborepo)
 - **Framework env inference**: Auto-detects Next.js, Vite, CRA, Gatsby, Nuxt, and more
 - **Remote caching**: Turborepo-compatible HTTP cache protocol
-- **Native Rust addon**: Optional xxHash-based parallel file hashing via napi-rs
+- **Native Rust addon**: Parallel file hashing (xxHash), concurrent process management via tokio
 - **Dependency-aware scheduling**: Topological task ordering with priority-based batching
 - **Incremental file hashing**: mtime-based change detection for near-instant cache checks
 - **Affected detection**: Git diff-based filtering to only run tasks for changed packages
@@ -61,32 +67,144 @@ pnpm add @visulima/task-runner
 ```typescript
 import { defaultTaskRunner } from "@visulima/task-runner";
 
-const results = await defaultTaskRunner(tasks, {
-    // Nx-style: explicit inputs
-    namedInputs: {
-        production: ["{projectRoot}/src/**/*"],
+const results = await defaultTaskRunner(
+    tasks,
+    {
+        // Nx-style: explicit inputs
+        namedInputs: {
+            production: ["{projectRoot}/src/**/*"],
+        },
+        globalInputs: ["pnpm-lock.yaml", "tsconfig.base.json"],
+        globalEnv: ["NODE_ENV"],
+
+        // Or: auto-fingerprinting (Vite Task-style)
+        // autoFingerprint: true,
+
+        // Smart lockfile hashing (only bust cache for affected packages)
+        smartLockfileHashing: true,
+
+        // Auto-detect framework env vars (NEXT_PUBLIC_*, VITE_*, etc.)
+        frameworkInference: true,
+
+        // Remote cache (Turborepo-compatible)
+        remoteCache: {
+            url: "https://cache.example.com",
+            token: process.env.CACHE_TOKEN,
+            teamId: "my-team",
+        },
     },
-    globalInputs: ["pnpm-lock.yaml", "tsconfig.base.json"],
-    globalEnv: ["NODE_ENV"],
-
-    // Or: auto-fingerprinting (Vite Task-style)
-    // autoFingerprint: true,
+    context,
+);
+```
 
-    // Smart lockfile hashing (only bust cache for affected packages)
-    smartLockfileHashing: true,
+## Concurrent Process Runner
 
-    // Auto-detect framework env vars (NEXT_PUBLIC_*, VITE_*, etc.)
-    frameworkInference: true,
+Run multiple commands in parallel with real-time output streaming, process tree management, and automatic native acceleration.
 
-    // Remote cache (Turborepo-compatible)
-    remoteCache: {
-        url: "https://cache.example.com",
-        token: process.env.CACHE_TOKEN,
-        teamId: "my-team",
+```typescript
+import { runConcurrently } from "@visulima/task-runner";
+
+// Basic usage
+const result = await runConcurrently(["npm run build", "npm run test", "npm run lint"]);
+console.log(result.success ? "All passed" : "Some failed");
+
+// With options
+const result = await runConcurrently(
+    [
+        { command: "vite dev", name: "web", stdin: "inherit" },
+        { command: "node api.js", name: "api" },
+    ],
+    {
+        maxProcesses: 4,
+        killOthers: ["failure"], // Kill all if one fails
+        successCondition: "all", // All must exit 0
+        onEvent: (event) => {
+            // Real-time streaming
+            if (event.kind === "stdout") {
+                console.log(`[${event.index}] ${event.text}`);
+            }
+        },
     },
-}, context);
+);
+```
+
+### Command Parser
+
+Use `parseCommands` to expand shortcuts and wildcards before passing to `runConcurrently`:
+
+```typescript
+import { parseCommands, runConcurrently } from "@visulima/task-runner";
+
+const commands = parseCommands([
+    "npm:build", // -> npm run build
+    "pnpm:test", // -> pnpm run test
+    '"quoted command"', // -> quoted command (quotes stripped)
+    "npm run watch-*", // -> expands to all matching scripts in package.json
+    "deno task dev-*", // -> expands from deno.json/deno.jsonc tasks
+]);
+
+await runConcurrently(commands);
+```
+
+### Flow Controllers
+
+```typescript
+import { runConcurrently } from "@visulima/task-runner";
+
+// Restart failed commands with exponential backoff
+await runConcurrently(["flaky-command"], {
+    restart: { tries: 3, delay: "exponential" },
+});
+
+// Print timing summary after completion
+await runConcurrently(["npm run build", "npm run test"], {
+    timings: true,
+});
+
+// Run cleanup commands after all processes finish
+await runConcurrently(["npm run dev"], {
+    teardown: ["docker compose down", "rm -rf .cache"],
+});
 ```
 
+### Shell Configuration
+
+The runner automatically detects `npm config set script-shell` for custom shells (e.g., Git Bash on Windows):
+
+```typescript
+import { runConcurrently, detectScriptShell } from "@visulima/task-runner";
+
+// Auto-detected from npm config
+await runConcurrently(["echo hello"]);
+
+// Or override explicitly
+await runConcurrently(["echo hello"], {
+    shellPath: "/usr/bin/bash",
+});
+```
+
+### Stdin Modes
+
+For long-running processes like dev servers:
+
+```typescript
+await runConcurrently([
+    { command: "vite dev", stdin: "inherit" }, // Child reads terminal directly
+    { command: "node worker.js", stdin: "null" }, // No stdin (default)
+    { command: "node repl.js", stdin: "pipe" }, // Programmatic stdin access
+]);
+```
+
+### Native vs Fallback
+
+The runner automatically uses the Rust NAPI addon when available for:
+
+- Process tree killing via setsid/killpg (Unix) and Job Objects (Windows)
+- Async I/O multiplexing via tokio
+- Signal propagation (SIGINT/SIGTERM/SIGHUP)
+
+Falls back to a pure JavaScript implementation when the native addon is not compiled.
+
 ## Caching Modes
 
 ### Nx-style (explicit inputs)
@@ -94,19 +212,19 @@ const results = await defaultTaskRunner(tasks, {
 Declare which files, env vars, and runtime values should be included in the cache hash:
 
 ```typescript
-const results = await defaultTaskRunner(tasks, {
-    namedInputs: {
-        production: [
-            "{projectRoot}/src/**/*",
-            { env: "NODE_ENV" },
-            { runtime: "node --version" },
-        ],
-    },
-    targetDefaults: {
-        build: { inputs: ["production"] },
-        test: { inputs: ["production", "{projectRoot}/**/*.test.ts"] },
+const results = await defaultTaskRunner(
+    tasks,
+    {
+        namedInputs: {
+            production: ["{projectRoot}/src/**/*", { env: "NODE_ENV" }, { runtime: "node --version" }],
+        },
+        targetDefaults: {
+            build: { inputs: ["production"] },
+            test: { inputs: ["production", "{projectRoot}/**/*.test.ts"] },
+        },
     },
-}, context);
+    context,
+);
 ```
 
 ### Auto-fingerprint (Vite Task-style)
@@ -114,11 +232,15 @@ const results = await defaultTaskRunner(tasks, {
 Automatically tracks which files a task accesses during execution:
 
 ```typescript
-const results = await defaultTaskRunner(tasks, {
-    autoFingerprint: true,
-    fingerprintEnvPatterns: ["VITE_*", "NODE_ENV"],
-    cacheDiagnostics: true, // Shows why cache misses occur
-}, context);
+const results = await defaultTaskRunner(
+    tasks,
+    {
+        autoFingerprint: true,
+        fingerprintEnvPatterns: ["VITE_*", "NODE_ENV"],
+        cacheDiagnostics: true, // Shows why cache misses occur
+    },
+    context,
+);
 ```
 
 ## API
@@ -127,27 +249,47 @@ const results = await defaultTaskRunner(tasks, {
 
 The main entry point. Runs tasks with caching, scheduling, and lifecycle support.
 
+### `runConcurrently(commands, options?)`
+
+Run commands concurrently with process management and output streaming.
+
+| Option             | Type                         | Description                                         |
+| ------------------ | ---------------------------- | --------------------------------------------------- |
+| `maxProcesses`     | `number`                     | Max simultaneous processes (0 = unlimited)          |
+| `killOthers`       | `("failure" \| "success")[]` | Kill others when a process exits                    |
+| `killSignal`       | `string`                     | Signal for killing (default: "SIGTERM")             |
+| `killTimeout`      | `number`                     | Ms before SIGKILL after kill signal (default: 5000) |
+| `successCondition` | `string`                     | "all", "first", "last", "command-\<name\>"          |
+| `shellPath`        | `string`                     | Custom shell path (auto-detected from npm config)   |
+| `restart`          | `{ tries, delay }`           | Restart failed commands with backoff                |
+| `teardown`         | `string[]`                   | Cleanup commands to run after completion            |
+| `timings`          | `boolean`                    | Print timing summary table                          |
+| `onEvent`          | `(event) => void`            | Real-time stdout/stderr/close/error events          |
+
 ### Key Options
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `parallel` | `number \| boolean` | Max parallel tasks (default: 3) |
-| `smartLockfileHashing` | `boolean` | Hash only relevant lockfile entries per package |
-| `frameworkInference` | `boolean` | Auto-detect framework env var prefixes |
-| `autoFingerprint` | `boolean` | Enable Vite Task-style auto-fingerprinting |
-| `globalInputs` | `string[]` | Files that invalidate all caches when changed |
-| `globalEnv` | `string[]` | Env vars that invalidate all caches |
-| `remoteCache` | `object` | Remote cache server configuration |
-| `dryRun` | `boolean` | Compute hashes without executing |
-| `summarize` | `boolean` | Generate JSON run summary |
-| `cacheDiagnostics` | `boolean` | Log cache miss reasons |
-| `maxCacheSize` | `string` | Max cache size (e.g., "1GB") |
-| `maxCacheAge` | `number` | Max cache entry age in ms |
+| Option                 | Type                | Description                                     |
+| ---------------------- | ------------------- | ----------------------------------------------- |
+| `parallel`             | `number \| boolean` | Max parallel tasks (default: 3)                 |
+| `smartLockfileHashing` | `boolean`           | Hash only relevant lockfile entries per package |
+| `frameworkInference`   | `boolean`           | Auto-detect framework env var prefixes          |
+| `autoFingerprint`      | `boolean`           | Enable Vite Task-style auto-fingerprinting      |
+| `globalInputs`         | `string[]`          | Files that invalidate all caches when changed   |
+| `globalEnv`            | `string[]`          | Env vars that invalidate all caches             |
+| `remoteCache`          | `object`            | Remote cache server configuration               |
+| `dryRun`               | `boolean`           | Compute hashes without executing                |
+| `summarize`            | `boolean`           | Generate JSON run summary                       |
+| `cacheDiagnostics`     | `boolean`           | Log cache miss reasons                          |
+| `maxCacheSize`         | `string`            | Max cache size (e.g., "1GB")                    |
+| `maxCacheAge`          | `number`            | Max cache entry age in ms                       |
 
 ### Exports
 
 The package exports many building blocks for custom task runners:
 
+- **Concurrent Runner**: `runConcurrently`, `runConcurrentFallback`, `detectScriptShell`
+- **Command Parser**: `parseCommands`, `expandShortcut`, `expandWildcard`, `expandArguments`, `stripQuotes`
+- **Flow Controllers**: `withRestart`, `createInputHandler`, `logTimings`, `formatTimingTable`, `runTeardown`
 - **Task Graph**: `createTaskGraph`, `findCycle`, `walkTaskGraph`, `makeAcyclic`
 - **Hashing**: `InProcessTaskHasher`, `IncrementalFileHasher`, `computeTaskHash`
 - **Caching**: `Cache`, `RemoteCache`, `FingerprintManager`

package/dist/affected.d.ts

@@ -1,16 +1,26 @@
-import type { ProjectConfiguration, ProjectGraph } from "./types.d.ts";
+import type { AffectedScope, ProjectConfiguration, ProjectGraph } from "./types.d.ts";
 /**
  * Options for determining affected projects.
  */
 interface AffectedOptions {
     /** The base ref to compare against (default: "main") */
     base?: string;
+    /**
+     * Control how far downstream (dependents of changed projects) to include.
+     * @default "deep"
+     */
+    downstream?: AffectedScope;
     /** The head ref to compare (default: "HEAD") */
     head?: string;
     /** Project graph for dependency resolution */
     projectGraph: ProjectGraph;
     /** All project configurations keyed by name */
     projects: Record<string, ProjectConfiguration>;
+    /**
+     * Control how far upstream (dependencies of changed projects) to include.
+     * @default "none"
+     */
+    upstream?: AffectedScope;
     /** The workspace root directory */
     workspaceRoot: string;
 }
@@ -18,13 +28,37 @@ interface AffectedOptions {
  * Result of affected detection.
  */
 interface AffectedResult {
-    /** Projects affected by changes (including transitive dependents) */
+    /** All affected projects (union of changed, downstream, and upstream) */
     affectedProjects: string[];
     /** Files that changed between base and head */
     changedFiles: string[];
     /** Projects that were directly changed */
     changedProjects: string[];
+    /** Projects affected because they depend on changed projects */
+    downstreamProjects: string[];
+    /** Projects that changed projects depend on */
+    upstreamProjects: string[];
 }
+/**
+ * Builds a map from each project to the set of projects that depend on it (reverse/downstream).
+ */
+declare const buildReverseDependencyMap: (projectGraph: ProjectGraph) => Map<string, Set<string>>;
+/**
+ * Builds a map from each project to the set of projects it depends on (forward/upstream).
+ */
+declare const buildForwardDependencyMap: (projectGraph: ProjectGraph) => Map<string, Set<string>>;
+/**
+ * Expands a set of changed projects based on upstream/downstream scope settings.
+ * Returns a new set containing all affected projects.
+ */
+declare const expandAffected: (changedProjects: Set<string>, projectGraph: ProjectGraph, options: {
+    downstream: AffectedScope;
+    upstream: AffectedScope;
+}) => {
+    affected: Set<string>;
+    downstream: Set<string>;
+    upstream: Set<string>;
+};
 /**
  * Gets the list of files changed between two git refs.
  * Uses execFile with argument arrays to prevent command injection.
@@ -45,4 +79,4 @@ declare const getAffectedProjects: (options: AffectedOptions) => Promise<Affecte
  */
 declare const filterAffectedTasks: (taskIds: string[], affectedProjects: Set<string>) => string[];
 export type { AffectedOptions, AffectedResult };
-export { filterAffectedTasks, getAffectedProjects, getChangedFiles };
+export { buildForwardDependencyMap, buildReverseDependencyMap, expandAffected, filterAffectedTasks, getAffectedProjects, getChangedFiles };

package/dist/command-parser/expand-arguments.d.ts

@@ -0,0 +1,11 @@
+import type { ConcurrentCommandConfig } from "../types.d.ts";
+/**
+ * Expands argument placeholders in command strings.
+ *
+ * Placeholders:
+ *   {1}, {2}, ...  -> specific positional argument
+ *   {@}            -> all arguments, individually quoted
+ *   {*}            -> all arguments as a single quoted string
+ *   \{1}           -> literal {1} (escaped)
+ */
+export declare const expandArguments: (config: ConcurrentCommandConfig, additionalArguments: string[]) => ConcurrentCommandConfig;

package/dist/command-parser/expand-shortcut.d.ts

@@ -0,0 +1,15 @@
+import type { ConcurrentCommandConfig } from "../types.d.ts";
+/**
+ * Expands package manager shortcuts into full commands.
+ *
+ * This parser transforms shorthand notation into proper package manager
+ * invocations. No user input is involved -- command strings originate
+ * from the calling code which reads package.json scripts.
+ *
+ * Examples:
+ *   npm:build    -> npm run build
+ *   pnpm:test    -> pnpm run test
+ *   node:script  -> node --run script
+ *   deno:task    -> deno task task
+ */
+export declare const expandShortcut: (config: ConcurrentCommandConfig) => ConcurrentCommandConfig;

package/dist/command-parser/expand-wildcard.d.ts

@@ -0,0 +1,13 @@
+import type { ConcurrentCommandConfig } from "../types.d.ts";
+/**
+ * Expands wildcard patterns in package manager "run" commands.
+ *
+ * Reads scripts from package.json and matches against the wildcard pattern.
+ * Returns one ConcurrentCommandConfig per matching script.
+ *
+ * Example: "npm run watch-*" with scripts { "watch-js": "...", "watch-css": "..." }
+ *          -> ["npm run watch-js", "npm run watch-css"]
+ *
+ * No user input is involved -- patterns come from the calling code.
+ */
+export declare const expandWildcard: (config: ConcurrentCommandConfig) => ConcurrentCommandConfig | ConcurrentCommandConfig[];

package/dist/command-parser/index.d.ts

@@ -0,0 +1,18 @@
+import type { ConcurrentCommandConfig, ConcurrentCommandInput } from "../types.d.ts";
+export interface ParseCommandsOptions {
+    /** Additional arguments for placeholder expansion ({1}, {@}, {*}). */
+    additionalArguments?: string[];
+}
+/**
+ * Parse and expand command inputs through the full pipeline:
+ * 1. Normalize string inputs to config objects
+ * 2. Strip surrounding quotes
+ * 3. Expand package manager shortcuts (npm:build -> npm run build)
+ * 4. Expand wildcard patterns (npm run watch-* -> multiple commands)
+ * 5. Expand argument placeholders ({1}, {@}, {*})
+ */
+export declare const parseCommands: (inputs: ConcurrentCommandInput[], options?: ParseCommandsOptions) => ConcurrentCommandConfig[];
+export { expandArguments } from "./expand-arguments.d.ts";
+export { expandShortcut } from "./expand-shortcut.d.ts";
+export { expandWildcard } from "./expand-wildcard.d.ts";
+export { stripQuotes } from "./strip-quotes.d.ts";

package/dist/command-parser/strip-quotes.d.ts

@@ -0,0 +1,6 @@
+import type { ConcurrentCommandConfig } from "../types.d.ts";
+/**
+ * Removes surrounding quotes from a command string.
+ * Handles both single and double quotes.
+ */
+export declare const stripQuotes: (config: ConcurrentCommandConfig) => ConcurrentCommandConfig;

package/dist/concurrent-fallback.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pure JavaScript fallback for the concurrent process runner.
+ * Used when the native Rust addon is not available.
+ *
+ * SECURITY NOTE: Commands executed here originate from package.json scripts
+ * (trusted input, not user-supplied). Shell execution via spawn() with
+ * explicit shell binary (sh -c / cmd.exe /s /c) is intentional -- package
+ * scripts require shell features (pipes, redirects, env expansion).
+ * This is the same approach used by npm/pnpm/yarn themselves.
+ */
+import type { ConcurrentCommandConfig, ConcurrentRunnerOptions, ConcurrentRunResult } from "./types.d.ts";
+/**
+ * Run commands concurrently using pure JavaScript (child_process.spawn).
+ * This is the fallback when the native Rust addon is unavailable.
+ */
+export declare const runConcurrentFallback: (commands: ConcurrentCommandConfig[], options: ConcurrentRunnerOptions) => Promise<ConcurrentRunResult>;

package/dist/concurrent.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Public API for the concurrent process runner.
+ *
+ * Uses the native Rust addon when available, falling back to
+ * a pure JavaScript implementation. Integrates flow controllers
+ * (restart, teardown, timings) around the core runner.
+ */
+import type { ConcurrentCommandInput, ConcurrentRunnerOptions, ConcurrentRunResult } from "./types.d.ts";
+/**
+ * Run commands concurrently with output streaming and process management.
+ *
+ * Automatically uses the native Rust addon for performance when available,
+ * falling back to a pure JavaScript implementation.
+ *
+ * Supports flow controllers:
+ * - `restart`: retry failed commands with configurable delay/backoff
+ * - `teardown`: run cleanup commands after all processes complete
+ * - `timings`: print a timing summary table
+ * @param commands Array of command strings or config objects
+ * @param options Runner options (maxProcesses, killOthers, restart, teardown, etc.)
+ * @returns Promise resolving to the run result with close events and success status
+ */
+export declare const runConcurrently: (commands: ConcurrentCommandInput[], options?: ConcurrentRunnerOptions) => Promise<ConcurrentRunResult>;

package/dist/detect-shell.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Detects the configured script shell for npm/pnpm/yarn.
+ *
+ * Resolution order:
+ * 1. `npm_config_script_shell` env var (set by npm when running scripts)
+ * 2. `npm config get script-shell` subprocess (cached after first call)
+ * 3. Platform default (undefined = let the runner use /bin/sh or cmd.exe)
+ */
+/**
+ * Detect the npm script-shell configuration.
+ *
+ * Returns the shell path if configured, or undefined to use platform defaults.
+ * The result is cached after the first call.
+ */
+export declare const detectScriptShell: () => string | undefined;
+/**
+ * Reset the cached shell path. Useful for testing.
+ */
+export declare const resetShellCache: () => void;

package/dist/flow-controllers/index.d.ts

@@ -0,0 +1,7 @@
+export type { InputHandlerOptions } from "./input-handler.d.ts";
+export { createInputHandler } from "./input-handler.d.ts";
+export { formatTimingTable, logTimings } from "./log-timings.d.ts";
+export type { RestartOptions } from "./restart-process.d.ts";
+export { withRestart } from "./restart-process.d.ts";
+export type { TeardownOptions } from "./teardown.d.ts";
+export { runTeardown } from "./teardown.d.ts";

package/dist/flow-controllers/input-handler.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Input handler flow controller.
+ *
+ * Routes stdin data to specific child processes based on a prefix pattern.
+ * Input prefixed with "name:" or "index:" is routed to that command's stdin.
+ * Unprefixed input goes to the default target (index 0).
+ *
+ * NOTE: This module does NOT execute commands -- it only pipes user-typed
+ * stdin data to already-running child process stdin streams. No shell
+ * invocation or command injection risk.
+ *
+ * LIMITATION: This is a standalone utility -- it is NOT integrated into
+ * runConcurrently() because the concurrent runner does not expose child
+ * stdin streams. To use this, spawn processes manually with stdin: "pipe"
+ * and pass the writable streams to createInputHandler().
+ *
+ * TODO: To fully integrate stdin routing into runConcurrently(), we would need:
+ * 1. A new "started" ProcessEvent that carries a writable stdin reference
+ * 2. On the Rust side: expose tokio::process::ChildStdin through NAPI
+ *    (requires a custom wrapper since ChildStdin can't cross FFI directly)
+ * 3. In the JS fallback: return child.stdin from spawnCommand()
+ */
+import type { Readable, Writable } from "node:stream";
+export interface InputHandlerOptions {
+    /** Default command index to route unprefixed input to. Default: 0. */
+    defaultTarget?: number;
+    /** Stream to read input from. Default: process.stdin. */
+    inputStream?: Readable;
+    /** Whether to pause the input stream when all processes finish. Default: true. */
+    pauseOnFinish?: boolean;
+}
+interface CommandStdin {
+    index: number;
+    name?: string;
+    stdin: Writable;
+}
+/**
+ * Creates an input handler that routes stdin to child processes.
+ * @param commands Map of command index/name to their stdin streams
+ * @param options Input handler configuration
+ * @returns cleanup function to call when done
+ */
+export declare const createInputHandler: (commands: CommandStdin[], options?: InputHandlerOptions) => () => void;
+export {};

package/dist/flow-controllers/log-timings.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Log timings flow controller.
+ *
+ * Prints a summary table of all command durations after completion.
+ */
+import type { ConcurrentCloseEvent } from "../types.d.ts";
+/**
+ * Generate a timing summary table string from close events.
+ * @param closeEvents Close events from the concurrent run (in completion order)
+ * @returns Formatted table string
+ */
+export declare const formatTimingTable: (closeEvents: ConcurrentCloseEvent[]) => string;
+/**
+ * Print timing summary to a writable stream.
+ * @param closeEvents Close events from the concurrent run
+ * @param output Output stream (default: process.stdout)
+ */
+export declare const logTimings: (closeEvents: ConcurrentCloseEvent[], output?: NodeJS.WritableStream) => void;

package/dist/flow-controllers/restart-process.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Restart flow controller.
+ *
+ * Re-runs failed commands with configurable retry count and delay.
+ * Supports fixed delay or exponential backoff.
+ */
+import type { ConcurrentCommandConfig, ConcurrentRunnerOptions, ConcurrentRunResult } from "../types.d.ts";
+export interface RestartOptions {
+    /** Delay between restarts in milliseconds. "exponential" for 2^attempt * 1000ms. */
+    delay: number | "exponential";
+    /** Maximum number of restart attempts per command. 0 = no restarts. -1 = infinite. */
+    tries: number;
+}
+/**
+ * Wraps a runner function to add restart-on-failure behavior.
+ * @param runFn The underlying runner function (runConcurrently or runConcurrentFallback)
+ * @param commands The original command configs
+ * @param options Runner options
+ * @param restartOptions Restart-specific options
+ */
+export declare const withRestart: (runFunction: (commands: ConcurrentCommandConfig[], options: ConcurrentRunnerOptions) => Promise<ConcurrentRunResult>, commands: ConcurrentCommandConfig[], options: ConcurrentRunnerOptions, restartOptions: RestartOptions) => Promise<ConcurrentRunResult>;