@visulima/task-runner 1.0.0-alpha.6 → 1.0.0-alpha.8

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

@@ -1,44 +0,0 @@
-/**
- * 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

@@ -1,18 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-/**
- * 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>;

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

@@ -1,22 +0,0 @@
-/**
- * Teardown flow controller.
- *
- * Runs cleanup commands sequentially after all concurrent processes complete.
- * Each teardown command inherits stdio (output goes directly to terminal).
- *
- * Commands are sourced from configuration (trusted, not user input).
- * Shell execution is intentional for pipe/redirect support.
- */
-export interface TeardownOptions {
-    /** Commands to run in sequence after all processes complete. */
-    commands: string[];
-    /** Working directory for teardown commands. */
-    cwd?: string;
-}
-/**
- * Run teardown commands sequentially.
- * Each command runs in the shell with inherited stdio.
- * If a command fails, subsequent commands are still attempted.
- * @returns Array of exit codes for each teardown command
- */
-export declare const runTeardown: (options: TeardownOptions) => Promise<number[]>;

package/dist/framework-inference.d.ts

@@ -1,35 +0,0 @@
-/**
- * Detected framework information.
- */
-interface DetectedFramework {
-    /** The env var prefix(es) that should be included in task hashes */
-    envPrefixes: string[];
-    /** The framework name */
-    name: string;
-}
-/**
- * Detects frameworks used in a project by inspecting its package.json dependencies.
- * @param packageJsonPath Absolute path to the package.json file
- * @returns Array of detected frameworks with their env prefixes
- */
-declare const detectFrameworks: (packageJsonPath: string) => Promise<DetectedFramework[]>;
-/**
- * Detects frameworks across all projects in a workspace and returns
- * the env var patterns that should be included in task hashes.
- * @param workspaceRoot The workspace root directory
- * @param projects Map of project name to project configuration with root paths
- * @returns Array of env var wildcard patterns (e.g., ["NEXT_PUBLIC_*", "VITE_*"])
- */
-declare const inferFrameworkEnvPatterns: (workspaceRoot: string, projects: Record<string, {
-    root: string;
-}>) => Promise<string[]>;
-/**
- * For a specific project, detects frameworks and returns the matching
- * env vars from the current environment.
- * @param packageJsonPath Absolute path to the project's package.json
- * @param env The current environment variables
- * @returns Map of env var name to value for matching framework env vars
- */
-declare const getFrameworkEnvVariables: (packageJsonPath: string, env?: Record<string, string | undefined>) => Promise<Record<string, string>>;
-export type { DetectedFramework };
-export { detectFrameworks, getFrameworkEnvVariables, inferFrameworkEnvPatterns };

package/dist/graph-visualizer.d.ts

@@ -1,74 +0,0 @@
-import type { ProjectGraph, TaskGraph } from "./types.d.ts";
-/**
- * Graph visualization output formats.
- */
-type GraphFormat = "dot" | "json" | "html" | "ascii";
-/**
- * Options for graph visualization.
- */
-interface GraphVisualizerOptions {
-    /** Show only affected/filtered tasks (highlight subset) */
-    focusedTasks?: string[];
-    /** Group tasks by project (default: true) */
-    groupByProject?: boolean;
-    /** Show task status colors (requires results) */
-    taskStatuses?: Map<string, "success" | "failure" | "skipped" | "local-cache" | "local-cache-kept-existing" | "remote-cache" | "running" | "pending">;
-}
-/**
- * Exports a task graph in DOT format for Graphviz rendering.
- * @example
- * ```ts
- * const dot = toGraphvizDot(taskGraph);
- * // Render: dot -Tsvg -o graph.svg <<< "$dot"
- * ```
- */
-declare const toGraphvizDot: (taskGraph: TaskGraph, options?: GraphVisualizerOptions) => string;
-/**
- * Exports the task graph as a JSON object suitable for visualization tools.
- */
-interface GraphJson {
-    edges: {
-        source: string;
-        target: string;
-    }[];
-    nodes: {
-        configuration?: string;
-        id: string;
-        project: string;
-        status?: string;
-        target: string;
-    }[];
-    roots: string[];
-}
-declare const toGraphJson: (taskGraph: TaskGraph, taskStatuses?: Map<string, string>) => {
-    edges: GraphJson["edges"];
-    nodes: GraphJson["nodes"];
-    roots: string[];
-};
-/**
- * Generates a self-contained HTML file with an interactive task graph visualization.
- * Uses a simple force-directed layout with SVG rendering (no external dependencies).
- */
-declare const toGraphHtml: (taskGraph: TaskGraph, options?: GraphVisualizerOptions) => string;
-/**
- * Renders the task graph as ASCII art for terminal display.
- * @example
- * ```
- * Task Graph (6 tasks, 5 dependencies)
- *
- * app:build
- * ├── lib-a:build
- * │   └── lib-core:build
- * └── lib-b:build
- *     └── lib-core:build (*)
- *
- * (*) = already shown above
- * ```
- */
-declare const toGraphAscii: (taskGraph: TaskGraph, options?: GraphVisualizerOptions) => string;
-/**
- * Exports a project graph in DOT format.
- */
-declare const projectGraphToDot: (projectGraph: ProjectGraph) => string;
-export type { GraphFormat, GraphJson, GraphVisualizerOptions };
-export { projectGraphToDot, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot };

package/dist/incremental-hasher.d.ts

@@ -1,76 +0,0 @@
-/**
- * Incremental file hasher that only re-hashes files that have changed
- * since the last run, based on mtime comparison.
- *
- * This is the key performance optimization used by Nx's daemon and
- * Turborepo's daemon — on subsequent runs, only files whose mtime
- * changed need to be re-read and re-hashed.
- *
- * The snapshot (path → { mtime, hash }) is kept in memory and can
- * optionally be persisted to disk for cross-process reuse.
- */
-interface FileSnapshot {
-    /** xxh3-128 hash of file contents */
-    hash: string;
-    /** Last modification time in milliseconds */
-    mtimeMs: number;
-    /** File size in bytes (fast pre-check) */
-    size: number;
-}
-interface IncrementalHasherOptions {
-    /** Directories to skip (default: node_modules, .git, dist, coverage, .cache) */
-    ignoredDirs?: Set<string>;
-    /** File to persist the snapshot to (for cross-run reuse) */
-    snapshotPath?: string;
-    workspaceRoot: string;
-}
-declare class IncrementalFileHasher {
-    #private;
-    constructor(options: IncrementalHasherOptions);
-    /**
-     * Loads the snapshot from disk if available.
-     * Called automatically on first use.
-     */
-    load(): Promise<void>;
-    /**
-     * Persists the current snapshot to disk for cross-run reuse.
-     */
-    save(): Promise<void>;
-    /**
-     * Incrementally hashes all files in a directory.
-     *
-     * Only files whose mtime or size changed since the last snapshot
-     * are re-read and re-hashed. Unchanged files reuse the cached hash.
-     *
-     * Returns a map of relative paths → hashes.
-     */
-    hashDirectory(directoryPath: string): Promise<Record<string, string>>;
-    /**
-     * Returns how many files are in the snapshot (for diagnostics).
-     */
-    get snapshotSize(): number;
-    /**
-     * Clears the in-memory snapshot.
-     */
-    clear(): void;
-    /**
-     * Looks up the cached hash for `absolutePath` when its mtime and
-     * size match the snapshot; returns `undefined` otherwise. Callers
-     * that already have a `stat` result (e.g. `InProcessTaskHasher`)
-     * skip an extra syscall by passing it through directly.
-     *
-     * The snapshot is considered loaded on first call — lazy-load is
-     * synchronous-friendly here because the caller already performed
-     * an async `stat` before calling this method.
-     */
-    getSnapshotHash(absolutePath: string, mtimeMs: number, size: number): string | undefined;
-    /**
-     * Writes a fresh snapshot entry after the caller has computed the
-     * hash. Pairs with {@link IncrementalFileHasher.getSnapshotHash}
-     * — after a miss, the caller hashes the file and records the
-     * result here so the next run can reuse it.
-     */
-    recordSnapshot(absolutePath: string, hash: string, mtimeMs: number, size: number): void;
-}
-export type { FileSnapshot, IncrementalHasherOptions };
-export { IncrementalFileHasher };

