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

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+## @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,179 @@
-# @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
-
-## 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.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-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
-
-## DO NOT USE THIS PACKAGE
-
-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
-
-## More Information
+---
 
-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)
+<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>
 
 ---
 
-**Maintained for OIDC setup purposes only**
+## Features
+
+- **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
+- **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
+- **Graph visualization**: DOT, JSON, HTML, and ASCII output formats
+- **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
+
+## Install
+
+```bash
+npm install @visulima/task-runner
+```
+
+```bash
+yarn add @visulima/task-runner
+```
+
+```bash
+pnpm add @visulima/task-runner
+```
+
+## Quick Start
+
+```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);
+```
+
+## 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.
+
+### 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:
+
+- **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]
+
+[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

package/binding.js

@@ -0,0 +1,204 @@
+/* eslint-disable */
+/* auto-generated binding loader for @visulima/task-runner native addon */
+
+const { existsSync, readFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const { platform, arch } = process;
+
+let nativeBinding = null;
+let localFileExisted = false;
+let loadError = null;
+
+function isMusl() {
+    // For Node 12+, check report.header for musl
+    if (
+        typeof process.report !== "undefined" &&
+        typeof process.report.getReport === "function"
+    ) {
+        const { glibcVersionRuntime } = process.report.getReport().header;
+        if (glibcVersionRuntime) {
+            return false;
+        }
+        return true;
+    }
+
+    try {
+        const lddOutput = readFileSync("/usr/bin/ldd", "utf8");
+        return lddOutput.includes("musl");
+    } catch {
+        try {
+            return readFileSync("/proc/self/map_files/../maps", "utf8").includes(
+                "musl"
+            );
+        } catch {
+            return false;
+        }
+    }
+}
+
+switch (platform) {
+    case "darwin":
+        switch (arch) {
+            case "x64":
+                localFileExisted = existsSync(
+                    join(__dirname, "task-runner-native.darwin-x64.node")
+                );
+                try {
+                    if (localFileExisted) {
+                        nativeBinding = require("./task-runner-native.darwin-x64.node");
+                    } else {
+                        nativeBinding = require("@visulima/task-runner-binding-darwin-x64");
+                    }
+                } catch (e) {
+                    loadError = e;
+                }
+                break;
+            case "arm64":
+                localFileExisted = existsSync(
+                    join(__dirname, "task-runner-native.darwin-arm64.node")
+                );
+                try {
+                    if (localFileExisted) {
+                        nativeBinding = require("./task-runner-native.darwin-arm64.node");
+                    } else {
+                        nativeBinding = require("@visulima/task-runner-binding-darwin-arm64");
+                    }
+                } catch (e) {
+                    loadError = e;
+                }
+                break;
+            default:
+                throw new Error(`Unsupported architecture on macOS: ${arch}`);
+        }
+        break;
+    case "linux":
+        switch (arch) {
+            case "x64":
+                if (isMusl()) {
+                    localFileExisted = existsSync(
+                        join(
+                            __dirname,
+                            "task-runner-native.linux-x64-musl.node"
+                        )
+                    );
+                    try {
+                        if (localFileExisted) {
+                            nativeBinding = require("./task-runner-native.linux-x64-musl.node");
+                        } else {
+                            nativeBinding = require("@visulima/task-runner-binding-linux-x64-musl");
+                        }
+                    } catch (e) {
+                        loadError = e;
+                    }
+                } else {
+                    localFileExisted = existsSync(
+                        join(
+                            __dirname,
+                            "task-runner-native.linux-x64-gnu.node"
+                        )
+                    );
+                    try {
+                        if (localFileExisted) {
+                            nativeBinding = require("./task-runner-native.linux-x64-gnu.node");
+                        } else {
+                            nativeBinding = require("@visulima/task-runner-binding-linux-x64-gnu");
+                        }
+                    } catch (e) {
+                        loadError = e;
+                    }
+                }
+                break;
+            case "arm64":
+                if (isMusl()) {
+                    localFileExisted = existsSync(
+                        join(
+                            __dirname,
+                            "task-runner-native.linux-arm64-musl.node"
+                        )
+                    );
+                    try {
+                        if (localFileExisted) {
+                            nativeBinding = require("./task-runner-native.linux-arm64-musl.node");
+                        } else {
+                            nativeBinding = require("@visulima/task-runner-binding-linux-arm64-musl");
+                        }
+                    } catch (e) {
+                        loadError = e;
+                    }
+                } else {
+                    localFileExisted = existsSync(
+                        join(
+                            __dirname,
+                            "task-runner-native.linux-arm64-gnu.node"
+                        )
+                    );
+                    try {
+                        if (localFileExisted) {
+                            nativeBinding = require("./task-runner-native.linux-arm64-gnu.node");
+                        } else {
+                            nativeBinding = require("@visulima/task-runner-binding-linux-arm64-gnu");
+                        }
+                    } catch (e) {
+                        loadError = e;
+                    }
+                }
+                break;
+            default:
+                throw new Error(`Unsupported architecture on Linux: ${arch}`);
+        }
+        break;
+    case "win32":
+        switch (arch) {
+            case "x64":
+                localFileExisted = existsSync(
+                    join(
+                        __dirname,
+                        "task-runner-native.win32-x64-msvc.node"
+                    )
+                );
+                try {
+                    if (localFileExisted) {
+                        nativeBinding = require("./task-runner-native.win32-x64-msvc.node");
+                    } else {
+                        nativeBinding = require("@visulima/task-runner-binding-win32-x64-msvc");
+                    }
+                } catch (e) {
+                    loadError = e;
+                }
+                break;
+            case "arm64":
+                localFileExisted = existsSync(
+                    join(
+                        __dirname,
+                        "task-runner-native.win32-arm64-msvc.node"
+                    )
+                );
+                try {
+                    if (localFileExisted) {
+                        nativeBinding = require("./task-runner-native.win32-arm64-msvc.node");
+                    } else {
+                        nativeBinding = require("@visulima/task-runner-binding-win32-arm64-msvc");
+                    }
+                } catch (e) {
+                    loadError = e;
+                }
+                break;
+            default:
+                throw new Error(`Unsupported architecture on Windows: ${arch}`);
+        }
+        break;
+    default:
+        throw new Error(
+            `Unsupported OS: ${platform}, architecture: ${arch}`
+        );
+}
+
+if (!nativeBinding) {
+    if (loadError) {
+        throw loadError;
+    }
+    throw new Error("Failed to load native binding");
+}
+
+module.exports = nativeBinding;

package/dist/affected.d.ts

@@ -0,0 +1,48 @@
+import type { ProjectConfiguration, ProjectGraph } from "./types.d.ts";
+/**
+ * Options for determining affected projects.
+ */
+interface AffectedOptions {
+    /** The base ref to compare against (default: "main") */
+    base?: string;
+    /** 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>;
+    /** The workspace root directory */
+    workspaceRoot: string;
+}
+/**
+ * Result of affected detection.
+ */
+interface AffectedResult {
+    /** Projects affected by changes (including transitive dependents) */
+    affectedProjects: string[];
+    /** Files that changed between base and head */
+    changedFiles: string[];
+    /** Projects that were directly changed */
+    changedProjects: string[];
+}
+/**
+ * Gets the list of files changed between two git refs.
+ * Uses execFile with argument arrays to prevent command injection.
+ */
+declare const getChangedFiles: (workspaceRoot: string, base: string, head: string) => Promise<string[]>;
+/**
+ * Determines which projects are affected by changes between two git refs.
+ *
+ * Uses `git diff` to find changed files, maps them to projects based on
+ * project roots, then walks the project dependency graph to find all
+ * transitively affected projects.
+ *
+ * This is the same strategy used by `nx affected` and `turbo run --filter=[base...]`.
+ */
+declare const getAffectedProjects: (options: AffectedOptions) => Promise<AffectedResult>;
+/**
+ * Filters tasks to only include those that are affected by changes.
+ */
+declare const filterAffectedTasks: (taskIds: string[], affectedProjects: Set<string>) => string[];
+export type { AffectedOptions, AffectedResult };
+export { filterAffectedTasks, getAffectedProjects, getChangedFiles };

package/dist/cache.d.ts

@@ -0,0 +1,103 @@
+import type { TaskFingerprint } from "./fingerprint.d.ts";
+/**
+ * Represents a cached task result.
+ */
+interface CachedResult {
+    /** The exit code of the original task execution */
+    code: number;
+    /** The auto-fingerprint data, if auto-fingerprinting was used */
+    fingerprint?: TaskFingerprint;
+    /** The hash that was used as the cache key */
+    hash: string;
+    /** The terminal output of the original task execution */
+    terminalOutput: string;
+}
+/**
+ * Options for creating a Cache instance.
+ */
+interface CacheOptions {
+    /** The cache directory (defaults to `{workspaceRoot}/.task-runner-cache`) */
+    cacheDirectory?: string;
+    /** Maximum age of cache entries in milliseconds (default: 7 days) */
+    maxCacheAge?: number;
+    /** Maximum cache size (e.g., "500MB", "1GB") */
+    maxCacheSize?: string;
+    /** The workspace root directory */
+    workspaceRoot: string;
+}
+/**
+ * Parses a human-readable cache size string into bytes.
+ * Delegates to @visulima/humanizer's parseBytes with base-2 (1024) multipliers.
+ */
+declare const parseCacheSize: (sizeString: string) => number;
+/**
+ * Formats a byte count into a human-readable string.
+ * Delegates to @visulima/humanizer's formatBytes with base-2 (1024) multipliers.
+ */
+declare const formatCacheSize: (bytes: number) => string;
+/**
+ * Local file-based cache for task results.
+ *
+ * Cache structure:
+ * ```
+ * .task-runner-cache/
+ *   <hash>/
+ *     outputs/          (Archived build outputs)
+ *     code              (Exit code)
+ *     terminalOutput    (Captured terminal output)
+ *     fingerprint.json  (Auto-fingerprint data, optional)
+ *     .commit           (Marker indicating complete cache entry)
+ *   .task-index.json    (Task ID -> hash mapping for auto-fingerprint)
+ * ```
+ *
+ * Atomicity: Cache entries are written to a temporary directory first,
+ * then renamed into place. The `.commit` marker ensures readers only
+ * see complete entries.
+ */
+declare class Cache {
+    #private;
+    constructor(options: CacheOptions);
+    /**
+     * Gets the cache directory path.
+     */
+    get cacheDirectory(): string;
+    /**
+     * Retrieves a cached result for the given task hash.
+     * Returns undefined if no valid cache entry exists.
+     */
+    get(hash: string): Promise<CachedResult | undefined>;
+    /**
+     * Stores a task result in the cache.
+     *
+     * Uses atomic write: builds the entry in a temporary directory,
+     * then renames into place to avoid partial reads by concurrent processes.
+     */
+    put(hash: string, terminalOutput: string, outputs: string[], code: number, fingerprint?: TaskFingerprint): Promise<void>;
+    /**
+     * Restores cached outputs to their original locations.
+     */
+    restoreOutputs(hash: string, outputs: string[]): Promise<boolean>;
+    /**
+     * Retrieves the most recent cached result for a task by its ID.
+     * Used in auto-fingerprint mode where the hash is derived from
+     * tracked file accesses rather than computed upfront.
+     */
+    getByTaskId(taskId: string): Promise<CachedResult | undefined>;
+    /**
+     * Stores the mapping from task ID to cache hash.
+     * Uses a write queue to serialize concurrent writes and prevent lost updates.
+     * Each write is atomic (temp file + rename).
+     */
+    setTaskIndex(taskId: string, hash: string): Promise<void>;
+    /**
+     * Removes old cache entries that exceed the maximum age,
+     * and enforces the maximum cache size by evicting oldest entries.
+     */
+    removeOldEntries(): Promise<void>;
+    /**
+     * Clears the entire cache.
+     */
+    clear(): Promise<void>;
+}
+export type { CachedResult, CacheOptions };
+export { Cache, formatCacheSize, parseCacheSize };

package/dist/default-task-runner.d.ts

@@ -0,0 +1,44 @@
+import type { Task, TaskResults, TaskRunnerContext, TaskRunnerOptions } from "./types.d.ts";
+/**
+ * The default task runner implementation.
+ *
+ * Runs tasks with caching, scheduling, and lifecycle support.
+ * Supports two caching modes:
+ *
+ * 1. **Nx-style** (default): Explicit input declarations with upfront hash computation.
+ * 2. **Auto-fingerprint** (Vite Task-style): Set `autoFingerprint: true` to automatically
+ * track file accesses and use them for cache invalidation.
+ * @example
+ * ```ts
+ * import { defaultTaskRunner } from "@visulima/task-runner";
+ *
+ * // Nx-style (explicit inputs)
+ * const results = await defaultTaskRunner(tasks, options, context);
+ *
+ * // Vite Task-style (auto-fingerprinting)
+ * const results = await defaultTaskRunner(tasks, {
+ *     ...options,
+ *     autoFingerprint: true,
+ *     fingerprintEnvPatterns: ["VITE_*", "NODE_ENV"],
+ *     cacheDiagnostics: true,
+ * }, context);
+ *
+ * // With remote cache
+ * const results = await defaultTaskRunner(tasks, {
+ *     ...options,
+ *     remoteCache: {
+ *         url: "https://cache.example.com",
+ *         token: process.env.CACHE_TOKEN,
+ *         teamId: "my-team",
+ *     },
+ * }, context);
+ *
+ * // Dry-run (inspect hashes without executing)
+ * const results = await defaultTaskRunner(tasks, {
+ *     ...options,
+ *     dryRun: true,
+ * }, context);
+ * ```
+ */
+declare const defaultTaskRunner: (_tasks: Task[], options: TaskRunnerOptions, context: TaskRunnerContext) => Promise<TaskResults>;
+export { defaultTaskRunner };