@visulima/task-runner 0.0.1 → 1.0.0-alpha.10

package/CHANGELOG.md

@@ -0,0 +1,212 @@
+## @visulima/task-runner [1.0.0-alpha.10](https://github.com/visulima/visulima/compare/@visulima/task-runner@1.0.0-alpha.9...@visulima/task-runner@1.0.0-alpha.10) (2026-05-06)
+
+### Features
+
+* **task-runner:** add per-target maxConcurrent and workspace concurrencyGroups ([985d5d1](https://github.com/visulima/visulima/commit/985d5d1d3a594f3b42cfa3f7735bc1bb8055563e))
+
+### Miscellaneous Chores
+
+* **task-runner:** clear lint warnings ([05fa2b6](https://github.com/visulima/visulima/commit/05fa2b6fa259607933fc709dc871b5ef52294721))
+* **task-runner:** fix lint errors ([0f5a6d0](https://github.com/visulima/visulima/commit/0f5a6d00bd321b98f9b4289923e151c59a5b7e58))
+* **task-runner:** fix lint errors in test files ([5e7dc4f](https://github.com/visulima/visulima/commit/5e7dc4fcee277691034666a252d97503aa7be0a4))
+* **task-runner:** housekeeping cleanup ([e837f11](https://github.com/visulima/visulima/commit/e837f1166b43bcfbccfdffe693248db498c0fe1d))
+
+### Continuous Integration
+
+* integrate codspeed for benchmark tracking ([e758f3d](https://github.com/visulima/visulima/commit/e758f3da491cc00d3f8bbf10d7ba3fdf8deb5325))
+
+## @visulima/task-runner [1.0.0-alpha.9](https://github.com/visulima/visulima/compare/@visulima/task-runner@1.0.0-alpha.8...@visulima/task-runner@1.0.0-alpha.9) (2026-05-04)
+
+### Features
+
+* **task-runner,vis:** cache restoration fidelity ([a15cb22](https://github.com/visulima/visulima/commit/a15cb22bde832cfe76ee017722b8b9f9102dac8f))
+* **task-runner:** add REAPI gRPC backend, cacheMode, and cache doctor ([03e6da9](https://github.com/visulima/visulima/commit/03e6da97beb84f6adc4a07a1c7ca4acf28be3b33))
+* **task-runner:** add URI-based input format ([050b583](https://github.com/visulima/visulima/commit/050b5838c15590a3ccba0ca99ad585cbabc36d99))
+* **task-runner:** skip-on-warning incrementality ([2c79ab3](https://github.com/visulima/visulima/commit/2c79ab35d0513bf4e60f87d1ac3bc4e99296cb62)), closes [#22](https://github.com/visulima/visulima/issues/22) [rushstack#1402](https://github.com/visulima/rushstack/issues/1402)
+
+### Bug Fixes
+
+* **vis:** preserve probe error on close failure and clamp formatAge ([f1d71d6](https://github.com/visulima/visulima/commit/f1d71d63a5432fc2ed8c09c9a0a87e4e59b83b0b))
+
+### Documentation
+
+* **task-runner:** cover when/always, tokens, REAPI, hooks ([1515cd3](https://github.com/visulima/visulima/commit/1515cd349db41fcfe83ae86ed4d52df8dccbf985))
+
+### Miscellaneous Chores
+
+* catalog refresh + task-runner binding bump to 1.0.0-alpha.8 ([ff4548a](https://github.com/visulima/visulima/commit/ff4548a5678c992048a57e73c310757733c04756))
+* **deps:** bump rust crates to current majors ([3a1d9bb](https://github.com/visulima/visulima/commit/3a1d9bb7f6e2c6b2d3862e212ae62707d60815cc))
+
+### Code Refactoring
+
+* **task-runner,vis:** consolidate helpers and tighten branches ([d1290d1](https://github.com/visulima/visulima/commit/d1290d1f614036902c6803d8ff51df100fdd07ab))
+* **task-runner,vis:** expose worktree helpers from task-runner ([12468d7](https://github.com/visulima/visulima/commit/12468d76bb03278ec56691ba0c6d9821c9482f94))
+
+### Tests
+
+* **task-runner:** split tests into unit/integration mirroring src layout ([ae78f99](https://github.com/visulima/visulima/commit/ae78f992d24626f3b23de56fa735aced47b1220e))
+
+## @visulima/task-runner [1.0.0-alpha.8](https://github.com/visulima/visulima/compare/@visulima/task-runner@1.0.0-alpha.7...@visulima/task-runner@1.0.0-alpha.8) (2026-04-30)
+
+### Features
+
+* **task-runner:** expose worktree detection napi bindings ([3d67028](https://github.com/visulima/visulima/commit/3d670284090010616956a024a4e5465ee91bbcd4))
+* **task-runner:** graceful Ctrl+Break on Windows SIGINT ([ae44b1c](https://github.com/visulima/visulima/commit/ae44b1c855839746092a91430eb49b216d1172ec))
+* **task-runner:** tokens, when, and always tasks ([5ae6505](https://github.com/visulima/visulima/commit/5ae65055d97e97d7ad7ff9088996da37d964da3f))
+
+### Bug Fixes
+
+* **vis:** address review findings on watch UX bundle ([edee703](https://github.com/visulima/visulima/commit/edee7038fe23a488791682dd8ce5c469b40a3e8c))
+
+### Miscellaneous Chores
+
+* re-sort workspace package.json files via vis sort-package-json ([f625696](https://github.com/visulima/visulima/commit/f625696cfac974325774b3243e1a83c3d23acbd7))
+* **task-runner:** upgrade packem to 2.0.0-alpha.76 ([5f59c41](https://github.com/visulima/visulima/commit/5f59c4140f89019cc3756ac917e1bda7ded0beec))
+
+## @visulima/task-runner [1.0.0-alpha.7](https://github.com/visulima/visulima/compare/@visulima/task-runner@1.0.0-alpha.6...@visulima/task-runner@1.0.0-alpha.7) (2026-04-22)
+
+### Bug Fixes
+
+* **ci:** publish native addons via local semantic-release plugin ([974beb2](https://github.com/visulima/visulima/commit/974beb2d021e7b2afc86b958bd2137be88d2f464))
+* Remove JSR configuration generation script and generated jsr.json files ([#616](https://github.com/visulima/visulima/issues/616)) ([533744b](https://github.com/visulima/visulima/commit/533744b103b74896941db5b727173e617a27a63b))
+
+### Miscellaneous Chores
+
+* update the jsr.json ([864ab7e](https://github.com/visulima/visulima/commit/864ab7e71c4b5ae82f64792d1ae8debfea2c539b))
+
+
+### Dependencies
+
+* **@visulima/humanizer:** upgraded to 3.0.0-alpha.11
+* **@visulima/path:** upgraded to 3.0.0-alpha.10
+
+## @visulima/task-runner [1.0.0-alpha.6](https://github.com/visulima/visulima/compare/@visulima/task-runner@1.0.0-alpha.5...@visulima/task-runner@1.0.0-alpha.6) (2026-04-21)
+
+### Features
+
+* **task-runner:** output globs, auto-writes, parallel cache IO ([137f53f](https://github.com/visulima/visulima/commit/137f53f7f5a4d8c16df511c9d145b2c158025a32))
+* **task-runner:** vite-task parity + plugin-ready lifecycle hooks ([cfc7360](https://github.com/visulima/visulima/commit/cfc7360abf00524fbfc37b60df27970c325f91e1)), closes [pkg#task](https://github.com/visulima/pkg/issues/task)
+
+### Bug Fixes
+
+* **task-runner:** resolve eslint errors in chrome-trace and task-hasher ([2cf6266](https://github.com/visulima/visulima/commit/2cf6266b8252bc24a6d900f49f97611d4d629ff3))
+
+### Miscellaneous Chores
+
+* **api-platform:** apply pending lint and source updates ([3fb0043](https://github.com/visulima/visulima/commit/3fb0043a4cf35f752ca89a09a077100ae0142da8))
+* bump engines.node to ^22.14.0 || >=24.10.0 ([c3d0931](https://github.com/visulima/visulima/commit/c3d0931d1504e4f21ebf50ea680cfa7ce4ba15ce))
+* fixed jsr.json ([5d85e51](https://github.com/visulima/visulima/commit/5d85e5179de38e284ec433b14d77c71a1619c8d6))
+* **task-runner:** apply formatter and lint fixes ([70b4641](https://github.com/visulima/visulima/commit/70b4641b394897ebfc021425b992db936e320d8a))
+* **task-runner:** apply formatter and lint fixes ([aee664f](https://github.com/visulima/visulima/commit/aee664f0a03ed9c1eb8bf7a6a91e62f601a3d5ff))
+* **task-runner:** apply pending changes ([9d92517](https://github.com/visulima/visulima/commit/9d92517f1a54bc28a19cb8cbdb937cdc234e152d))
+* **task-runner:** apply pending lint and source updates ([c01eb39](https://github.com/visulima/visulima/commit/c01eb393f991d8fc96f8ed87bfc71d90902ee659))
+* **task-runner:** enforce curly braces and apply lint fixes ([4fbd8ee](https://github.com/visulima/visulima/commit/4fbd8eefa1b56f428528b495b074d5c266fb6733))
+
+### Code Refactoring
+
+* replace inline import() types with top-level imports ([4569a4c](https://github.com/visulima/visulima/commit/4569a4ca04723da069f985855dcfab292f7347e1))
+
+### Tests
+
+* **task-runner:** remove native binding guard from tests ([90f0dff](https://github.com/visulima/visulima/commit/90f0dffe85f4b83e76905a26d53b917365116b45))
+* **task-runner:** skip default excludes for tmpdir-backed tracker tests ([0db0620](https://github.com/visulima/visulima/commit/0db06206173f0799244fafcc578b9fb0be9d2fb6))
+
+## @visulima/task-runner [1.0.0-alpha.5](https://github.com/visulima/visulima/compare/@visulima/task-runner@1.0.0-alpha.4...@visulima/task-runner@1.0.0-alpha.5) (2026-04-15)
+
+### Features
+
+* Add comprehensive workspace configuration and command infrastructure ([#609](https://github.com/visulima/visulima/issues/609)) ([f4347bf](https://github.com/visulima/visulima/commit/f4347bfdcdd1b228cd9d842a927e446aaf23f035))
+* **vis:** add cache command for task runner cache ([#607](https://github.com/visulima/visulima/issues/607)) ([6752769](https://github.com/visulima/visulima/commit/67527692562b3dd9c03bb6a67c084ff1e694a560))
+
+### Bug Fixes
+
+* **tooling:** resolve eslint and formatting issues ([399d292](https://github.com/visulima/visulima/commit/399d29282be5b29bb26b4e5b24d45e2a6cdeeca3))
+
+
+### Dependencies
+
+* **@visulima/humanizer:** upgraded to 3.0.0-alpha.10
+* **@visulima/path:** upgraded to 3.0.0-alpha.9
+
+## @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
+
+* **web:** auto-generate packages page from workspace metadata ([623e520](https://github.com/visulima/visulima/commit/623e5207693a7fe720f5f2f179593a3654c880e3))
+
+### Miscellaneous Chores
+
+* **task-runner:** remove redundant extends from .releaserc.json ([8969dfa](https://github.com/visulima/visulima/commit/8969dfaeccf3a36e40ecb9ba659187f81dda4ce1))
+
+### Continuous Integration
+
+* **task-runner:** use escaped newlines in git commit message template ([b3045b6](https://github.com/visulima/visulima/commit/b3045b6c2c5afc641c699932fbf90effe7c31563))
+
+
+### Dependencies
+
+* **@visulima/humanizer:** upgraded to 3.0.0-alpha.8
+* **@visulima/path:** upgraded to 3.0.0-alpha.7
+
+## @visulima/task-runner [1.0.0-alpha.2](https://github.com/visulima/visulima/compare/@visulima/task-runner@1.0.0-alpha.1...@visulima/task-runner@1.0.0-alpha.2) (2026-03-26)
+
+### Bug Fixes
+
+* **task-runner:** publish native binding packages with version lockstep via exec plugin ([12e342f](https://github.com/visulima/visulima/commit/12e342f1656ad0b595eaff627d3407c61c4ea7b6))
+
+### Miscellaneous Chores
+
+* **task-runner:** add project.json for all native binding packages ([eb48812](https://github.com/visulima/visulima/commit/eb48812cb87c0990b9822d9314ccc0081e41d11f))
+
+## @visulima/task-runner 1.0.0-alpha.1 (2026-03-26)
+
+### Features
+
+* Add @visulima/task-runner , vis and find-ai-runner ([#594](https://github.com/visulima/visulima/issues/594)) ([034b5db](https://github.com/visulima/visulima/commit/034b5db8aadcc02e23abe007208c5196859c7755))
+
+
+### Dependencies
+
+* **@visulima/humanizer:** upgraded to 3.0.0-alpha.7
+* **@visulima/path:** upgraded to 3.0.0-alpha.6

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 visulima
+
+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

@@ -1,45 +1,323 @@
-# @visulima/task-runner
+<div align="center">
+  <h3>Visulima task-runner</h3>
+  <p>
+  High-performance monorepo task runner with intelligent caching, dependency-aware scheduling, and auto-fingerprinting.
+  </p>
+</div>
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+<br />
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+<div align="center">
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+[![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
 
-## Purpose
+</div>
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@visulima/task-runner`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+---
+
+<div align="center">
+    <p>
+        <sup>
+            Daniel Bannert's open source work is supported by the community on <a href="https://github.com/sponsors/prisis">GitHub Sponsors</a>
+        </sup>
+    </p>
+</div>
 
-## What is OIDC Trusted Publishing?
+---
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## Features
 
-## Setup Instructions
+- **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, plus a Bazel REAPI gRPC backend (bazel-remote, BuildBuddy, BuildBarn, EngFlow)
+- **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
+- **Conditional tasks**: `when:` predicates (`os`, `env`, `branch`, `ci`) and `always: true` finally-tasks for cleanup/notifications
+- **Graph visualization**: DOT, JSON, HTML, and ASCII output formats
+- **Log reporter modes**: `interleaved`, `labeled` (per-line `[project#target]` prefix), and `grouped` (header/footer wrapping) for vite-task parity
+- **Run summaries**: Detailed JSON reports for debugging cache behavior
+- **Cache diagnostics**: Explains exactly why a cache miss occurred
+- **Output archiving**: Caches and restores build outputs (dist/ directories)
+- **LRU cache eviction**: Configurable max size and age limits
+- **Lifecycle hooks**: 7 hook points for custom behavior
 
-To properly configure OIDC trusted publishing for this package:
+## Install
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```bash
+npm install @visulima/task-runner
+```
 
-## DO NOT USE THIS PACKAGE
+```bash
+yarn add @visulima/task-runner
+```
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```bash
+pnpm add @visulima/task-runner
+```
 
-## More Information
+## Quick Start
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```typescript
+import { defaultTaskRunner } from "@visulima/task-runner";
 
----
+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",
+        },
+    },
+    context,
+);
+```
+
+## Concurrent Process Runner
+
+Run multiple commands in parallel with real-time output streaming, process tree management, and automatic native acceleration.
+
+```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}`);
+            }
+        },
+    },
+);
+```
+
+### 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)
+
+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"] },
+        },
+    },
+    context,
+);
+```
+
+### Auto-fingerprint (Vite Task-style)
+
+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,
+);
+```
+
+## API
+
+### `defaultTaskRunner(tasks, options, context)`
+
+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                       |
+
+### 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`
+- **Scheduling**: `TaskScheduler`, `TaskOrchestrator`
+- **Lockfile**: `LockfileHasher`, `parseNpmLockfile`, `parsePnpmLockfile`, `parseYarnLockfile`
+- **Framework**: `detectFrameworks`, `inferFrameworkEnvPatterns`, `getFrameworkEnvVariables`
+- **Affected**: `getAffectedProjects`, `getChangedFiles`, `filterAffectedTasks`
+- **Visualization**: `toGraphvizDot`, `toGraphJson`, `toGraphHtml`, `toGraphAscii`
+- **Summary**: `generateRunSummary`, `writeRunSummary`
+- **Lifecycle**: `ConsoleLifeCycle`, `CompositeLifeCycle`
+
+## Supported Node.js Versions
+
+Libraries in this ecosystem make the best effort to track [Node.js' release schedule](https://github.com/nodejs/release#release-schedule).
+
+## Contributing
+
+If you would like to help take a look at the [list of issues](https://github.com/visulima/visulima/issues) and check our [Contributing](https://github.com/visulima/visulima/blob/main/.github/CONTRIBUTING.md) guidelines.
+
+## License
+
+The visulima task-runner is open-sourced software licensed under the [MIT][license-url]
 
-**Maintained for OIDC setup purposes only**
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]: https://www.typescriptlang.org/
+[license-image]: https://img.shields.io/npm/l/@visulima/task-runner?color=blueviolet&style=for-the-badge
+[license-url]: LICENSE.md
+[npm-image]: https://img.shields.io/npm/v/@visulima/task-runner/latest.svg?style=for-the-badge&logo=npm
+[npm-url]: https://www.npmjs.com/package/@visulima/task-runner/v/latest