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

package/dist/index.js

@@ -1,10 +1,10 @@
-export { buildForwardDependencyMap, buildReverseDependencyMap, expandAffected, filterAffectedTasks, getAffectedProjects, getChangedFiles } from './packem_shared/buildForwardDependencyMap-DLPgKEto.js';
+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-CWaX_c8U.js';
 export { toChromeTrace, writeChromeTrace } from './packem_shared/toChromeTrace-B2tZoJ-7.js';
-export { parseCommands } from './packem_shared/parseCommands-D-IgF8Zh.js';
+export { parseCommands } from './packem_shared/parseCommands-CJ16ohOB.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 { defaultTaskRunner } from './packem_shared/defaultTaskRunner-DzR0ld8F.js';
 export { detectScriptShell } from './packem_shared/detectScriptShell-CR-xXKA4.js';
 export { FileAccessTracker, generatePreloadScript } from './packem_shared/FileAccessTracker-CQ5Ot7Hd.js';
 export { FingerprintManager } from './packem_shared/FingerprintManager-CV7U4f4f.js';
@@ -12,24 +12,26 @@ export { detectFrameworks, getFrameworkEnvVariables, inferFrameworkEnvPatterns }
 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 { LockfileHasher, extractPackageName, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile } from './packem_shared/extractPackageName-CbVNW-dr.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-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 { createTaskGraph, getTaskId, parseTaskId } from './packem_shared/createTaskGraph-B5YrfAMx.js';
 export { findCycle, findCycles, getDependentTasks, getLeafTasks, getTransitiveDependencies, makeAcyclic, reverseTaskGraph, walkTaskGraph } from './packem_shared/findCycle-DefgNYhg.js';
-export { InProcessTaskHasher, computeTaskHash } from './packem_shared/computeTaskHash-DYqfrDGq.js';
-export { TaskOrchestrator } from './packem_shared/TaskOrchestrator-rf45vW5c.js';
+export { InProcessTaskHasher, computeTaskHash } from './packem_shared/computeTaskHash-B5APHW7e.js';
+export { TaskOrchestrator } from './packem_shared/TaskOrchestrator-UCMHCx8c.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 { evaluateWhen, explainWhen, getCurrentBranch, resetBranchCache } from './packem_shared/getCurrentBranch-DsKPDoVj.js';
 export { createInputHandler } from './packem_shared/createInputHandler-DTfePcTG.js';
 export { expandArguments } from './packem_shared/expandArguments-0AwD2BIA.js';
 export { expandShortcut } from './packem_shared/expandShortcut-BVG05ee4.js';
+export { expandTokens, expandTokensInString } from './packem_shared/expandTokensInString-C03AGAjh.js';
 export { expandWildcard } from './packem_shared/expandWildcard-B0xN_knq.js';
 export { formatTimingTable, logTimings } from './packem_shared/formatTimingTable-3qtCM552.js';
 export { runTeardown } from './packem_shared/runTeardown-BAezH79J.js';

package/dist/packem_shared/{TaskOrchestrator-rf45vW5c.js → TaskOrchestrator-UCMHCx8c.js}

@@ -2,8 +2,9 @@ import { d as resolveTaskCwd, a as createFailureResult, e as createXxh3Hasher }
 import { resolve, join } from '@visulima/path';
 import { FingerprintManager } from './FingerprintManager-CV7U4f4f.js';
 import { generateRunSummary, writeLastRunSummary, writeRunSummary } from './generateRunSummary-BE1jnQ3H.js';
-import { computeTaskHash } from './computeTaskHash-DYqfrDGq.js';
+import { computeTaskHash } from './computeTaskHash-B5APHW7e.js';
 import { TrackedTaskExecutor } from './TrackedTaskExecutor-CFPpQfXF.js';
