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

package/dist/packem_shared/toChromeTrace-B2tZoJ-7.js

@@ -0,0 +1,121 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  writeFile
+} = __cjs_getBuiltinModule("node:fs/promises");
+
+const TASK_CATEGORY = "task";
+const FLOW_CATEGORY = "dep";
+const PID = 1;
+const toChromeTrace = (summary) => {
+  const events = [];
+  const traceStartMs = Date.parse(summary.startTime);
+  const tasksByStart = [...summary.tasks].sort((a, b) => {
+    const aStart = a.startTime ? Date.parse(a.startTime) : Number.POSITIVE_INFINITY;
+    const bStart = b.startTime ? Date.parse(b.startTime) : Number.POSITIVE_INFINITY;
+    return aStart - bStart;
+  });
+  const lanes = [];
+  const taskLane = /* @__PURE__ */ new Map();
+  for (const task of tasksByStart) {
+    if (!task.startTime || !task.endTime) {
+      continue;
+    }
+    const startMs = Date.parse(task.startTime);
+    const endMs = Date.parse(task.endTime);
+    let lane = lanes.findIndex((laneEnd) => laneEnd <= startMs);
+    if (lane === -1) {
+      lane = lanes.length;
+      lanes.push(endMs);
+    } else {
+      lanes[lane] = endMs;
+    }
+    taskLane.set(task.taskId, lane);
+    events.push({
+      args: {
+        cacheStatus: task.cacheStatus,
+        exitCode: task.exitCode,
+        hash: task.hash,
+        project: task.target.project,
+        target: task.target.target
+      },
+      cat: TASK_CATEGORY,
+      dur: Math.max(0, (endMs - startMs) * 1e3),
+      name: task.taskId,
+      ph: "X",
+      pid: PID,
+      tid: lane,
+      ts: (startMs - traceStartMs) * 1e3
+    });
+  }
+  let flowId = 1;
+  for (const task of summary.tasks) {
+    if (!task.startTime || !task.endTime) {
+      continue;
+    }
+    const dependents = task.dependencies ?? [];
+    for (const depId of dependents) {
+      const dep = summary.tasks.find((t) => t.taskId === depId);
+      if (!dep?.endTime || !task.startTime) {
+        continue;
+      }
+      const depEndUs = (Date.parse(dep.endTime) - traceStartMs) * 1e3;
+      const taskStartUs = (Date.parse(task.startTime) - traceStartMs) * 1e3;
+      const id = flowId;
+      flowId += 1;
+      events.push(
+        {
+          cat: FLOW_CATEGORY,
+          id,
+          name: `${depId} → ${task.taskId}`,
+          ph: "s",
+          pid: PID,
+          tid: taskLane.get(depId) ?? 0,
+          ts: depEndUs
+        },
+        {
+          cat: FLOW_CATEGORY,
+          id,
+          name: `${depId} → ${task.taskId}`,
+          ph: "f",
+          pid: PID,
+          tid: taskLane.get(task.taskId) ?? 0,
+          ts: taskStartUs
+        }
+      );
+    }
+  }
+  events.unshift({
+    args: { name: `vis run (${summary.id})` },
+    cat: "__metadata",
+    name: "process_name",
+    ph: "M",
+    pid: PID,
+    tid: 0,
+    ts: 0
+  });
+  return events;
+};
+const writeChromeTrace = async (summary, outputPath) => {
+  const events = toChromeTrace(summary);
+  await writeFile(outputPath, JSON.stringify({ traceEvents: events }));
+};
+
+export { toChromeTrace, writeChromeTrace };

package/dist/remote-cache.d.ts

@@ -1,7 +1,45 @@
+/**
+ * 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.
@@ -10,6 +48,13 @@ interface RemoteCacheOptions {
     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) */

package/dist/run-summary.d.ts

@@ -1,4 +1,4 @@
-import type { TaskGraph, TaskHashDetails, TaskResults } from "./types.d.ts";
+import type { OutputSpec, TaskGraph, TaskHashDetails, TaskResults } from "./types.d.ts";
 /**
  * Summary of a single task execution.
  */