package/dist/life-cycle.d.ts

@@ -1,38 +0,0 @@
-import type { LifeCycleInterface, Task, TaskResult, TaskStatus } from "./types.d.ts";
-/**
- * Combines multiple lifecycle handlers into one.
- * Each event is forwarded to all registered handlers.
- */
-declare class CompositeLifeCycle implements LifeCycleInterface {
-    #private;
-    constructor(lifeCycles: LifeCycleInterface[]);
-    startCommand(): void;
-    endCommand(): void;
-    scheduleTask(task: Task): void;
-    startTasks(tasks: Task[]): void;
-    endTasks(taskResults: TaskResult[]): void;
-    printTaskTerminalOutput(task: Task, status: TaskStatus, terminalOutput: string): void;
-    printCacheMiss(task: Task, reasons: string): void;
-    onTaskStdout(task: Task, chunk: string): void;
-    onTaskStderr(task: Task, chunk: string): void;
-}
-/**
- * A lifecycle handler that logs task progress to the console.
- */
-declare class ConsoleLifeCycle implements LifeCycleInterface {
-    #private;
-    constructor(verbose?: boolean);
-    startCommand(): void;
-    endCommand(): void;
-    scheduleTask(task: Task): void;
-    startTasks(tasks: Task[]): void;
-    endTasks(taskResults: TaskResult[]): void;
-    printTaskTerminalOutput(_task: Task, _status: TaskStatus, terminalOutput: string): void;
-    printCacheMiss(task: Task, reasons: string): void;
-}
-/**
- * A no-op lifecycle handler. Useful as a default.
- */
-declare class EmptyLifeCycle implements LifeCycleInterface {
-}
-export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle };

package/dist/lockfile-hasher.d.ts

@@ -1,73 +0,0 @@
-/**
- * Resolved dependency entry from a lockfile.
- */
-interface ResolvedDependency {
-    /** The package name */
-    name: string;
-    /** The resolved version */
-    version: string;
-}
-/**
- * Result of parsing a lockfile for a specific package.
- */
-interface PackageLockfileHash {
-    /** The resolved dependencies that were included in the hash */
-    dependencies: ResolvedDependency[];
-    /** Hash of the resolved dependencies relevant to this package */
-    hash: string;
-}
-/**
- * Extracts a package name from a node_modules path.
- * E.g., "node_modules/@scope/name" -> "@scope/name",
- * "node_modules/name" -> "name",
- * "node_modules/.package-lock.json" -> undefined.
- */
-declare const extractPackageName: (path: string) => string | undefined;
-/**
- * Parses package-lock.json (npm v2/v3 format) to extract resolved versions.
- * The v2/v3 format uses a flat "packages" map with paths like "node_modules/pkg-name".
- */
-declare const parseNpmLockfile: (content: string) => Map<string, string>;
-/**
- * Parses pnpm-lock.yaml to extract resolved versions.
- * Uses a lightweight regex-based parser to avoid a YAML dependency.
- */
-declare const parsePnpmLockfile: (content: string) => Map<string, string>;
-/**
- * Parses yarn.lock to extract resolved versions.
- * Works with both Yarn Classic (v1) and Berry (v2+) formats.
- */
-declare const parseYarnLockfile: (content: string) => Map<string, string>;
-/**
- * Smart lockfile hasher that only hashes the resolved versions
- * of a package's actual dependencies, not the entire lockfile.
- *
- * This matches Turborepo's smart lockfile hashing behavior:
- * changing the lockfile only busts cache for affected packages.
- *
- * Supports:
- * - package-lock.json (npm v2/v3)
- * - pnpm-lock.yaml (pnpm)
- * - yarn.lock (Yarn Classic + Berry)
- */
-declare class LockfileHasher {
-    #private;
-    constructor(workspaceRoot: string);
-    /**
-     * Computes a hash based only on the resolved dependency versions
-     * relevant to a specific package.
-     * @param packageJsonPath Path to the package.json (relative to workspace root)
-     * @returns Hash of the relevant lockfile entries, or undefined if no lockfile found
-     */
-    hashForPackage(packageJsonPath: string): Promise<PackageLockfileHash | undefined>;
-    /**
-     * Returns the type of lockfile detected, or undefined if none found.
-     */
-    get lockfileType(): "npm" | "pnpm" | "yarn" | undefined;
-    /**
-     * Clears the cached lockfile data.
-     */
-    clearCache(): void;
-}
-export type { PackageLockfileHash, ResolvedDependency };
-export { extractPackageName, LockfileHasher, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile };

package/dist/log-reporter.d.ts

@@ -1,34 +0,0 @@
-import type { LifeCycleInterface, Task, TaskResult, TaskStatus } from "./types.d.ts";
-/**
- * Output formatting mode for task terminal output.
- *
- * - `interleaved` **(default)**: emit each task's buffered output as-is
- *   — lines from parallel tasks may intermix when streamed live.
- * - `labeled`: prefix every line with `[project#target]` so parallel
- *   tasks remain distinguishable.
- * - `grouped`: buffer each task's output and print it as a single block
- *   bracketed by `── project#target ──` header and blank-line footer.
- *
- * Matches the three modes exposed by vite-task's `--log` flag.
- */
-export type LogMode = "grouped" | "interleaved" | "labeled";
-/**
- * A lifecycle handler that renders task terminal output per {@link LogMode}.
- *
- * Operates on the buffered `printTaskTerminalOutput` signal the orchestrator
- * emits at task-completion. Line-by-line streaming is the consumer's
- * responsibility — a streaming reporter can wrap this one and emit buffered
- * output at the end of each task regardless of streaming choices.
- */
-export declare class LogReporter implements LifeCycleInterface {
-    #private;
-    constructor(mode: LogMode, write?: (chunk: string) => void);
-    printTaskTerminalOutput(task: Task, _status: TaskStatus, terminalOutput: string): void;
-    endTasks(_taskResults: TaskResult[]): void;
-}
-/**
- * Convenience factory matching vite-task's `createLogReporter(mode)` surface.
- * Consumers that already compose their own lifecycle handlers can instantiate
- * {@link LogReporter} directly.
- */
-export declare const createLogReporter: (mode: LogMode, write?: (chunk: string) => void) => LogReporter;

package/dist/native-binding.d.ts

