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

package/dist/types.d.ts

@@ -0,0 +1,385 @@
+/**
+ * Represents a target that a task executes against.
+ */
+export interface TaskTarget {
+    /** Optional configuration name */
+    configuration?: string;
+    /** The project name */
+    project: string;
+    /** The target name (e.g., "build", "test", "lint") */
+    target: string;
+}
+/**
+ * Represents a single task to be executed.
+ */
+export interface Task {
+    /** Whether this task is eligible for caching */
+    cache?: boolean;
+    /** Hash of the task inputs for caching */
+    hash?: string;
+    /** Detailed hash information */
+    hashDetails?: TaskHashDetails;
+    /** Unique identifier for the task, typically "project:target:configuration" */
+    id: string;
+    /** Output file paths produced by this task */
+    outputs: string[];
+    /** Overrides/extra options passed to the task */
+    overrides: Record<string, unknown>;
+    /** Whether this task supports parallel execution */
+    parallelism?: boolean;
+    /** The project root directory */
+    projectRoot?: string;
+    /** The target this task executes */
+    target: TaskTarget;
+}
+/**
+ * Represents detailed hash information for a task.
+ */
+export interface TaskHashDetails {
+    /** The command hash */
+    command: string;
+    /** Hash of implicit dependencies */
+    implicitDeps?: Record<string, string>;
+    /** Hashes of input files */
+    nodes: Record<string, string>;
+    /** Hash of runtime values */
+    runtime?: Record<string, string>;
+}
+/**
+ * Represents a directed acyclic graph of tasks.
+ */
+export interface TaskGraph {
+    /** Dependencies for each task */
+    dependencies: Record<string, string[]>;
+    /** Top-level tasks that no other task depends on (the final outputs to run) */
+    roots: string[];
+    /** All tasks in the graph, keyed by task ID */
+    tasks: Record<string, Task>;
+}
+/**
+ * Possible states of a task after execution.
+ */
+export type TaskStatus = "success" | "failure" | "skipped" | "local-cache" | "local-cache-kept-existing" | "remote-cache";
+/**
+ * Result of executing a task.
+ */
+export interface TaskResult {
+    /** The exit code, if applicable */
+    code?: number;
+    /** The end time of the task */
+    endTime?: number;
+    /** The start time of the task */
+    startTime?: number;
+    status: TaskStatus;
+    task: Task;
+    /** The terminal output produced during execution */
+    terminalOutput?: string;
+}
+/**
+ * Map of task results, keyed by task ID.
+ */
+export type TaskResults = Map<string, TaskResult>;
+/**
+ * Configuration for a project in the workspace.
+ */
+export interface ProjectConfiguration {
+    /** Implicit dependencies on other projects */
+    implicitDependencies?: string[];
+    /** The project type */
+    projectType?: "library" | "application";
+    /** The root directory of the project, relative to workspace root */
+    root: string;
+    /** The source root directory */
+    sourceRoot?: string;
+    /** Tags for filtering */
+    tags?: string[];
+    /** Named targets and their configurations */
+    targets?: Record<string, TargetConfiguration>;
+}
+/**
+ * Configuration for a target within a project.
+ */
+export interface TargetConfiguration {
+    /** Whether this target is cacheable */
+    cache?: boolean;
+    /** The command to run (alternative to executor) */
+    command?: string;
+    /** Named configurations (e.g., "production", "development") */
+    configurations?: Record<string, Record<string, unknown>>;
+    /** Other targets this target depends on */
+    dependsOn?: (string | TargetDependencyConfig)[];
+    /** The executor/command to run */
+    executor?: string;
+    /** Input patterns for cache invalidation */
+    inputs?: (string | InputDefinition)[];
+    /** Options passed to the executor */
+    options?: Record<string, unknown>;
+    /** Output patterns produced by this target */
+    outputs?: string[];
+    /** Whether this target supports parallel execution */
+    parallelism?: boolean;
+}
+/**
+ * Defines a dependency on another target.
+ */
+export interface TargetDependencyConfig {
+    /** Whether this is a dependency on the same project */
+    dependencies?: boolean;
+    /** Params to pass through */
+    params?: "forward" | "ignore";
+    /** The project name (if different from the current project) */
+    projects?: string | string[];
+    /** The target name */
+    target: string;
+}
+/**
+ * Defines an input for cache invalidation.
+ */
+export type InputDefinition = FileSetInput | RuntimeInput | EnvironmentInput | ExternalDependencyInput;
+/**
+ * An input based on file patterns.
+ */
+export interface FileSetInput {
+    fileset: string;
+}
+/**
+ * An input based on a runtime command.
+ */
+export interface RuntimeInput {
+    runtime: string;
+}
+/**
+ * An input based on environment variables.
+ */
+export interface EnvironmentInput {
+    env: string;
+}
+/**
+ * An input based on external dependency versions.
+ */
+export interface ExternalDependencyInput {
+    externalDependencies: string[];
+}
+/**
+ * Workspace configuration containing all project configurations.
+ */
+export interface WorkspaceConfiguration {
+    /** All projects in the workspace, keyed by project name */
+    projects: Record<string, ProjectConfiguration>;
+}
+/**
+ * A dependency relationship in the project graph.
+ */
+export interface ProjectGraphDependency {
+    /** The source project */
+    source: string;
+    /** The target project */
+    target: string;
+    /** The type of dependency */
+    type: "static" | "dynamic" | "implicit";
+}
+/**
+ * A node in the project graph.
+ */
+export interface ProjectGraphProjectNode {
+    /** The project configuration */
+    data: ProjectConfiguration;
+    /** The project name */
+    name: string;
+    /** The type of project */
+    type: "library" | "application";
+}
+/**
+ * The project graph represents the dependency relationships between projects.
+ */
+export interface ProjectGraph {
+    /** All dependency relationships */
+    dependencies: Record<string, ProjectGraphDependency[]>;
+    /** All project nodes, keyed by project name */
+    nodes: Record<string, ProjectGraphProjectNode>;
+}
+/**
+ * Named input definitions that can be referenced by name.
+ */
+export interface NamedInputs {
+    [name: string]: (string | InputDefinition)[];
+}
+/**
+ * Configuration for the task runner.
+ */
+export interface TaskRunnerOptions {
+    /**
+     * Enable auto-fingerprinting mode (Vite Task-style).
+     * When enabled, the task runner automatically tracks which files
+     * a task accesses during execution and uses that for cache invalidation
+     * instead of requiring manual input configuration.
+     *
+     * Falls back to explicit inputs (Nx-style) when file tracking
+     * is not supported on the current platform.
+     * @default false
+     */
+    autoFingerprint?: boolean;
+    /**
+     * Whether to show cache miss diagnostics (why a cache miss occurred).
+     * @default false
+     */
+    cacheDiagnostics?: boolean;
+    /** Directory for storing cache */
+    cacheDirectory?: string;
+    /**
+     * Dry-run mode: compute hashes and check cache but don't execute tasks.
+     * Useful for debugging cache hits/misses.
+     * @default false
+     */
+    dryRun?: boolean;
+    /** Custom environment variables to include in hash */
+    envVars?: string[];
+    /**
+     * Environment variable patterns to include in auto-fingerprint.
+     * Supports wildcard patterns like "VITE_*".
+     * Only used when autoFingerprint is enabled.
+     */
+    fingerprintEnvPatterns?: string[];
+    /**
+     * Enable framework environment variable inference.
+     * When true, automatically detects common frontend frameworks and includes
+     * their public env var prefixes in the task hash:
+     * - Next.js: NEXT_PUBLIC_*
+     * - Vite: VITE_*
+     * - Create React App: REACT_APP_*
+     * - Gatsby: GATSBY_*
+     * - Nuxt: NUXT_PUBLIC_*
+     * - Expo: EXPO_PUBLIC_*
+     *
+     * Matches Turborepo's framework inference behavior.
+     * @default false
+     */
+    frameworkInference?: boolean;
+    /**
+     * Global environment variables that invalidate ALL task hashes.
+     * Matches Turborepo's `globalEnv`.
+     */
+    globalEnv?: string[];
+    /**
+     * Global input files that invalidate ALL task hashes when changed.
+     * These are workspace-root-relative paths.
+     *
+     * Default: ["package-lock.json", "pnpm-lock.yaml", "yarn.lock",
+     * "tsconfig.base.json", ".env"]
+     *
+     * When any global input changes, every task's hash changes,
+     * forcing a full rebuild. This matches Turborepo's `globalDependencies`.
+     */
+    globalInputs?: string[];
+    /** Maximum age of cache entries in milliseconds */
+    maxCacheAge?: number;
+    /** Maximum cache size (e.g., "1GB") */
+    maxCacheSize?: string;
+    /** Named inputs for cache invalidation */
+    namedInputs?: NamedInputs;
+    /** Maximum number of parallel tasks */
+    parallel?: number | boolean;
+    /**
+     * Remote cache configuration.
+     * When configured, the task runner will check the remote cache
+     * after a local cache miss, and upload results after execution.
+     */
+    remoteCache?: {
+        /**
+         * 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;
+        /** Enable remote reads (default: true) */
+        read?: boolean;
+        /** Team/namespace for cache isolation */
+        teamId?: string;
+        /** Authentication token */
+        token?: string;
+        /** Remote cache server URL */
+        url: string;
+        /** Enable remote writes (default: true) */
+        write?: boolean;
+    };
+    /** Whether to skip cache reads */
+    skipNxCache?: boolean;
+    /**
+     * Enable smart lockfile hashing.
+     * Instead of hashing the entire lockfile (which busts ALL caches),
+     * only hash the resolved versions of each package's actual dependencies.
+     * This matches Turborepo's smart lockfile hashing behavior.
+     * @default false
+     */
+    smartLockfileHashing?: boolean;
+    /**
+     * Generate a detailed JSON run summary after execution.
+     * When true, writes a summary file to `.task-runner/runs/` containing
+     * all task inputs, outputs, hashes, timings, and cache status.
+     *
+     * Useful for debugging cache misses and comparing runs.
+     * Matches Turborepo's `--summarize` flag.
+     * @default false
+     */
+    summarize?: boolean;
+    /** Target-specific default configurations */
+    targetDefaults?: Record<string, Partial<TargetConfiguration>>;
+    /**
+     * Environment variables that should be passed to tasks but NOT
+     * included in the cache fingerprint. Useful for CI-specific vars.
+     * Only used when autoFingerprint is enabled.
+     */
+    untrackedEnvVars?: string[];
+}
+/**
+ * Options for executing a task.
+ */
+export interface TaskExecutionOptions {
+    /** Whether to capture output */
+    captureOutput?: boolean;
+    /** The working directory */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Stream output as it arrives */
+    streamOutput?: boolean;
+}
+/**
+ * A task executor function.
+ */
+export type TaskExecutor = (task: Task, options: TaskExecutionOptions) => Promise<{
+    code: number;
+    terminalOutput: string;
+}>;
+/**
+ * The function type for a task runner.
+ */
+export type TasksRunner = (tasks: Task[], options: TaskRunnerOptions, context: TaskRunnerContext) => Promise<TaskResults>;
+/**
+ * Context provided to the task runner.
+ */
+export interface TaskRunnerContext {
+    /** Lifecycle hooks */
+    lifeCycle: LifeCycleInterface;
+    /** The project graph */
+    projectGraph: ProjectGraph;
+    /** The task executor */
+    taskExecutor: TaskExecutor;
+    /** The task graph */
+    taskGraph: TaskGraph;
+    /** The workspace root directory */
+    workspaceRoot: string;
+}
+/**
+ * Interface for lifecycle event handlers.
+ */
+export interface LifeCycleInterface {
+    endCommand?: () => void;
+    endTasks?: (taskResults: TaskResult[]) => void;
+    /** Called when a cache miss occurs with diagnostic information */
+    printCacheMiss?: (task: Task, reasons: string) => void;
+    printTaskTerminalOutput?: (task: Task, status: TaskStatus, terminalOutput: string) => void;
+    scheduleTask?: (task: Task) => void;
+    startCommand?: () => void;
+    startTasks?: (tasks: Task[]) => void;
+}