@@ -19,8 +19,8 @@ interface TaskSummary {
     hash: string | undefined;
     /** Detailed hash information */
     hashDetails: TaskHashDetails | undefined;
-    /** The task's declared outputs */
-    outputs: string[];
+    /** The task's declared outputs (glob patterns, literals, or `{ auto: true }`). */
+    outputs: OutputSpec[];
     /** Start time (ISO 8601) */
     startTime: string | undefined;
     /** The task target */
@@ -85,5 +85,27 @@ declare const generateRunSummary: (results: TaskResults, taskGraph: TaskGraph, s
  * @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, writeRunSummary };
+export { generateRunSummary, getLastRunSummaryPath, readLastRunSummary, writeLastRunSummary, writeRunSummary };

package/dist/task-hasher.d.ts

@@ -1,14 +1,29 @@
+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[];
     /**
@@ -27,6 +42,17 @@ interface TaskHasherOptions {
      * 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 */
@@ -55,6 +81,17 @@ declare class InProcessTaskHasher implements TaskHasher {
     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.

package/dist/task-orchestrator.d.ts

@@ -2,7 +2,7 @@ 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, TaskResults } from "./types.d.ts";
+import type { LifeCycleInterface, Task, TaskExecutor, TaskGraph, TaskResults } from "./types.d.ts";
 /**
  * Options for the TaskOrchestrator.
  */
@@ -20,7 +20,7 @@ interface TaskOrchestratorOptions {
     skipCache?: boolean;
     summarize?: boolean;
     taskExecutor: TaskExecutor;
-    taskGraph?: import("./types").TaskGraph;
+    taskGraph?: TaskGraph;
     taskHasher: TaskHasher;
     untrackedEnvVars?: string[];
     workspaceRoot: string;

package/dist/types.d.ts

@@ -12,6 +12,32 @@ export interface TaskTarget {
 /**
  * Represents a single task to be executed.
  */
+/**
+ * Scheduling priority hint. The scheduler picks higher-priority tasks
+ * out of the ready-queue first; ties fall through to the graph-derived
+ * signals (dependent count, project depth).
+ *
+ * Use `"high"` for long-running leaves you want to kick off early
+ * (integration tests, e2e suites) so their wall-clock overlaps with
+ * the main build phase. Use `"low"` for work you don't mind deferring
+ * (linters, coverage uploads) when faster tasks contend for slots.
+ */
+export type TaskPriority = "high" | "low" | "normal";
+/**
+ * A single entry in a task's `outputs` list.
+ *
+ * - `string` — a literal path *or* a glob pattern relative to the
+ *   workspace root. Prefix with `!` to exclude files the positive
+ *   patterns would otherwise include (e.g. `"!dist/cache/**"`).
+ * - `{ auto: true }` — use whatever files the task actually wrote
+ *   during execution (resolved from the file-access tracker). Lets
+ *   authors who don't know their exact output layout cache results
+ *   without listing every path. Silently behaves as "no outputs" when
+ *   tracking isn't active for this task.
+ */
+export type OutputSpec = string | {
+    auto: true;
+};
 export interface Task {
     /** Whether this task is eligible for caching */
     cache?: boolean;
@@ -21,12 +47,22 @@ export interface Task {
     hashDetails?: TaskHashDetails;
     /** Unique identifier for the task, typically "project:target:configuration" */
     id: string;
-    /** Output file paths produced by this task */
-    outputs: string[];
+    /**
+     * Output patterns this task produces. Each entry is either a
+     * literal path, a glob (`"dist/**"`), a negative glob
+     * (`"!dist/cache/**"`), or `{ auto: true }` to pick up whatever
+     * files the task wrote during execution.
+     */
+    outputs: OutputSpec[];
     /** Overrides/extra options passed to the task */
     overrides: Record<string, unknown>;
     /** Whether this task supports parallel execution */
     parallelism?: boolean;
+    /**
+     * Explicit scheduling priority. Outranks the scheduler's
+     * graph-derived heuristics. Defaults to `"normal"` when absent.
+     */
+    priority?: TaskPriority;
     /** The project root directory */
     projectRoot?: string;
     /** The target this task executes */
@@ -66,8 +102,23 @@ export type TaskStatus = "success" | "failure" | "skipped" | "local-cache" | "lo
 export interface TaskResult {
     /** The exit code, if applicable */
     code?: number;
+    /**
+     * Set when auto-fingerprint tracking was attempted for this task but
+     * returned zero workspace accesses — usually a static binary on
+     * macOS/Windows, where the Node preload can't attach. Caching is
+     * skipped to avoid persisting an empty fingerprint that would
+     * produce false cache hits on every subsequent run.
+     */
+    emptyFingerprint?: boolean;
     /** The end time of the task */
     endTime?: number;
+    /**
+     * Set when the task modified one or more of its own tracked input
+     * files during execution. Caching is skipped in this case — the
+     * fingerprint captured before the run would mismatch the post-run
+     * contents and produce false cache hits on subsequent runs.
+     */
+    selfModified?: boolean;
     /** The start time of the task */
     startTime?: number;
     status: TaskStatus;
@@ -145,11 +196,30 @@ export interface TargetDependencyConfig {
  * Defines an input for cache invalidation.
  */
 export type InputDefinition = FileSetInput | RuntimeInput | EnvironmentInput | ExternalDependencyInput;
+/**
+ * Controls how a glob pattern is anchored.
+ * - "package" (default): pattern is resolved relative to the project root
+ * - "workspace": pattern is resolved relative to the workspace root
+ */
+export type FileSetBase = "package" | "workspace";
 /**
  * An input based on file patterns.
+ *
+ * `fileset` may be a bare glob string (package-root relative) or an object
+ * form `{ pattern, base }` to anchor explicitly to the workspace root.
+ * Negation (`!` prefix) works in both forms.
  */
 export interface FileSetInput {
-    fileset: string;
+    fileset: FileSetPattern | string;
+}
+/**
+ * Object form of a fileset pattern, for anchoring to the workspace root.
+ */
+export interface FileSetPattern {
+    /** Anchor for the pattern. */
+    base: FileSetBase;
+    /** Glob pattern (may start with `!` for negation). */
+    pattern: string;
 }
 /**
  * An input based on a runtime command.
@@ -311,6 +381,14 @@ export interface NamedInputs {
  * Configuration for the task runner.
  */
 export interface TaskRunnerOptions {
+    /**
+     * Scan each task's resolved command text for `$VAR`/`${VAR}`
+     * references and automatically fingerprint those env vars. Catches
+     * tasks like `curl ${VERCEL_URL}/api` where the user forgot to
+     * declare the reference in `envVars`/`globalEnv`.
+     * @default false
+     */
+    autoEnvVars?: boolean;
     /**
      * Enable auto-fingerprinting mode (Vite Task-style).
      * When enabled, the task runner automatically tracks which files
@@ -374,12 +452,37 @@ export interface TaskRunnerOptions {
      * forcing a full rebuild. This matches Turborepo's `globalDependencies`.
      */
     globalInputs?: string[];
+    /**
+     * When `true`, file hashes are cached in a persistent mtime+size
+     * indexed snapshot under `node_modules/.cache/task-runner/`. On
+     * subsequent runs, unchanged files skip content re-reads — cuts
+     * cold-cache fingerprint time dramatically on large workspaces.
+     *
+     * Changed or new files still get full content hashing. Safe to
+     * leave on by default; overhead when nothing matches is a single
+     * `stat` call per file.
+     * @default false
+     */
+    incrementalFileHashing?: boolean;
     /** Maximum age of cache entries in milliseconds */
     maxCacheAge?: number;
     /** Maximum cache size (e.g., "1GB") */
     maxCacheSize?: string;
     /** Named inputs for cache invalidation */
     namedInputs?: NamedInputs;
+    /**
+     * When `true`, the cache directory is partitioned by a hash of
+     * the resolved `globalEnv` values. Changing a globalEnv var moves
+     * cache writes into a new namespace; rolling it back reuses the
+     * old namespace and its hits. Without this option, any globalEnv
+     * change silently busts every cached entry.
+     *
+     * Keep disabled when globalEnv is stable across runs — the extra
+     * path depth offers no value, and misconfigured namespaces can
+     * hide stale hits.
+     * @default false
+     */
+    namespaceByGlobalEnv?: boolean;
     /** Maximum number of parallel tasks */
     parallel?: number | boolean;
     /**
@@ -614,8 +717,39 @@ export interface ConcurrentRunResult {
 export interface LifeCycleInterface {
     endCommand?: () => void;
     endTasks?: (taskResults: TaskResult[]) => void;
+    /**
+     * Called when a running task emits data on stderr, in the order the
+     * data arrives. Executors that support streaming output (`vis run`'s
+     * concurrent executor) forward chunks here verbatim. Executors that
+     * only buffer full output (e.g. the simple test executor) skip this
+     * hook — rely on `printTaskTerminalOutput` for the final dump.
+     *
+     * Handlers should be non-blocking; the orchestrator doesn't await.
+     */
+    onTaskStderr?: (task: Task, chunk: string) => void;
+    /**
+     * Called when a running task emits data on stdout, in the order the
+     * data arrives. See {@link LifeCycleInterface.onTaskStderr} for
+     * semantics — same contract, different stream.
+     */
+    onTaskStdout?: (task: Task, chunk: string) => void;
     /** Called when a cache miss occurs with diagnostic information */
     printCacheMiss?: (task: Task, reasons: string) => void;
+    /**
+     * Called when caching was skipped because auto-fingerprint tracking
+     * came back empty — a signal that the tracker (strace or Node
+     * preload) couldn't observe the task's file access, typically
+     * because it's a static binary on a platform without strace.
+     * `reason` is a short human-readable diagnostic.
+     */
+    printEmptyFingerprintWarning?: (task: Task, reason: string) => void;
+    /**
+     * Called when caching is skipped because the task modified one or
+     * more of its own tracked inputs. `modifiedFiles` lists the
+     * workspace-relative paths that changed between pre- and
+     * post-execution hashes.
+     */
+    printSelfModifyingSkip?: (task: Task, modifiedFiles: string[]) => void;
     printTaskTerminalOutput?: (task: Task, status: TaskStatus, terminalOutput: string) => void;
     scheduleTask?: (task: Task) => void;
     startCommand?: () => void;