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

package/dist/remote-cache.d.ts

@@ -1,100 +0,0 @@
-/**
- * Compression algorithm used for artifact tarballs on the wire.
- * - `"gzip"` (default): tar+gzip, matches Turborepo's protocol format
- *   and stays interop-safe with existing remote cache servers.
- * - `"brotli"`: tar + Node brotli (BROTLI_MODE_TEXT, quality 4) — a
- *   solid ratio/speed trade-off for source-tree tarballs. Both upload
- *   and download sides must agree; switching invalidates existing
- *   remote entries (they will simply re-populate on next run).
- */
-export type RemoteCacheCompression = "brotli" | "gzip";
-/**
- * HMAC signing configuration for cache integrity.
- *
- * When set, every upload carries an `X-Artifact-Signature` header
- * containing the HMAC-SHA256 digest of `hash | body`. On download,
- * the client recomputes the HMAC and rejects any artifact whose
- * signature doesn't match using a constant-time comparison.
- *
- * Prevents cache poisoning in shared team environments where a
- * compromised cache server (or a MITM) could inject malicious
- * artifacts. Unsigned entries (written before signing was enabled)
- * are accepted only when `verifyOnDownload === false` — the default.
- */
-export interface RemoteCacheSigning {
-    /** Shared secret. Must be at least 16 characters. */
-    secret: string;
-    /**
-     * Reject downloads whose signature doesn't match or is missing.
-     * Set to `true` once every upload on your server is signed.
-     * @default false
-     */
-    verifyOnDownload?: boolean;
-}
-/**
- * Options for the remote cache.
- */
-interface RemoteCacheOptions {
-    /**
-     * Compression format for artifact tarballs. Defaults to `"gzip"`
-     * for Turborepo protocol compatibility.
-     */
-    compression?: RemoteCacheCompression;
-    /**
-     * Called when a fire-and-forget upload fails.
-     * Since uploads are non-blocking, errors are silently swallowed by default.
-     * Provide this callback to log or report upload failures.
-     */
-    onUploadError?: (hash: string, error: unknown) => void;
-    /** Whether to enable remote cache reads */
-    read?: boolean;
-    /**
-     * HMAC-SHA256 signing for upload integrity. When set, every
-     * uploaded artifact carries an `X-Artifact-Signature` header;
-     * downloads with `verifyOnDownload: true` reject unsigned or
-     * tampered payloads.
-     */
-    signing?: RemoteCacheSigning;
-    /** Team ID or namespace for cache isolation */
-    teamId?: string;
-    /** Request timeout in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Authentication token for the remote cache */
-    token?: string;
-    /** Remote cache server URL (e.g., "https://cache.example.com") */
-    url: string;
-    /** Whether to enable remote cache writes */
-    write?: boolean;
-}
-/**
- * HTTP-based remote cache compatible with the Turborepo remote cache protocol.
- *
- * Protocol:
- * - GET  /v8/artifacts/{hash}?teamId={team}  -> retrieve cached artifact (gzipped tar)
- * - PUT  /v8/artifacts/{hash}?teamId={team}  -> store artifact
- * - POST /v8/artifacts/events                -> analytics (optional)
- *
- * Authentication via `Authorization: Bearer {token}` header.
- *
- * The cache entry is a gzipped tarball containing the cache directory contents
- * (code, terminalOutput, fingerprint.json, outputs/, .commit).
- */
-declare class RemoteCache {
-    #private;
-    constructor(options: RemoteCacheOptions);
-    /**
-     * Retrieves a cached artifact from the remote cache.
-     * Returns the local path to the extracted cache entry, or undefined if not found.
-     */
-    retrieve(hash: string, localCacheDirectory: string): Promise<boolean>;
-    /**
-     * Stores a cache entry in the remote cache.
-     */
-    store(hash: string, localCacheDirectory: string): Promise<boolean>;
-    /**
-     * Checks if an artifact exists in the remote cache without downloading it.
-     */
-    exists(hash: string): Promise<boolean>;
-}
-export type { RemoteCacheOptions };
-export { RemoteCache };

package/dist/run-summary.d.ts