package/dist/utils.d.ts

@@ -0,0 +1,39 @@
+import type { Task, TaskResult } from "./types.d.ts";
+/**
+ * Hashes a file's content using xxh3-128.
+ * Returns undefined if the file cannot be read.
+ */
+declare const hashFile: (filePath: string) => Promise<string | undefined>;
+/**
+ * Hashes one or more string values using xxh3-128.
+ */
+declare const hashStrings: (...values: string[]) => string;
+/**
+ * Sorts an object's keys for deterministic serialization.
+ */
+declare const sortObjectKeys: (object: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Recursively collects all file paths in a directory,
+ * skipping directories in the ignored set.
+ *
+ * Tracks visited real paths to prevent infinite loops from symlink cycles.
+ */
+declare const collectFiles: (directory: string, ignoredDirectories: Set<string>, visitedRealPaths?: Set<string>) => Promise<string[]>;
+/**
+ * Resolves the working directory for a task.
+ */
+declare const resolveTaskCwd: (workspaceRoot: string, task: Task) => string;
+/**
+ * Creates a failure TaskResult from an error.
+ */
+declare const createFailureResult: (task: Task, error: unknown, startTime: number) => TaskResult;
+declare const readPackageDeps: (packageJsonPath: string, options?: {
+    optional?: boolean;
+    peer?: boolean;
+}) => Promise<Set<string> | undefined>;
+/**
+ * Generates a unique ID for temporary files/directories.
+ * Not cryptographically secure — for cache entry naming only.
+ */
+declare const uniqueId: () => string;
+export { collectFiles, createFailureResult, hashFile, hashStrings, readPackageDeps, resolveTaskCwd, sortObjectKeys, uniqueId };

package/package.json

@@ -1,10 +1,75 @@
 {
   "name": "@visulima/task-runner",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @visulima/task-runner",
+  "version": "1.0.0-alpha.2",
+  "description": "A task runner with caching support for monorepo workspaces",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "visulima",
+    "task-runner",
+    "cache",
+    "monorepo",
+    "task",
+    "runner",
+    "workspace"
+  ],
+  "homepage": "https://visulima.com/packages/task-runner",
+  "bugs": {
+    "url": "https://github.com/visulima/visulima/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/visulima/visulima.git",
+    "directory": "packages/tooling/task-runner"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/prisis"
+    },
+    {
+      "type": "consulting",
+      "url": "https://anolilab.com/support"
+    }
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Daniel Bannert",
+    "email": "d.bannert@anolilab.de"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**",
+    "binding.js",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.md"
+  ],
+  "dependencies": {
+    "@visulima/humanizer": "3.0.0-alpha.7",
+    "@visulima/path": "3.0.0-alpha.6"
+  },
+  "optionalDependencies": {
+    "@visulima/task-runner-binding-darwin-arm64": "1.0.0-alpha.2",
+    "@visulima/task-runner-binding-linux-arm64-musl": "1.0.0-alpha.2",
+    "@visulima/task-runner-binding-linux-x64-gnu": "1.0.0-alpha.2",
+    "@visulima/task-runner-binding-linux-arm64-gnu": "1.0.0-alpha.2",
+    "@visulima/task-runner-binding-darwin-x64": "1.0.0-alpha.2",
+    "@visulima/task-runner-binding-linux-x64-musl": "1.0.0-alpha.2",
+    "@visulima/task-runner-binding-win32-x64-msvc": "1.0.0-alpha.2",
+    "@visulima/task-runner-binding-win32-arm64-msvc": "1.0.0-alpha.2"
+  },
+  "engines": {
+    "node": ">=20.19 <=25.x"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}