@@ -1,106 +0,0 @@
-/**
- * Optional native bindings for performance-critical operations.
- *
- * The native addon (Rust via napi-rs) provides:
- * - Parallel file hashing using rayon + xxHash xxh3-128
- * - Optimized task hash computation
- * - Fast graph operations (cycle detection, topological sort)
- *
- * Falls back to pure TypeScript implementations when the native
- * addon is not available (not compiled, wrong platform, etc.).
- *
- * Build with: pnpm build:native
- * The napi v3 CLI outputs the .node file to the package root.
- */
-interface NativeFileHash {
-    hash: string;
-    path: string;
-}
-interface NativeTaskHashDetails {
-    command: string;
-    implicit_deps?: string[][];
-    nodes: string[][];
-    runtime?: string[][];
-}
-interface NativeTaskGraph {
-    edges: string[][];
-    task_ids: string[];
-}
-interface NativeCycleResult {
-    cycle: string[];
-    has_cycle: boolean;
-}
-interface NativeConcurrentCommandConfig {
-    command: string;
-    cwd?: string;
-    env?: Record<string, string>;
-    name?: string;
-    shell?: boolean;
-    stdin?: string;
-}
-interface NativeConcurrentRunnerOptions {
-    killOthers?: string[];
-    killSignal?: string;
-    killTimeout?: number;
-    maxProcesses?: number;
-    shellPath?: string;
-    successCondition?: string;
-}
-interface NativeProcessEvent {
-    commandName?: string;
-    durationMs?: number;
-    exitCode?: number;
-    index: number;
-    killed?: boolean;
-    kind: string;
-    message?: string;
-    text?: string;
-}
-interface NativeConcurrentCloseEvent {
-    command: string;
-    durationMs: number;
-    exitCode: number;
-    index: number;
-    killed: boolean;
-    name?: string;
-}
-interface NativeConcurrentRunResult {
-    closeEvents: NativeConcurrentCloseEvent[];
-    success: boolean;
-}
-interface NativeBindings {
-    collectFiles: (directory: string) => string[];
-    computeTaskHash: (details: NativeTaskHashDetails) => string;
-    findAllCycles: (graph: NativeTaskGraph) => string[][];
-    findBackEdges: (graph: NativeTaskGraph) => string[][];
-    findCycle: (graph: NativeTaskGraph) => NativeCycleResult;
-    getDependentTasks: (graph: NativeTaskGraph, taskId: string) => string[];
-    getTransitiveDeps: (graph: NativeTaskGraph, taskId: string) => string[];
-    hashCommand: (project: string, target: string, configuration: string | undefined, overridesJson: string) => string;
-    hashEnvVar: (name: string, value: string) => string;
-    hashFile: (filePath: string) => string;
-    hashFilesBatch: (filePaths: string[], workspaceRoot: string) => NativeFileHash[];
-    hashFilesInDirectory: (directory: string, workspaceRoot: string) => NativeFileHash[];
-    hashString: (input: string) => string;
-    hashStrings: (inputs: string[]) => string;
-    runConcurrent: (commands: NativeConcurrentCommandConfig[], options: NativeConcurrentRunnerOptions, onEvent: (event: NativeProcessEvent) => void) => Promise<NativeConcurrentRunResult>;
-    runConcurrentBatch: (commands: NativeConcurrentCommandConfig[], options: NativeConcurrentRunnerOptions) => Promise<NativeConcurrentRunResult>;
-    topologicalSort: (graph: NativeTaskGraph) => string[];
-}
-/**
- * Attempts to load the native addon. Returns undefined if unavailable.
- * The result is cached after the first attempt.
- *
- * napi v3 outputs the .node file to the package root as
- * `task-runner-native.&lt;platform>.node`. The napi-generated index.js
- * handles platform detection automatically.
- *
- * Uses createRequire because the napi-generated index.js is CJS.
- */
-declare const loadNativeBindings: () => NativeBindings | undefined;
-/**
- * Returns true if the native addon is loaded and available.
- */
-declare const isNativeAvailable: () => boolean;
-export type { NativeBindings, NativeConcurrentCloseEvent, NativeConcurrentCommandConfig, NativeConcurrentRunnerOptions, NativeConcurrentRunResult, NativeCycleResult, NativeFileHash, NativeProcessEvent, NativeTaskGraph, NativeTaskHashDetails, };
-export { isNativeAvailable, loadNativeBindings };

package/dist/output-resolver.d.ts

@@ -1,20 +0,0 @@
-import type { OutputSpec } from "./types.d.ts";
-/**
- * Expands a task's `OutputSpec[]` into the concrete file list to
- * archive:
- *
- * - literal paths → kept as-is (the archiver recursively copies
- *   directories, so `"dist"` captures its whole tree);
- * - positive globs → expanded via `fs.glob`, filtered to files only;
- * - negatives (`!pattern`) → applied to the combined result;
- * - `{ auto: true }` → pulls in `autoWrites` entries that fall inside
- *   the workspace.
- *
- * Returns deduped, sorted workspace-relative paths so archives are
- * byte-reproducible across invocations.
- *
- * Silent degradation: missing literal paths, empty glob matches, and
- * `{ auto: true }` without tracked writes all contribute nothing
- * rather than throwing.
- */
-export declare const resolveOutputs: (workspaceRoot: string, outputs: OutputSpec[] | undefined, autoWrites?: ReadonlyArray<string>) => Promise<string[]>;

package/dist/project-constraints.d.ts

@@ -1,9 +0,0 @@
-import type { ConstraintsConfig, ConstraintViolation, ProjectGraph } from "./types.d.ts";
-/**
- * Enforces project dependency constraints on a project graph.
- * @param projectGraph The workspace project graph to validate.
- * @param constraints The constraint rules to enforce.
- * @returns Array of violations found. Empty means all constraints pass.
- */
-declare const enforceProjectConstraints: (projectGraph: ProjectGraph, constraints: ConstraintsConfig) => ConstraintViolation[];
-export { enforceProjectConstraints };