@@ -1,111 +0,0 @@
-import type { OutputSpec, TaskGraph, TaskHashDetails, TaskResults } from "./types.d.ts";
-/**
- * Summary of a single task execution.
- */
-interface TaskSummary {
-    /** Whether the task was cacheable */
-    cacheable: boolean;
-    /** Cache status */
-    cacheStatus: "HIT" | "MISS" | "REMOTE_HIT" | "SKIPPED";
-    /** Dependencies on other tasks */
-    dependencies: string[];
-    /** Duration in milliseconds */
-    duration: number | undefined;
-    /** End time (ISO 8601) */
-    endTime: string | undefined;
-    /** Exit code */
-    exitCode: number | undefined;
-    /** The computed cache hash */
-    hash: string | undefined;
-    /** Detailed hash information */
-    hashDetails: TaskHashDetails | undefined;
-    /** The task's declared outputs (glob patterns, literals, or `{ auto: true }`). */
-    outputs: OutputSpec[];
-    /** Start time (ISO 8601) */
-    startTime: string | undefined;
-    /** The task target */
-    target: {
-        configuration?: string;
-        project: string;
-        target: string;
-    };
-    /** The task ID (e.g., "app:build") */
-    taskId: string;
-}
-/**
- * Complete summary of a task runner execution.
- */
-interface RunSummary {
-    /** Total duration in milliseconds */
-    duration: number;
-    /** Run end time (ISO 8601) */
-    endTime: string;
-    /** Environment info */
-    environment: {
-        /** Architecture */
-        arch: string;
-        /** Node.js version */
-        nodeVersion: string;
-        /** Platform */
-        platform: string;
-    };
-    /** Unique run ID */
-    id: string;
-    /** Run start time (ISO 8601) */
-    startTime: string;
-    /** Overall execution statistics */
-    stats: {
-        /** Number of cached tasks (local + remote) */
-        cached: number;
-        /** Number of failed tasks */
-        failed: number;
-        /** Number of skipped tasks */
-        skipped: number;
-        /** Number of successful tasks */
-        succeeded: number;
-        /** Total number of tasks */
-        total: number;
-    };
-    /** The task graph used for this run */
-    taskGraph: {
-        dependencies: Record<string, string[]>;
-        roots: string[];
-    };
-    /** Summary of each task */
-    tasks: TaskSummary[];
-}
-/**
- * Generates a run summary from task results.
- */
-declare const generateRunSummary: (results: TaskResults, taskGraph: TaskGraph, startTime: number) => RunSummary;
-/**
- * Writes the run summary to a JSON file in the `.task-runner/runs/` directory.
- * @param summary The run summary to write
- * @param workspaceRoot The workspace root directory
- * @returns The path to the written summary file
- */
-declare const writeRunSummary: (summary: RunSummary, workspaceRoot: string) => Promise<string>;
-/**
- * Path where the most-recent run summary is persisted.
- * Consumers (e.g. CLIs exposing `--last-details`) read this file
- * to replay or render the previous run without re-executing.
- */
-declare const getLastRunSummaryPath: (workspaceRoot: string) => string;
-/**
- * Persists `summary` as the most-recent run summary at
- * `.task-runner/last-summary.json`, overwriting any previous entry.
- *
- * This is the companion to {@link readLastRunSummary} and powers
- * CLI surfaces that display "last run" details without re-running tasks.
- * @returns The path to the written summary file
- */
-declare const writeLastRunSummary: (summary: RunSummary, workspaceRoot: string) => Promise<string>;
-/**
- * Reads the most-recent run summary written by {@link writeLastRunSummary}.
- * Returns `undefined` when no previous run has been recorded or the file
- * cannot be parsed — callers should render an informational message
- * instead of treating this as an error.
- */
-declare const readLastRunSummary: (workspaceRoot: string) => Promise<RunSummary | undefined>;
-export type { RunSummary, TaskSummary };
-export { generateRunSummary, getLastRunSummaryPath, readLastRunSummary, writeLastRunSummary, writeRunSummary };

package/dist/task-graph-utils.d.ts

