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

package/CHANGELOG.md

@@ -1,3 +1,34 @@
+## @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

package/dist/archive.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared tar + brotli archive helpers.
+ *
+ * Both the local cache (`cache.ts`) and remote cache (`remote-cache.ts`)
+ * archive file trees into compressed tarballs. This module consolidates
+ * the compression parameters and stream plumbing so both paths stay in
+ * sync — same brotli quality, same error-handling shape, one place to
+ * audit.
+ */
+/**
+ * Brotli quality 4 hits a sweet spot for cache tarballs: ~15–20% smaller
+ * than gzip on typical source/dist payloads at comparable throughput.
+ * Higher qualities (8+) reach diminishing returns and noticeably slow
+ * down cache writes; lower qualities (1–3) give up ratio for speed we
+ * don't need on IO-bound workloads.
+ */
+export declare const BROTLI_COMPRESS_OPTIONS: {
+    params: Record<number, number>;
+};
+/** Plain tar: `sourceDir` → `outputPath`, no compression. */
+export declare const createTar: (sourceDirectory: string, outputPath: string) => Promise<void>;
+/** Plain tar extract into `destinationDirectory`. */
+export declare const extractTar: (archivePath: string, destinationDirectory: string) => Promise<void>;
+/** tar + gzip (`-czf`). Used when Turborepo-protocol compatibility matters. */
+export declare const createTarGz: (sourceDirectory: string, outputPath: string) => Promise<void>;
+export declare const extractTarGz: (archivePath: string, destinationDirectory: string) => Promise<void>;
+/**
+ * Creates an uncompressed tar, then streams it through brotli into
+ * `outputPath`. Two-step (tar-to-temp, brotli-stream) to avoid
+ * shelling out to an external `brotli` binary that may not exist.
+ * Cleans up the intermediate tar even when compression fails.
+ */
+export declare const createTarBrotli: (sourceDirectory: string, outputPath: string) => Promise<void>;
+/**
+ * Inverse of {@link createTarBrotli}: decompresses into a temp tar,
+ * then extracts. Temp is cleaned in `finally`.
+ */
+export declare const extractTarBrotli: (archivePath: string, destinationDirectory: string) => Promise<void>;

package/dist/cache.d.ts

@@ -1,4 +1,5 @@
 import type { TaskFingerprint } from "./fingerprint.d.ts";
+import type { OutputSpec } from "./types.d.ts";
 /**
  * Represents a cached task result.
  */