+import { getCurrentBranch, evaluateWhen, explainWhen } from './getCurrentBranch-DsKPDoVj.js';
 
 const hashFingerprint = (fingerprint) => {
   const hash = createXxh3Hasher();
@@ -54,6 +55,8 @@ class TaskOrchestrator {
   #taskGraph;
   #results = /* @__PURE__ */ new Map();
   #startTime;
+  #alwaysTasks;
+  #whenContext;
   /** Tracks in-flight task promises so the execution loop can await them */
   #inFlightTasks = /* @__PURE__ */ new Map();
   /** Deferred that gets resolved whenever a task completes, waking the loop */
@@ -78,6 +81,10 @@ class TaskOrchestrator {
     this.#summarize = options.summarize ?? false;
     this.#taskGraph = options.taskGraph ?? void 0;
     this.#startTime = Date.now();
+    this.#alwaysTasks = options.alwaysTasks ?? [];
+    this.#whenContext = options.whenContext ?? {
+      branch: getCurrentBranch(options.workspaceRoot)
+    };
     if (this.#autoFingerprint) {
       this.#fingerprintManager = new FingerprintManager(options.workspaceRoot);
       this.#trackedExecutor = new TrackedTaskExecutor(options.workspaceRoot);
@@ -96,6 +103,9 @@ class TaskOrchestrator {
     process.on("SIGTERM", signalHandler);
     try {
       await this.#executionLoop();
+      if (this.#alwaysTasks.length > 0 && !this.#aborted) {
+        await this.#runAlwaysTasks();
+      }
     } finally {
       process.removeListener("SIGINT", signalHandler);
       process.removeListener("SIGTERM", signalHandler);
@@ -110,6 +120,40 @@ class TaskOrchestrator {
     }
     return this.#results;
   }
+  /**
+   * Runs the configured `always: true` tasks sequentially after the
+   * main task graph completes. Each task's `when` clause is still
+   * honoured. Failures are recorded but never propagate — the whole
+   * point of an always-task is to fire regardless of upstream state.
+   *
+   * Always-tasks deliberately bypass `#processTask` /
+   * `#processTaskWithFingerprint`, which means **no cache lookup
+   * and no fingerprint check**. Cleanup / teardown / notification
+   * tasks are expected to run every invocation; serving them from
+   * cache would defeat the purpose.
+   */
+  async #runAlwaysTasks() {
+    for (const task of this.#alwaysTasks) {
+      this.#lifeCycle.scheduleTask?.(task);
+      this.#lifeCycle.startTasks?.([task]);
+      let result;
+      if (this.#shouldSkipForWhen(task)) {
+        result = this.#whenSkipResult(task);
+      } else {
+        const startTime = Date.now();
+        try {
+          result = await this.#executeTask(task, startTime);
+        } catch (error) {
+          result = createFailureResult(task, error, startTime);
+          this.#results.set(task.id, result);
+        }
+      }
+      this.#lifeCycle.endTasks?.([result]);
+      if (result.terminalOutput) {
+        this.#lifeCycle.printTaskTerminalOutput?.(result.task, result.status, result.terminalOutput);
+      }
+    }
+  }
   async #executionLoop() {
     while (!this.#scheduler.isComplete() && !this.#aborted) {
       const batch = this.#scheduler.getNextBatch();
@@ -130,7 +174,8 @@ class TaskOrchestrator {
       }
       this.#lifeCycle.startTasks?.(batch);
       for (const task of batch) {
-        const taskPromise = (this.#autoFingerprint ? this.#processTaskWithFingerprint(task) : this.#processTask(task)).catch((error) => {
+        const startPromise = this.#shouldSkipForWhen(task) ? Promise.resolve(this.#whenSkipResult(task)) : this.#autoFingerprint ? this.#processTaskWithFingerprint(task) : this.#processTask(task);
+        const taskPromise = startPromise.catch((error) => {
           const errorResult = createFailureResult(task, error, Date.now());
           this.#results.set(task.id, errorResult);
           return errorResult;
@@ -413,6 +458,27 @@ class TaskOrchestrator {
     this.#results.set(task.id, result);
     return result;
   }
+  #shouldSkipForWhen(task) {
+    if (!task.when) {
+      return false;
+    }
+    return !evaluateWhen(task.when, this.#whenContext);
+  }
+  #whenSkipResult(task) {
+    const reason = explainWhen(task.when, this.#whenContext);
+    const startTime = Date.now();
+    this.#lifeCycle.printWhenSkip?.(task, reason);
+    const result = {
+      code: 0,
+      endTime: startTime,
+      startTime,
+      status: "skipped",
+      task,
+      terminalOutput: reason ? `Skipped: ${reason}` : "Skipped by when clause"
+    };
+    this.#results.set(task.id, result);
+    return result;
+  }
 }
 
 export { TaskOrchestrator };

package/dist/packem_shared/{buildForwardDependencyMap-DLPgKEto.js → buildForwardDependencyMap-0BJFMMPv.js}

@@ -33,8 +33,7 @@ const findProjectForFile = (filePath, projects) => {
   let bestLength = 0;
   for (const [name, config] of Object.entries(projects)) {
     const { root } = config;
-    if ((filePath.startsWith(`${root}/`) || filePath === root) && // Prefer the most specific (longest) match
-    root.length > bestLength) {
+    if ((filePath.startsWith(`${root}/`) || filePath === root) && root.length > bestLength) {
       bestMatch = name;
       bestLength = root.length;
     }

package/dist/packem_shared/{computeTaskHash-DYqfrDGq.js → computeTaskHash-B5APHW7e.js}

@@ -27,7 +27,7 @@ const {
 import { b as hashStrings, s as sortObjectKeys, c as collectFiles, x as xxh3Hash, e as createXxh3Hasher } from './utils-zO0ZRgtf.js';
 import { join, resolve, relative } from '@visulima/path';
 import { getFrameworkEnvVariables } from './detectFrameworks-CeFzKE6J.js';
-import { LockfileHasher } from './extractPackageName-BllKetnz.js';
+import { LockfileHasher } from './extractPackageName-CbVNW-dr.js';
 import { loadNativeBindings } from './isNativeAvailable-BpD28A6Z.js';
 
 const DEFAULT_GLOBAL_INPUTS = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "tsconfig.base.json", "tsconfig.json", ".env"];

package/dist/packem_shared/{createTaskGraph-B7nH0kY_.js → createTaskGraph-B5YrfAMx.js}

@@ -38,13 +38,15 @@ const getSameProjectTask = (projectName, targetName, overrides, workspace, targe
   };
   return [
     {
+      always: project.targets?.[targetName]?.always ?? targetDefaults?.[targetName]?.always,
       cache: project.targets?.[targetName]?.cache ?? targetDefaults?.[targetName]?.cache,
       id: getTaskId(target),
       outputs: getTaskOutputs(projectName, targetName, workspace, targetDefaults),
       overrides,
       parallelism: project.targets?.[targetName]?.parallelism ?? targetDefaults?.[targetName]?.parallelism,
       projectRoot: project.root,
-      target
+      target,
+      when: project.targets?.[targetName]?.when ?? targetDefaults?.[targetName]?.when
     }
   ];
 };
@@ -63,13 +65,15 @@ const getDependencyProjectTasks = (projectName, targetName, overrides, workspace
         target: targetName
       };
       tasks.push({
+        always: depProject.targets?.[targetName]?.always ?? targetDefaults?.[targetName]?.always,
         cache: depProject.targets?.[targetName]?.cache ?? targetDefaults?.[targetName]?.cache,
         id: getTaskId(target),
         outputs: getTaskOutputs(dep.target, targetName, workspace, targetDefaults),
         overrides,
         parallelism: depProject.targets?.[targetName]?.parallelism ?? targetDefaults?.[targetName]?.parallelism,
         projectRoot: depProject.root,
-        target
+        target,
+        when: depProject.targets?.[targetName]?.when ?? targetDefaults?.[targetName]?.when
       });
     }
   }

package/dist/packem_shared/{defaultTaskRunner-Cp7jCmIl.js → defaultTaskRunner-DzR0ld8F.js}

@@ -3,10 +3,40 @@ import { Cache } from './Cache-CWaX_c8U.js';
 import { inferFrameworkEnvPatterns } from './detectFrameworks-CeFzKE6J.js';
 import { IncrementalFileHasher } from './IncrementalFileHasher-BRS76-mb.js';
 import { RemoteCache } from './RemoteCache-DSU3lc87.js';
-import { InProcessTaskHasher } from './computeTaskHash-DYqfrDGq.js';
-import { TaskOrchestrator } from './TaskOrchestrator-rf45vW5c.js';
+import { InProcessTaskHasher } from './computeTaskHash-B5APHW7e.js';
+import { TaskOrchestrator } from './TaskOrchestrator-UCMHCx8c.js';
 import { TaskScheduler } from './parsePartition-BfLbHGAx.js';
 
+const partitionAlwaysTasks = (taskGraph) => {
+  const alwaysTasks = [];
+  const remaining = {};
+  for (const [id, task] of Object.entries(taskGraph.tasks)) {
+    if (task.always) {
+      alwaysTasks.push(task);
+    } else {
+      remaining[id] = task;
+    }
+  }
+  if (alwaysTasks.length === 0) {
+    return { alwaysTasks: [], graph: taskGraph };
+  }
+  const alwaysIds = new Set(alwaysTasks.map((t) => t.id));
+  const dependencies = {};
+  for (const [id, deps] of Object.entries(taskGraph.dependencies)) {
+    if (alwaysIds.has(id)) {
+      continue;
+    }
+    dependencies[id] = deps.filter((dep) => !alwaysIds.has(dep));
+  }
+  return {
+    alwaysTasks,
+    graph: {
+      dependencies,
+      roots: taskGraph.roots.filter((id) => !alwaysIds.has(id)),
+      tasks: remaining
+    }
+  };
+};
 const computeGlobalEnvNamespace = (globalEnv) => {
   if (!globalEnv || globalEnv.length === 0) {
     return void 0;
@@ -56,8 +86,9 @@ const defaultTaskRunner = async (_tasks, options, context) => {
     targetDefaults: options.targetDefaults,
     workspaceRoot
   });
+  const { alwaysTasks, graph: scheduledGraph } = partitionAlwaysTasks(taskGraph);
   const maxParallel = resolveParallel(options.parallel);
-  const scheduler = new TaskScheduler(taskGraph, projectGraph, maxParallel);
+  const scheduler = new TaskScheduler(scheduledGraph, projectGraph, maxParallel);
   const resolveCommand = (task) => {
     const project = projectGraph.nodes[task.target.project];
     const targetConfig = project?.data.targets?.[task.target.target];
@@ -71,6 +102,7 @@ const defaultTaskRunner = async (_tasks, options, context) => {
     fingerprintEnvPatterns = [.../* @__PURE__ */ new Set([...fingerprintEnvPatterns, ...inferredPatterns])];
   }
   const orchestrator = new TaskOrchestrator({
+    alwaysTasks,
     autoFingerprint: options.autoFingerprint,
     cache,
     cacheDiagnostics: options.cacheDiagnostics,
@@ -84,7 +116,7 @@ const defaultTaskRunner = async (_tasks, options, context) => {
     skipCache: options.skipNxCache,
     summarize: options.summarize,
     taskExecutor,
-    taskGraph,
+    taskGraph: scheduledGraph,
     taskHasher,
     untrackedEnvVars: options.untrackedEnvVars,
     workspaceRoot

package/dist/packem_shared/expandTokensInString-C03AGAjh.js

@@ -0,0 +1,46 @@
+const TOKEN_PATHS = {
+  "affected.files": "affectedFiles",
+  changed_files: "affectedFiles"
+};
+const TOKEN_REGEX = /\\?\$\{\s*([\w.]+)\s*(?:\|\s*flag\s+(["'])(.*?)\2\s*)?\}/g;
+const shellQuote = (value) => `'${value.replaceAll("'", String.raw`'\''`)}'`;
+const rewriteForProjectRoot = (filePath, projectRoot) => {
+  if (filePath === projectRoot) {
+    return ".";
+  }
+  const prefix = `${projectRoot}/`;
+  if (filePath.startsWith(prefix)) {
+    return filePath.slice(prefix.length);
+  }
+  return void 0;
+};
+const expandTokensInString = (command, context) => command.replaceAll(TOKEN_REGEX, (match, name, _quote, flagValue) => {
+  if (match.startsWith("\\")) {
+    return match.slice(1);
+  }
+  const sourceKey = TOKEN_PATHS[name];
+  if (!sourceKey) {
+    return match;
+  }
+  const rawFiles = context[sourceKey] ?? [];
+  const files = context.projectRoot ? rawFiles.map((f) => rewriteForProjectRoot(f, context.projectRoot)).filter((f) => f !== void 0) : rawFiles;
+  if (files.length === 0) {
+    return "";
+  }
+  if (flagValue !== void 0 && flagValue.length > 0) {
+    return files.map((file) => `${flagValue} ${shellQuote(file)}`).join(" ");
+  }
+  return files.map(shellQuote).join(" ");
+});
+const expandTokens = (config, context) => {
+  if (!config.command.includes("${")) {
+    return config;
+  }
+  const command = expandTokensInString(config.command, context);
+  if (command === config.command) {
+    return config;
+  }
+  return { ...config, command };
+};
+
+export { expandTokens, expandTokensInString };

package/dist/packem_shared/{extractPackageName-BllKetnz.js → extractPackageName-CbVNW-dr.js}

@@ -44,8 +44,7 @@ const parseNpmLockfile = (content) => {
           continue;
         }
         const name = extractPackageName(path);
-        if (name && // Use the first (top-level) occurrence
-        !versions.has(name)) {
+        if (name && !versions.has(name)) {
           versions.set(name, entry.version);
         }
       }

package/dist/packem_shared/getCurrentBranch-DsKPDoVj.js

@@ -0,0 +1,153 @@
+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 {
+  execFileSync
+} = __cjs_getBuiltinModule("node:child_process");
+
+const normalisePlatform = (value) => value === "windows" ? "win32" : value;
+const matchPlatform = (clause, current) => {
+  const list = Array.isArray(clause) ? clause : [clause];
+  return list.some((p) => normalisePlatform(p) === normalisePlatform(current));
+};
+const matchBranch = (clause, current) => {
+  if (current === "") {
+    return false;
+  }
+  const list = Array.isArray(clause) ? clause : [clause];
+  return list.includes(current);
+};
+const matchSingleEnv = (matcher, env) => {
+  if (typeof matcher === "string") {
+    const value2 = env[matcher];
+    return value2 !== void 0 && value2 !== "";
+  }
+  const value = env[matcher.name];
+  if (matcher.equals !== void 0) {
+    return value === matcher.equals;
+  }
+  if (matcher.exists !== void 0) {
+    const present = value !== void 0 && value !== "";
+    return matcher.exists ? present : !present;
+  }
+  return value !== void 0 && value !== "";
+};
+const matchEnv = (clause, env) => {
+  const list = Array.isArray(clause) ? clause : [clause];
+  return list.some((m) => matchSingleEnv(m, env));
+};
+const detectCi = (env) => {
+  const value = env.CI;
+  return value !== void 0 && value !== "" && value !== "false" && value !== "0";
+};
+const branchCache = /* @__PURE__ */ new Map();
+const getCurrentBranch = (cwd) => {
+  const cached = branchCache.get(cwd);
+  if (cached !== void 0) {
+    return cached;
+  }
+  try {
+    const out = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"] });
+    let branch = out.toString("utf8").trim();
+    if (branch === "HEAD") {
+      branch = "";
+    }
+    branchCache.set(cwd, branch);
+    return branch;
+  } catch {
+    branchCache.set(cwd, "");
+    return "";
+  }
+};
+const resetBranchCache = () => {
+  branchCache.clear();
+};
+const evaluateWhen = (when, context = {}) => {
+  if (!when) {
+    return true;
+  }
+  const env = context.env ?? process.env;
+  const currentPlatform = context.platform ?? process.platform;
+  const branch = context.branch ?? "";
+  const ci = context.ci ?? detectCi(env);
+  if (when.os !== void 0 && !matchPlatform(when.os, currentPlatform)) {
+    return false;
+  }
+  if (when.env !== void 0 && !matchEnv(when.env, env)) {
+    return false;
+  }
+  if (when.branch !== void 0 && !matchBranch(when.branch, branch)) {
+    return false;
+  }
+  if (when.ci !== void 0 && when.ci !== ci) {
+    return false;
+  }
+  if (when.not) {
+    if (when.not.os !== void 0 && matchPlatform(when.not.os, currentPlatform)) {
+      return false;
+    }
+    if (when.not.env !== void 0 && matchEnv(when.not.env, env)) {
+      return false;
+    }
+    if (when.not.branch !== void 0 && matchBranch(when.not.branch, branch)) {
+      return false;
+    }
+    if (when.not.ci !== void 0 && when.not.ci === ci) {
+      return false;
+    }
+  }
+  return true;
+};
+const explainWhen = (when, context = {}) => {
+  if (!when || evaluateWhen(when, context)) {
+    return "";
+  }
+  const env = context.env ?? process.env;
+  const currentPlatform = context.platform ?? process.platform;
+  const branch = context.branch ?? "";
+  const ci = context.ci ?? detectCi(env);
+  const reasons = [];
+  if (when.os !== void 0 && !matchPlatform(when.os, currentPlatform)) {
+    reasons.push(`os=${currentPlatform} does not match ${JSON.stringify(when.os)}`);
+  }
+  if (when.env !== void 0 && !matchEnv(when.env, env)) {
+    reasons.push(`env clause did not match`);
+  }
+  if (when.branch !== void 0 && !matchBranch(when.branch, branch)) {
+    reasons.push(`branch=${branch || "(unknown)"} does not match ${JSON.stringify(when.branch)}`);
+  }
+  if (when.ci !== void 0 && when.ci !== ci) {
+    reasons.push(`ci=${ci} does not match required ci=${when.ci}`);
+  }
+  if (when.not?.os !== void 0 && matchPlatform(when.not.os, currentPlatform)) {
+    reasons.push(`os=${currentPlatform} matches excluded ${JSON.stringify(when.not.os)}`);
+  }
+  if (when.not?.env !== void 0 && matchEnv(when.not.env, env)) {
+    reasons.push(`env clause matches excluded matcher`);
+  }
+  if (when.not?.branch !== void 0 && matchBranch(when.not.branch, branch)) {
+    reasons.push(`branch=${branch} matches excluded ${JSON.stringify(when.not.branch)}`);
+  }
+  if (when.not?.ci !== void 0 && when.not.ci === ci) {
+    reasons.push(`ci=${ci} matches excluded ci=${when.not.ci}`);
+  }
+  return reasons.join("; ");
+};
+
+export { evaluateWhen, explainWhen, getCurrentBranch, resetBranchCache };

package/dist/packem_shared/{parseCommands-D-IgF8Zh.js → parseCommands-CJ16ohOB.js}

@@ -1,10 +1,12 @@
 import { expandArguments } from './expandArguments-0AwD2BIA.js';
 import { expandShortcut } from './expandShortcut-BVG05ee4.js';
+import { expandTokens } from './expandTokensInString-C03AGAjh.js';
+export { expandTokensInString } from './expandTokensInString-C03AGAjh.js';
 import { expandWildcard } from './expandWildcard-B0xN_knq.js';
 import { stripQuotes } from './stripQuotes-Cey-zwFf.js';
 
 const parseCommands = (inputs, options = {}) => {
-  const { additionalArguments = [] } = options;
+  const { additionalArguments = [], tokens } = options;
   let configs = inputs.map((input) => {
     if (typeof input === "string") {
       return { command: input };
@@ -17,10 +19,13 @@ const parseCommands = (inputs, options = {}) => {
     const result = expandWildcard(config);
     return Array.isArray(result) ? result : [result];
   });
+  if (tokens) {
+    configs = configs.map((config) => expandTokens(config, tokens));
+  }
   if (additionalArguments.length > 0) {
     configs = configs.map((config) => expandArguments(config, additionalArguments));
   }
   return configs;
 };
 
-export { expandArguments, expandShortcut, expandWildcard, parseCommands, stripQuotes };
+export { expandArguments, expandShortcut, expandTokens, expandWildcard, parseCommands, stripQuotes };