@@ -1,39 +0,0 @@
-import type { TaskGraph } from "./types.d.ts";
-/**
- * Finds a single cycle in the task graph, if one exists.
- * Returns the cycle as an array of task IDs, or null if no cycle exists.
- */
-export declare const findCycle: (taskGraph: TaskGraph) => string[] | undefined;
-/**
- * Finds all cycles in the task graph.
- */
-export declare const findCycles: (taskGraph: TaskGraph) => string[][];
-/**
- * Walks the task graph in topological order (dependencies before dependents),
- * calling the callback for each task.
- *
- * Note: If the graph contains cycles, tasks involved in cycles will not be visited.
- * Use `findCycle` to detect cycles before walking if complete traversal is required.
- */
-export declare const walkTaskGraph: (taskGraph: TaskGraph, callback: (taskId: string) => void) => void;
-/**
- * Returns a reversed copy of the task graph (edges point in the opposite direction).
- */
-export declare const reverseTaskGraph: (taskGraph: TaskGraph) => TaskGraph;
-/**
- * Returns the leaf tasks (tasks with no dependencies of their own).
- */
-export declare const getLeafTasks: (taskGraph: TaskGraph) => string[];
-/**
- * Removes edges that form cycles, making the graph acyclic.
- * Returns a new task graph without the cycle-forming edges.
- */
-export declare const makeAcyclic: (taskGraph: TaskGraph) => TaskGraph;
-/**
- * Gets all tasks that depend on the given task (directly or transitively).
- */
-export declare const getDependentTasks: (taskGraph: TaskGraph, taskId: string) => string[];
-/**
- * Gets all tasks that the given task depends on (directly or transitively).
- */
-export declare const getTransitiveDependencies: (taskGraph: TaskGraph, taskId: string) => string[];

package/dist/task-graph.d.ts

@@ -1,22 +0,0 @@
-import type { ProjectGraph, TargetConfiguration, Task, TaskGraph, TaskTarget, WorkspaceConfiguration } from "./types.d.ts";
-interface CreateTaskGraphOptions {
-    /** The project graph */
-    projectGraph: ProjectGraph;
-    /** Target default configurations */
-    targetDefaults?: Record<string, Partial<TargetConfiguration>>;
-    /** The workspace configuration */
-    workspace: WorkspaceConfiguration;
-}
-/**
- * Creates a unique task ID from a target.
- */
-declare const getTaskId: (target: TaskTarget) => string;
-/**
- * Parses a task ID into its component parts.
- */
-declare const parseTaskId: (taskId: string) => TaskTarget;
-/**
- * Creates a task graph from a list of tasks, resolving all dependencies.
- */
-declare const createTaskGraph: (initialTasks: Task[], options: CreateTaskGraphOptions) => TaskGraph;
-export { createTaskGraph, getTaskId, parseTaskId };

package/dist/task-hasher.d.ts