@@ -18,6 +19,17 @@ interface CachedResult {
 interface CacheOptions {
     /** The cache directory (defaults to `{workspaceRoot}/.task-runner-cache`) */
     cacheDirectory?: string;
+    /**
+     * Optional isolation namespace appended to the cache directory
+     * as `<cacheDir>/ns/<namespace>`. When the caller derives the
+     * namespace from the resolved global-env fingerprint, flipping an
+     * env var sends writes into a new namespace while keeping the old
+     * namespace intact — rolling the env back restores the old hits.
+     *
+     * Filesystem-safe segment; callers are responsible for sanitising
+     * (slashes/colons would break path resolution).
+     */
+    cacheNamespace?: string;
     /** Maximum age of cache entries in milliseconds (default: 7 days) */
     maxCacheAge?: number;
     /** Maximum cache size (e.g., "500MB", "1GB") */
@@ -78,12 +90,28 @@ declare class Cache {
      *
      * Uses atomic write: builds the entry in a temporary directory,
      * then renames into place to avoid partial reads by concurrent processes.
+     *
+     * `outputs` accepts the richer `OutputSpec[]` shape — glob
+     * patterns, negative globs, and `{ auto: true }` entries. Pass
+     * `autoWrites` alongside `{ auto: true }` so the resolver knows
+     * which files the task actually wrote; otherwise auto entries
+     * contribute nothing.
      */
-    put(hash: string, terminalOutput: string, outputs: string[], code: number, fingerprint?: TaskFingerprint): Promise<void>;
+    put(hash: string, terminalOutput: string, outputs: OutputSpec[], code: number, fingerprint?: TaskFingerprint, autoWrites?: ReadonlyArray<string>): Promise<void>;
     /**
-     * Restores cached outputs to their original locations.
+     * Restores cached outputs from the compressed `outputs.tar.br`
+     * archive. Returns `true` either when the archive was extracted
+     * successfully OR when the entry simply has no outputs to restore.
+     *
+     * The restore flow stages into a temp directory, then swaps each
+     * top-level entry into place (see {@link restoreOutputsCompressed})
+     * so a mid-restore failure never destroys the user's working tree.
+     * The `outputs` parameter is no longer consulted at restore time —
+     * the archive is authoritative, and top-level entries in the
+     * extracted staging become the set of swap roots. Still accepted
+     * for backward compat.
      */
-    restoreOutputs(hash: string, outputs: string[]): Promise<boolean>;
+    restoreOutputs(hash: string, _outputs?: OutputSpec[]): 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

package/dist/chrome-trace.d.ts

@@ -0,0 +1,53 @@
+import type { RunSummary } from "./run-summary.d.ts";
+/**
+ * A single event in the Chrome Tracing JSON format. Chrome's
+ * chrome://tracing viewer and Perfetto both accept an array of these.
+ *
+ * Fields track the subset we actually emit:
+ * - `ph: "X"` — "complete" span (has duration)
+ * - `ph: "s"` / `ph: "f"` — flow start / finish (connects two spans)
+ *
+ * See the Chrome Trace Event Format spec on docs.google.com
+ * (document id: 1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU)
+ * for the full specification.
+ */
+export interface ChromeTraceEvent {
+    args?: Record<string, unknown>;
+    /** Event category — grouped in the viewer's search/filter UI. */
+    cat: string;
+    /** Duration in microseconds — only set for `ph: "X"` events. */
+    dur?: number;
+    /** Flow ID — used to draw an arrow from flow-start to flow-finish. */
+    id?: number;
+    /** Human label shown on the timeline. */
+    name: string;
+    /**
+     * Event phase:
+     * - `"X"` — complete (span with duration)
+     * - `"s"` — flow start
+     * - `"f"` — flow finish
+     * - `"M"` — metadata
+     */
+    ph: "f" | "M" | "s" | "X";
+    pid: number;
+    tid: number;
+    /** Timestamp in microseconds. */
+    ts: number;
+}
+/**
+ * Converts a {@link RunSummary} into a Chrome Tracing event list that
+ * renders as a gantt chart in chrome://tracing or Perfetto.
+ *
+ * Each task becomes a `"X"` span; dependency edges become flow arrows
+ * from the dependency's finish to the dependent task's start.
+ * Parallel tasks are assigned synthetic `tid` values (lane 0, 1, 2, …)
+ * based on the smallest free lane at the task's start time, so the
+ * timeline clearly shows concurrency without requiring real thread IDs.
+ */
+export declare const toChromeTrace: (summary: RunSummary) => ChromeTraceEvent[];
+/**
+ * Writes a Chrome Tracing JSON file at `outputPath`. Consumers (e.g.
+ * a CLI `--profile out.json` flag) call this after the run completes
+ * with a RunSummary produced by the task orchestrator.
+ */
+export declare const writeChromeTrace: (summary: RunSummary, outputPath: string) => Promise<void>;

package/dist/file-access-tracker.d.ts

@@ -1,11 +1,17 @@
 /**
  * Represents a file access recorded during task execution.
+ *
+ * Write-intent accesses (`"write"`) are emitted when a task opens a file
+ * with `O_WRONLY`/`O_RDWR`/`O_CREAT`/`O_TRUNC` flags (strace) or calls
+ * `writeFile`/`appendFile`/`unlink`/`rename` (preload script).
+ * The orchestrator uses the overlap of reads and writes to the same
+ * workspace path to detect self-modifying tasks and skip caching.
  */
 export interface FileAccess {
     /** The absolute path of the file */
     path: string;
     /** The type of access */
-    type: "read" | "stat" | "readdir" | "missing";
+    type: "missing" | "read" | "readdir" | "stat" | "write";
 }
 /**
  * Result of tracking file accesses during a command execution.

package/dist/fingerprint.d.ts

@@ -13,6 +13,15 @@ export interface TaskFingerprint {
     fileHashes: Record<string, string>;
     /** Paths of files that were probed but didn't exist (ENOENT) */
     missingFiles: string[];
+    /**
+     * Workspace-relative paths that were both read **and** written
+     * during execution. Populated when the tracker emits
+     * {@link FileAccess} entries with `"write"` type. The orchestrator
+     * uses a non-empty value here to skip caching a self-modifying
+     * task, whose fingerprint would otherwise capture post-write state
+     * and trigger false cache hits.
+     */
+    modifiedInputs?: string[];
 }
 /**
  * Describes why a cache miss occurred.

package/dist/incremental-hasher.d.ts

@@ -53,6 +53,24 @@ declare class IncrementalFileHasher {
      * 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/index.d.ts

@@ -2,6 +2,8 @@ export type { AffectedOptions, AffectedResult } from "./affected.d.ts";
 export { buildForwardDependencyMap, buildReverseDependencyMap, expandAffected, filterAffectedTasks, getAffectedProjects, getChangedFiles } from "./affected.d.ts";
 export type { CachedResult, CacheOptions } from "./cache.d.ts";
 export { Cache, DEFAULT_CACHE_DIRECTORY_NAME, formatCacheSize, parseCacheSize } from "./cache.d.ts";
+export type { ChromeTraceEvent } from "./chrome-trace.d.ts";
+export { toChromeTrace, writeChromeTrace } from "./chrome-trace.d.ts";
 export type { ParseCommandsOptions } from "./command-parser/index.d.ts";
 export { expandArguments, expandShortcut, expandWildcard, parseCommands, stripQuotes } from "./command-parser/index.d.ts";
 export { runConcurrently } from "./concurrent.d.ts";
@@ -23,12 +25,15 @@ export { IncrementalFileHasher } from "./incremental-hasher.d.ts";
 export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle } from "./life-cycle.d.ts";
 export type { PackageLockfileHash, ResolvedDependency } from "./lockfile-hasher.d.ts";
 export { extractPackageName, LockfileHasher, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile } from "./lockfile-hasher.d.ts";
+export type { LogMode } from "./log-reporter.d.ts";
+export { createLogReporter, LogReporter } from "./log-reporter.d.ts";
 export { isNativeAvailable, loadNativeBindings } from "./native-binding.d.ts";
+export { resolveOutputs } from "./output-resolver.d.ts";
 export { enforceProjectConstraints } from "./project-constraints.d.ts";
-export type { RemoteCacheOptions } from "./remote-cache.d.ts";
+export type { RemoteCacheCompression, RemoteCacheOptions, RemoteCacheSigning } from "./remote-cache.d.ts";
 export { RemoteCache } from "./remote-cache.d.ts";
 export type { RunSummary, TaskSummary } from "./run-summary.d.ts";
-export { generateRunSummary, writeRunSummary } from "./run-summary.d.ts";
+export { generateRunSummary, getLastRunSummaryPath, readLastRunSummary, writeLastRunSummary, writeRunSummary } from "./run-summary.d.ts";
 export { createTaskGraph, getTaskId, parseTaskId } from "./task-graph.d.ts";
 export { findCycle, findCycles, getDependentTasks, getLeafTasks, getTransitiveDependencies, makeAcyclic, reverseTaskGraph, walkTaskGraph, } from "./task-graph-utils.d.ts";
 export type { TaskHasher, TaskHasherOptions } from "./task-hasher.d.ts";
@@ -40,5 +45,5 @@ export { parsePartition, TaskScheduler } from "./task-scheduler.d.ts";
 export { TerminalBuffer } from "./terminal-buffer.d.ts";
 export type { TrackedExecutionResult } from "./tracked-executor.d.ts";
 export { TrackedTaskExecutor } from "./tracked-executor.d.ts";
-export type { AffectedScope, ConcurrentCloseEvent, ConcurrentCommandConfig, ConcurrentCommandInput, ConcurrentRunnerOptions, ConcurrentRunResult, ConstraintsConfig, ConstraintViolation, DependencyKindRules, DependencyType, EnvironmentInput, ExternalDependencyInput, FileSetInput, InputDefinition, LifeCycleInterface, NamedInputs, ProcessEvent, ProjectConfiguration, ProjectGraph, ProjectGraphDependency, ProjectGraphProjectNode, RuntimeInput, TagRelationships, TargetConfiguration, TargetDependencyConfig, Task, TaskExecutionOptions, TaskExecutor, TaskGraph, TaskHashDetails, TaskResult, TaskResults, TaskRunnerContext, TaskRunnerOptions, TasksRunner, TaskStatus, TaskTarget, TypeBoundaries, WorkspaceConfiguration, } from "./types.d.ts";
+export type { AffectedScope, ConcurrentCloseEvent, ConcurrentCommandConfig, ConcurrentCommandInput, ConcurrentRunnerOptions, ConcurrentRunResult, ConstraintsConfig, ConstraintViolation, DependencyKindRules, DependencyType, EnvironmentInput, ExternalDependencyInput, FileSetBase, FileSetInput, FileSetPattern, InputDefinition, LifeCycleInterface, NamedInputs, OutputSpec, ProcessEvent, ProjectConfiguration, ProjectGraph, ProjectGraphDependency, ProjectGraphProjectNode, RuntimeInput, TagRelationships, TargetConfiguration, TargetDependencyConfig, Task, TaskExecutionOptions, TaskExecutor, TaskGraph, TaskHashDetails, TaskPriority, TaskResult, TaskResults, TaskRunnerContext, TaskRunnerOptions, TasksRunner, TaskStatus, TaskTarget, TypeBoundaries, WorkspaceConfiguration, } from "./types.d.ts";
 export { collectFiles, createFailureResult, hashFile, hashStrings, readPackageDeps, resolveTaskCwd, sortObjectKeys, uniqueId } from "./utils.d.ts";

package/dist/index.js

@@ -1,28 +1,31 @@
-export { buildForwardDependencyMap, buildReverseDependencyMap, expandAffected, filterAffectedTasks, getAffectedProjects, getChangedFiles } from './packem_shared/buildForwardDependencyMap-0BJFMMPv.js';
-export { Cache, DEFAULT_CACHE_DIRECTORY_NAME, formatCacheSize, parseCacheSize } from './packem_shared/Cache-iAjRMV2d.js';
+export { buildForwardDependencyMap, buildReverseDependencyMap, expandAffected, filterAffectedTasks, getAffectedProjects, getChangedFiles } from './packem_shared/buildForwardDependencyMap-DLPgKEto.js';
+export { Cache, DEFAULT_CACHE_DIRECTORY_NAME, formatCacheSize, parseCacheSize } from './packem_shared/Cache-CWaX_c8U.js';
+export { toChromeTrace, writeChromeTrace } from './packem_shared/toChromeTrace-B2tZoJ-7.js';
 export { parseCommands } from './packem_shared/parseCommands-D-IgF8Zh.js';
-export { runConcurrently } from './packem_shared/runConcurrently-qrkWyzXW.js';
-export { runConcurrentFallback } from './packem_shared/runConcurrentFallback-CGHz_f-Q.js';
-export { defaultTaskRunner } from './packem_shared/defaultTaskRunner-BdFTifsh.js';
+export { runConcurrently } from './packem_shared/runConcurrently-CmfC4r-f.js';
+export { runConcurrentFallback } from './packem_shared/runConcurrentFallback-BTmgGV1H.js';
+export { defaultTaskRunner } from './packem_shared/defaultTaskRunner-Cp7jCmIl.js';
 export { detectScriptShell } from './packem_shared/detectScriptShell-CR-xXKA4.js';
-export { FileAccessTracker, generatePreloadScript } from './packem_shared/FileAccessTracker-CrtBAt5D.js';
-export { FingerprintManager } from './packem_shared/FingerprintManager-Cu-ta9ee.js';
+export { FileAccessTracker, generatePreloadScript } from './packem_shared/FileAccessTracker-CQ5Ot7Hd.js';
+export { FingerprintManager } from './packem_shared/FingerprintManager-CV7U4f4f.js';
 export { detectFrameworks, getFrameworkEnvVariables, inferFrameworkEnvPatterns } from './packem_shared/detectFrameworks-CeFzKE6J.js';
-export { projectGraphToDot, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot } from './packem_shared/projectGraphToDot-C8uYeaPo.js';
-export { IncrementalFileHasher } from './packem_shared/IncrementalFileHasher-Cm_kJY5V.js';
-export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle } from './packem_shared/CompositeLifeCycle-7AtYw1dv.js';
-export { LockfileHasher, extractPackageName, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile } from './packem_shared/extractPackageName-CbVNW-dr.js';
+export { projectGraphToDot, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot } from './packem_shared/projectGraphToDot-DU1lSe-c.js';
+export { IncrementalFileHasher } from './packem_shared/IncrementalFileHasher-BRS76-mb.js';
+export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle } from './packem_shared/CompositeLifeCycle-CSVbRC_5.js';
+export { LockfileHasher, extractPackageName, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile } from './packem_shared/extractPackageName-BllKetnz.js';
+export { LogReporter, createLogReporter } from './packem_shared/LogReporter-BDt52HLu.js';
 export { isNativeAvailable, loadNativeBindings } from './packem_shared/isNativeAvailable-BpD28A6Z.js';
+export { resolveOutputs } from './packem_shared/resolveOutputs-n6MCKoTe.js';
 export { enforceProjectConstraints } from './packem_shared/enforceProjectConstraints-C5Jp_C3u.js';
-export { RemoteCache } from './packem_shared/RemoteCache-BFceSe4a.js';
-export { generateRunSummary, writeRunSummary } from './packem_shared/generateRunSummary-qn-_jKwt.js';
-export { createTaskGraph, getTaskId, parseTaskId } from './packem_shared/createTaskGraph-CcsFaSrz.js';
+export { RemoteCache } from './packem_shared/RemoteCache-DSU3lc87.js';
+export { generateRunSummary, getLastRunSummaryPath, readLastRunSummary, writeLastRunSummary, writeRunSummary } from './packem_shared/generateRunSummary-BE1jnQ3H.js';
+export { createTaskGraph, getTaskId, parseTaskId } from './packem_shared/createTaskGraph-B7nH0kY_.js';
 export { findCycle, findCycles, getDependentTasks, getLeafTasks, getTransitiveDependencies, makeAcyclic, reverseTaskGraph, walkTaskGraph } from './packem_shared/findCycle-DefgNYhg.js';
-export { InProcessTaskHasher, computeTaskHash } from './packem_shared/computeTaskHash-B2SVZqgp.js';
-export { TaskOrchestrator } from './packem_shared/TaskOrchestrator-lLn-PH1m.js';
-export { TaskScheduler, parsePartition } from './packem_shared/parsePartition-C4-P5RjK.js';
-export { TerminalBuffer } from './packem_shared/TerminalBuffer-CnPyFgPB.js';
-export { TrackedTaskExecutor } from './packem_shared/TrackedTaskExecutor-BGUKFE-7.js';
+export { InProcessTaskHasher, computeTaskHash } from './packem_shared/computeTaskHash-DYqfrDGq.js';
+export { TaskOrchestrator } from './packem_shared/TaskOrchestrator-rf45vW5c.js';
+export { TaskScheduler, parsePartition } from './packem_shared/parsePartition-BfLbHGAx.js';
+export { TerminalBuffer } from './packem_shared/TerminalBuffer-qVJvbRQZ.js';
+export { TrackedTaskExecutor } from './packem_shared/TrackedTaskExecutor-CFPpQfXF.js';
 export { c as collectFiles, a as createFailureResult, h as hashFile, b as hashStrings, r as readPackageDeps, d as resolveTaskCwd, s as sortObjectKeys, u as uniqueId } from './packem_shared/utils-zO0ZRgtf.js';
 export { createInputHandler } from './packem_shared/createInputHandler-DTfePcTG.js';
 export { expandArguments } from './packem_shared/expandArguments-0AwD2BIA.js';

package/dist/life-cycle.d.ts

@@ -13,6 +13,8 @@ declare class CompositeLifeCycle implements LifeCycleInterface {
     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.

package/dist/log-reporter.d.ts

@@ -0,0 +1,34 @@
+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/output-resolver.d.ts

@@ -0,0 +1,20 @@
+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/packem_shared/{Cache-iAjRMV2d.js → Cache-CWaX_c8U.js}

@@ -22,17 +22,30 @@ const {
   mkdir,
   writeFile,
   rename,
-  stat,
   rm,
-  cp,
-  readdir
+  readdir,
+  stat,
+  cp
 } = __cjs_getBuiltinModule("node:fs/promises");
 import { formatBytes, parseBytes } from '@visulima/humanizer';
 import { join, resolve, dirname } from '@visulima/path';
+import { e as extractTarBrotli, c as createTarBrotli } from './archive-UQHAnZUa.js';
+import { resolveOutputs } from './resolveOutputs-n6MCKoTe.js';
 import { u as uniqueId } from './utils-zO0ZRgtf.js';
 
 const DEFAULT_MAX_CACHE_AGE = 7 * 24 * 60 * 60 * 1e3;
 const DEFAULT_CACHE_DIRECTORY_NAME = ".task-runner-cache";
+const assertSafeNamespace = (namespace) => {
+  if (namespace.includes("\0")) {
+    throw new Error("cacheNamespace: null bytes are not allowed.");
+  }
+  if (namespace.includes("/") || namespace.includes("\\")) {
+    throw new Error(`cacheNamespace: path separators are not allowed (received ${JSON.stringify(namespace)}).`);
+  }
+  if (namespace === "." || namespace === "..") {
+    throw new Error(`cacheNamespace: "${namespace}" would escape the cache subtree.`);
+  }
+};
 const removeEntry = async (entryPath) => {
   try {
     await rm(entryPath, { force: true, recursive: true });
@@ -73,7 +86,11 @@ class Cache {
   #indexWriteQueue = Promise.resolve();
   constructor(options) {
     this.#workspaceRoot = options.workspaceRoot;
-    this.#cacheDirectory = options.cacheDirectory ?? join(options.workspaceRoot, DEFAULT_CACHE_DIRECTORY_NAME);
+    const baseDirectory = options.cacheDirectory ?? join(options.workspaceRoot, DEFAULT_CACHE_DIRECTORY_NAME);
+    if (options.cacheNamespace !== void 0 && options.cacheNamespace.length > 0) {
+      assertSafeNamespace(options.cacheNamespace);
+    }
+    this.#cacheDirectory = options.cacheNamespace && options.cacheNamespace.length > 0 ? join(baseDirectory, "ns", options.cacheNamespace) : baseDirectory;
     this.#maxCacheAge = options.maxCacheAge ?? DEFAULT_MAX_CACHE_AGE;
     this.#maxCacheSize = options.maxCacheSize ? parseCacheSize(options.maxCacheSize) : void 0;
   }
@@ -117,8 +134,14 @@ class Cache {
    *
    * Uses atomic write: builds the entry in a temporary directory,
    * then renames into place to avoid partial reads by concurrent processes.
+   *
+   * `outputs` accepts the richer `OutputSpec[]` shape — glob
+   * patterns, negative globs, and `{ auto: true }` entries. Pass
+   * `autoWrites` alongside `{ auto: true }` so the resolver knows
+   * which files the task actually wrote; otherwise auto entries
+   * contribute nothing.
    */
-  async put(hash, terminalOutput, outputs, code, fingerprint) {
+  async put(hash, terminalOutput, outputs, code, fingerprint, autoWrites) {
     const cacheEntryDirectory = join(this.#cacheDirectory, hash);
     const temporaryDirectory = join(this.#cacheDirectory, `.tmp-${hash}-${uniqueId()}`);
     try {
@@ -126,7 +149,7 @@ class Cache {
       const writes = [
         writeFile(join(temporaryDirectory, "code"), String(code)),
         writeFile(join(temporaryDirectory, "terminalOutput"), terminalOutput),
-        this.#archiveOutputs(temporaryDirectory, outputs)
+        this.#archiveOutputs(temporaryDirectory, outputs, autoWrites)
       ];
       if (fingerprint) {
         writes.push(writeFile(join(temporaryDirectory, "fingerprint.json"), JSON.stringify(fingerprint)));
@@ -140,36 +163,21 @@ class Cache {
     }
   }
   /**
-   * Restores cached outputs to their original locations.
+   * Restores cached outputs from the compressed `outputs.tar.br`
+   * archive. Returns `true` either when the archive was extracted
+   * successfully OR when the entry simply has no outputs to restore.
+   *
+   * The restore flow stages into a temp directory, then swaps each
+   * top-level entry into place (see {@link restoreOutputsCompressed})
+   * so a mid-restore failure never destroys the user's working tree.
+   * The `outputs` parameter is no longer consulted at restore time —
+   * the archive is authoritative, and top-level entries in the
+   * extracted staging become the set of swap roots. Still accepted
+   * for backward compat.
    */
-  async restoreOutputs(hash, outputs) {
+  async restoreOutputs(hash, _outputs) {
     const cacheEntryDirectory = join(this.#cacheDirectory, hash);
-    const outputsDirectory = join(cacheEntryDirectory, "outputs");
-    try {
-      await stat(outputsDirectory);
-    } catch {
-      return true;
-    }
-    try {
-      await Promise.all(
-        outputs.map(async (output) => {
-          const absoluteOutput = resolve(this.#workspaceRoot, output);
-          const cachedOutput = join(outputsDirectory, output);
-          try {
-            await stat(cachedOutput);
-          } catch {
-            return;
-          }
-          const parentDirectory = dirname(absoluteOutput);
-          await mkdir(parentDirectory, { recursive: true });
-          await rm(absoluteOutput, { force: true, recursive: true });
-          await cp(cachedOutput, absoluteOutput, { recursive: true });
-        })
-      );
-      return true;
-    } catch {
-      return false;
-    }
+    return restoreOutputsCompressed(cacheEntryDirectory, this.#workspaceRoot);
   }
   /**
    * Retrieves the most recent cached result for a task by its ID.
@@ -276,23 +284,105 @@ class Cache {
     }
   }
   /**
-   * Archives task output files into the cache.
+   * Archives task output files into the cache as a single
+   * brotli-compressed tarball (`outputs.tar.br`). See
+   * {@link archiveOutputsCompressed} for the staging + compression
+   * flow.
    */
-  async #archiveOutputs(cacheEntryDirectory, outputs) {
-    const outputsDirectory = join(cacheEntryDirectory, "outputs");
-    await mkdir(outputsDirectory, { recursive: true });
-    for (const output of outputs) {
-      const absoluteOutput = resolve(this.#workspaceRoot, output);
-      const cachedOutput = join(outputsDirectory, output);
+  async #archiveOutputs(cacheEntryDirectory, outputs, autoWrites) {
+    await archiveOutputsCompressed(this.#workspaceRoot, cacheEntryDirectory, outputs, autoWrites);
+  }
+}
+const OUTPUTS_ARCHIVE_FILENAME = "outputs.tar.br";
+const archiveOutputsCompressed = async (workspaceRoot, cacheEntryDirectory, outputs, autoWrites) => {
+  if (outputs.length === 0) {
+    return;
+  }
+  const resolvedPaths = await resolveOutputs(workspaceRoot, outputs, autoWrites);
+  if (resolvedPaths.length === 0) {
+    return;
+  }
+  const stagingDirectory = join(cacheEntryDirectory, `.outputs-stage-${uniqueId()}`);
+  const finalPath = join(cacheEntryDirectory, OUTPUTS_ARCHIVE_FILENAME);
+  try {
+    await mkdir(stagingDirectory, { recursive: true });
+    const stagedFlags = await runBounded(STAGE_CONCURRENCY, resolvedPaths, async (relativePath) => {
+      const absoluteOutput = resolve(workspaceRoot, relativePath);
+      const stagedOutput = join(stagingDirectory, relativePath);
+      try {
+        await mkdir(dirname(stagedOutput), { recursive: true });
+        await cp(absoluteOutput, stagedOutput, { recursive: true });
+        return true;
+      } catch {
+        return false;
+      }
+    });
+    const stagedCount = stagedFlags.filter(Boolean).length;
+    if (stagedCount === 0) {
+      return;
+    }
+    await createTarBrotli(stagingDirectory, finalPath);
+  } finally {
+    await rm(stagingDirectory, { force: true, recursive: true }).catch(() => {
+    });
+  }
+};
+const STAGE_CONCURRENCY = 16;
+const runBounded = async (limit, items, fn) => {
+  const results = Array.from({ length: items.length });
+  let cursor = 0;
+  const worker = async () => {
+    while (cursor < items.length) {
+      const index = cursor;
+      cursor += 1;
+      results[index] = await fn(items[index], index);
+    }
+  };
+  const workers = Array.from({ length: Math.min(limit, items.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+};
+const restoreOutputsCompressed = async (cacheEntryDirectory, workspaceRoot) => {
+  const archivePath = join(cacheEntryDirectory, OUTPUTS_ARCHIVE_FILENAME);
+  try {
+    await stat(archivePath);
+  } catch {
+    return true;
+  }
+  const stagingDirectory = join(cacheEntryDirectory, `.restore-${uniqueId()}`);
+  const backups = [];
+  try {
+    await mkdir(stagingDirectory, { recursive: true });
+    await extractTarBrotli(archivePath, stagingDirectory);
+    const topLevel = await readdir(stagingDirectory);
+    await runBounded(STAGE_CONCURRENCY, topLevel, async (entry) => {
+      const absoluteOutput = resolve(workspaceRoot, entry);
+      const stagedOutput = join(stagingDirectory, entry);
+      await mkdir(dirname(absoluteOutput), { recursive: true });
       try {
         await stat(absoluteOutput);
-        const cachedOutputParent = join(cachedOutput, "..");
-        await mkdir(cachedOutputParent, { recursive: true });
-        await cp(absoluteOutput, cachedOutput, { recursive: true });
+        const backup = `${absoluteOutput}.pre-restore-${uniqueId()}`;
+        await rename(absoluteOutput, backup);
+        backups.push({ backup, original: absoluteOutput });
       } catch {
       }
+      await cp(stagedOutput, absoluteOutput, { recursive: true });
+    });
+    await Promise.all(backups.map(({ backup }) => rm(backup, { force: true, recursive: true }).catch(() => {
+    })));
+    return true;
+  } catch {
+    for (const { backup, original } of backups) {
+      await rm(original, { force: true, recursive: true }).catch(() => {
+      });
+      await rename(backup, original).catch(() => {
+      });
     }
+    return false;
+  } finally {
+    await rm(stagingDirectory, { force: true, recursive: true }).catch(() => {
+    });
   }
-}
+};
 
 export { Cache, DEFAULT_CACHE_DIRECTORY_NAME, formatCacheSize, parseCacheSize };