@@ -1,104 +0,0 @@
-import type { IncrementalFileHasher } from "./incremental-hasher.d.ts";
-import type { NamedInputs, ProjectConfiguration, TargetConfiguration, Task, TaskHashDetails } from "./types.d.ts";
-/**
- * Interface for task hashers.
- */
-interface TaskHasher {
-    hashTask: (task: Task) => Promise<TaskHashDetails>;
-    /**
-     * Rehashes a single file bypassing any in-memory cache. Optional to keep
-     * external/custom hashers backward compatible; the orchestrator skips
-     * self-modifying-task detection when the implementation is absent.
-     */
-    rehashFile?: (filePath: string) => Promise<string | undefined>;
-}
-/**
- * Options for creating an InProcessTaskHasher.
- */
-interface TaskHasherOptions {
-    /**
-     * When true, scan each task's resolved command for `$VAR`/`${VAR}`
-     * references and auto-fingerprint them. Catches the common case of
-     * a script reading `$VERCEL_URL` or `${NEXT_PUBLIC_API}` without
-     * the user remembering to declare it in `envVars`/`globalEnv`.
-     * @default false
-     */
-    autoEnvVars?: boolean;
-    /** Additional environment variables to include in hash */
-    envVars?: string[];
-    /**
-     * Enable framework environment variable inference.
-     * When true, auto-detects frameworks and includes their public
-     * env var prefixes in the task hash.
-     * @default false
-     */
-    frameworkInference?: boolean;
-    /**
-     * Global environment variables that invalidate all task hashes.
-     */
-    globalEnv?: string[];
-    /**
-     * Global input files that invalidate all task hashes when changed.
-     * These are workspace-root-relative paths (e.g., "pnpm-lock.yaml").
-     */
-    globalInputs?: string[];
-    /**
-     * Optional persistent mtime/size-indexed file snapshot. When set,
-     * `#hashFile` consults the snapshot first and only re-reads file
-     * contents when the file's mtime or size has changed since the
-     * previous run. Cuts cold-cache fingerprint time dramatically on
-     * large workspaces where most source files don't change run-to-run.
-     *
-     * The caller is responsible for `load()`ing the snapshot before
-     * using the hasher and `save()`ing it after the run completes.
-     */
-    incrementalHasher?: IncrementalFileHasher;
-    /** Named input definitions */
-    namedInputs?: NamedInputs;
-    /** Project configurations keyed by project name */
-    projects: Record<string, ProjectConfiguration>;
-    /**
-     * Enable smart lockfile hashing.
-     * When true, instead of hashing the entire lockfile, only the resolved
-     * versions of a package's actual dependencies are hashed.
-     * This means changing the lockfile only busts cache for affected packages.
-     *
-     * Matches Turborepo's smart lockfile hashing behavior.
-     * @default false
-     */
-    smartLockfileHashing?: boolean;
-    /** Target default configurations */
-    targetDefaults?: Record<string, Partial<TargetConfiguration>>;
-    /** The workspace root directory */
-    workspaceRoot: string;
-}
-/**
- * Computes hashes for tasks based on their inputs.
- * Used to determine if a cached result can be reused.
- */
-declare class InProcessTaskHasher implements TaskHasher {
-    #private;
-    constructor(options: TaskHasherOptions);
-    hashTask(task: Task): Promise<TaskHashDetails>;
-    clearCache(): void;
-    /**
-     * Reads `filePath` fresh and returns its content hash, bypassing the
-     * in-memory cache used during the initial `hashTask` pass.
-     *
-     * Used to detect tasks that modify their own tracked inputs: compare
-     * a pre-execution hash (from `task.hashDetails.nodes`) against the
-     * post-execution result of this method.
-     * @param filePath Absolute path to the file.
-     * @returns The fresh xxh3 hash, or `undefined` if the file cannot be read.
-     */
-    rehashFile(filePath: string): Promise<string | undefined>;
-}
-/**
- * Computes the final hash for a task from its hash details.
- * Uses native Rust xxh3-128 when available, otherwise pure TS xxh3-ts.
- * Both produce identical xxh3-128 hashes, ensuring cache compatibility
- * regardless of whether the native addon is loaded.
- */
-declare const computeTaskHash: (hashDetails: TaskHashDetails) => string;
-export { computeTaskHash, InProcessTaskHasher };
-export type { TaskHasher, TaskHasherOptions };

package/dist/task-orchestrator.d.ts

@@ -1,38 +0,0 @@
-import type { Cache } from "./cache.d.ts";
-import type { RemoteCache } from "./remote-cache.d.ts";
-import type { TaskHasher } from "./task-hasher.d.ts";
-import type { TaskScheduler } from "./task-scheduler.d.ts";
-import type { LifeCycleInterface, Task, TaskExecutor, TaskGraph, TaskResults } from "./types.d.ts";
-/**
- * Options for the TaskOrchestrator.
- */
-interface TaskOrchestratorOptions {
-    autoFingerprint?: boolean;
-    cache: Cache;
-    cacheDiagnostics?: boolean;
-    captureOutput?: boolean;
-    dryRun?: boolean;
-    fingerprintEnvPatterns?: string[];
-    lifeCycle: LifeCycleInterface;
-    remoteCache?: RemoteCache;
-    resolveCommand?: (task: Task) => string | undefined;
-    scheduler: TaskScheduler;
-    skipCache?: boolean;
-    summarize?: boolean;
-    taskExecutor: TaskExecutor;
-    taskGraph?: TaskGraph;
-    taskHasher: TaskHasher;
-    untrackedEnvVars?: string[];
-    workspaceRoot: string;
-}
-/**
- * Orchestrates the execution of tasks, handling caching,
- * scheduling, and lifecycle events.
- */
-declare class TaskOrchestrator {
-    #private;
-    constructor(options: TaskOrchestratorOptions);
-    run(): Promise<TaskResults>;
-}
-export { TaskOrchestrator };
-export type { TaskOrchestratorOptions };

package/dist/task-scheduler.d.ts

@@ -1,41 +0,0 @@
-import type { ProjectGraph, Task, TaskGraph } from "./types.d.ts";
-/**
- * Options for partitioning tasks across CI runners.
- */
-export interface PartitionOptions {
-    /** 1-based partition index (e.g., 1 for the first partition) */
-    index: number;
-    /** Total number of partitions */
-    total: number;
-}
-/**
- * Parses a partition string like "1/4" into PartitionOptions.
- * Also supports the VIS_PARTITION environment variable as fallback.
- */
-export declare const parsePartition: (value?: string) => PartitionOptions | undefined;
-/**
- * Manages the scheduling order of tasks based on dependencies,
- * parallelism constraints, and estimated execution times.
- */
-export declare class TaskScheduler {
-    #private;
-    /**
-     * Partitions a list of tasks for distributed CI execution.
-     * Tasks are sorted by ID for deterministic distribution, then split
-     * using ceiling division so partitions differ by at most one task.
-     * @param tasks The full list of tasks to partition
-     * @param partition The partition configuration (1-based index and total)
-     * @returns The subset of tasks assigned to this partition
-     */
-    static partitionTasks(tasks: Task[], partition: PartitionOptions): Task[];
-    constructor(taskGraph: TaskGraph, projectGraph: ProjectGraph, maxParallel?: number);
-    /**
-     * Returns the next batch of tasks that are ready to execute.
-     */
-    getNextBatch(): Task[];
-    startTask(taskId: string): void;
-    completeTask(taskId: string): void;
-    isComplete(): boolean;
-    get remainingCount(): number;
-    get runningCount(): number;
-}

package/dist/terminal-buffer.d.ts

@@ -1,29 +0,0 @@
-/**
- * Minimal virtual terminal buffer that processes ANSI escape sequences
- * for cursor movement and line erasure. This allows PTY output from
- * interactive tools (inquirer, etc.) to render correctly by updating
- * lines in place rather than always appending.
- *
- * Supported sequences:
- * - \r       carriage return (cursor to column 0)
- * - \n       line feed (new line)
- * - \x1b[nA  cursor up n lines
- * - \x1b[nB  cursor down n lines
- * - \x1b[nC  cursor forward n columns
- * - \x1b[nD  cursor back n columns
- * - \x1b[nG  cursor to column n
- * - \x1b[r;cH cursor position
- * - \x1b[K   erase from cursor to end of line (0K, 1K, 2K)
- * - \x1b[J   erase from cursor to end of display (0J, 1J, 2J)
- * - \x1b[...m SGR (colors/styles) — passed through into output
- */
-export declare class TerminalBuffer {
-    #private;
-    constructor(maxBytes?: number);
-    /**
-     * Process raw PTY output data.
-     */
-    write(data: string): void;
-    /** Get the current buffer content as a string. */
-    toString(): string;
-}

package/dist/tracked-executor.d.ts

@@ -1,46 +0,0 @@
-import type { FileAccess } from "./file-access-tracker.d.ts";
-import type { Task, TaskExecutionOptions } from "./types.d.ts";
-/**
- * Result of a tracked task execution.
- */
-export interface TrackedExecutionResult {
-    /** File accesses recorded during execution */
-    accesses: FileAccess[];
-    /** The command exit code */
-    code: number;
-    /** The command stdout + stderr output */
-    terminalOutput: string;
-}
-/**
- * A task executor that tracks file accesses during command execution.
- *
- * Tracking strategies (in priority order):
- * 1. **Linux**: strace-based syscall interception (most complete)
- * 2. **macOS/Windows**: Node.js preload script that patches `fs` module
- * (works for Node.js processes, not native binaries)
- * 3. **Fallback**: No tracking (accesses array will be empty)
- */
-export declare class TrackedTaskExecutor {
-    #private;
-    constructor(workspaceRoot: string);
-    /**
-     * Returns true if file access tracking is supported on the current platform.
-     * strace tracking (Linux) or preload script (any Node.js process).
-     */
-    get isTrackingSupported(): boolean;
-    /**
-     * Returns true if the platform supports full syscall-level tracking (strace).
-     */
-    get isStraceSupported(): boolean;
-    /**
-     * Executes a task command and tracks all file system accesses.
-     *
-     * On Linux, uses strace for comprehensive tracking.
-     * On other platforms, uses a Node.js preload script (for Node processes).
-     */
-    execute(task: Task, options: TaskExecutionOptions, command: string): Promise<TrackedExecutionResult>;
-    /**
-     * Kills all active child processes. Called on abort/signal to prevent orphans.
-     */
-    killAll(): void;
-}