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

package/dist/packem_shared/withRestart-BREjRJa4.js

@@ -0,0 +1,49 @@
+const withRestart = async (runFunction, commands, options, restartOptions) => {
+  const { delay, tries } = restartOptions;
+  if (tries === 0) {
+    return runFunction(commands, options);
+  }
+  const state = /* @__PURE__ */ new Map();
+  const allCloseEvents = [];
+  const userOnEvent = options.onEvent;
+  let pendingRestarts = [...commands];
+  let iteration = 0;
+  while (pendingRestarts.length > 0) {
+    const currentBatch = pendingRestarts;
+    pendingRestarts = [];
+    const result = await runFunction(currentBatch, {
+      ...options,
+      onEvent: (event) => {
+        userOnEvent?.(event);
+      }
+    });
+    for (const closeEvent of result.closeEvents) {
+      if (closeEvent.exitCode !== 0) {
+        const cmdState = state.get(closeEvent.index) ?? { attempts: 0, commandIndex: closeEvent.index };
+        cmdState.attempts++;
+        state.set(closeEvent.index, cmdState);
+        const shouldRestart = tries === -1 || cmdState.attempts <= tries;
+        if (shouldRestart) {
+          const delayMs = delay === "exponential" ? Math.min(2 ** (cmdState.attempts - 1) * 1e3, 3e4) : delay;
+          if (delayMs > 0) {
+            await sleep(delayMs);
+          }
+          pendingRestarts.push(currentBatch[closeEvent.index]);
+          continue;
+        }
+      }
+      allCloseEvents.push(closeEvent);
+    }
+    iteration++;
+    if (iteration > 1e3) {
+      break;
+    }
+  }
+  const success = allCloseEvents.every((e) => e.exitCode === 0);
+  return { closeEvents: allCloseEvents, success };
+};
+const sleep = (ms) => new Promise((resolve) => {
+  setTimeout(resolve, ms);
+});
+
+export { withRestart };

package/dist/project-constraints.d.ts

@@ -0,0 +1,9 @@
+import type { ConstraintsConfig, ConstraintViolation, ProjectGraph } from "./types.d.ts";
+/**
+ * Enforces project dependency constraints on a project graph.
+ * @param projectGraph The workspace project graph to validate.
+ * @param constraints The constraint rules to enforce.
+ * @returns Array of violations found. Empty means all constraints pass.
+ */
+declare const enforceProjectConstraints: (projectGraph: ProjectGraph, constraints: ConstraintsConfig) => ConstraintViolation[];
+export { enforceProjectConstraints };

package/dist/task-scheduler.d.ts

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

package/dist/terminal-buffer.d.ts

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

package/dist/types.d.ts

@@ -85,6 +85,15 @@ export type TaskResults = Map<string, TaskResult>;
 export interface ProjectConfiguration {
     /** Implicit dependencies on other projects */
     implicitDependencies?: string[];
+    /**
+     * Project layer in the dependency hierarchy. Used by
+     * `enforceLayerRelationships` to ensure projects only depend on
+     * projects at the same or lower layer.
+     *
+     * Hierarchy (lowest → highest):
+     * `configuration < library < scaffolding < tool < automation < application`
+     */
+    layer?: "application" | "automation" | "configuration" | "library" | "scaffolding" | "tool";
     /** The project type */
     projectType?: "library" | "application";
     /** The root directory of the project, relative to workspace root */
@@ -160,6 +169,91 @@ export interface EnvironmentInput {
 export interface ExternalDependencyInput {
     externalDependencies: string[];
 }
+/**
+ * Defines tag-based dependency rules.
+ * Each key is a tag name. The value is the list of tags that a dependency
+ * must have at least one of, when the source project has that tag.
+ *
+ * Example: `{ "frontend": ["shared", "frontend"] }` means a project tagged
+ * "frontend" can only depend on projects tagged "shared" or "frontend".
+ */
+export type TagRelationships = Record<string, string[]>;
+/**
+ * Defines project-type-based dependency rules.
+ */
+export interface TypeBoundaries {
+    /**
+     * Custom rules mapping project types to allowed dependency types.
+     * Example: `{ "application": ["library"] }` means applications can only
+     * depend on libraries.
+     */
+    allowedDependencyTypes?: Record<string, string[]>;
+    /**
+     * When true, no project may depend on an "application" type project.
+     * Applications are typically deployment targets, not libraries.
+     * @default true
+     */
+    enforceApplicationBoundary?: boolean;
+}
+/**
+ * Rules based on the dependency kind (dependencies vs devDependencies vs peerDependencies).
+ */
+export interface DependencyKindRules {
+    /**
+     * When true, a "library" project must not have workspace-internal devDependencies
+     * on other libraries that are also in its production dependencies.
+     * Prevents publishing libraries that silently rely on dev-only workspace packages.
+     * @default false
+     */
+    noDevDependencyOnProductionDep?: boolean;
+    /**
+     * When true, production `dependencies` must not point to "application" type projects.
+     * devDependencies on applications are allowed (e.g., for testing).
+     * @default false
+     */
+    noProductionDependencyOnApplication?: boolean;
+}
+/**
+ * Configuration for project constraint enforcement.
+ */
+export interface ConstraintsConfig {
+    /** Rules based on the dependency kind (static vs devDependency vs peerDependency) */
+    dependencyKindRules?: DependencyKindRules;
+    /**
+     * When true, projects can only depend on projects at the same or
+     * lower layer in the hierarchy:
+     *
+     *   configuration < library < scaffolding < tool < automation < application
+     *
+     * Projects without an explicit `layer` are unconstrained.
+     * @default false
+     */
+    enforceLayerRelationships?: boolean;
+    /** Tag-based dependency rules */
+    tagRelationships?: TagRelationships;
+    /** Project-type-based dependency rules */
+    typeBoundaries?: TypeBoundaries;
+}
+/**
+ * A single constraint violation detected in the project graph.
+ */
+export interface ConstraintViolation {
+    /** The project being depended on */
+    dependencyProject: string;
+    /** Human-readable description of the violation */
+    message: string;
+    /** The type of rule that was violated */
+    rule: "dependency-kind" | "layer-relationship" | "tag-relationship" | "type-boundary";
+    /** The project that has the invalid dependency */
+    sourceProject: string;
+}
+/**
+ * Controls how far to traverse the dependency graph in a given direction.
+ * - "none": Don't traverse — only directly changed projects are included.
+ * - "direct": Include only immediate neighbors (one hop).
+ * - "deep": Include all transitive neighbors (full chain).
+ */
+export type AffectedScope = "deep" | "direct" | "none";
 /**
  * Workspace configuration containing all project configurations.
  */
@@ -167,6 +261,15 @@ export interface WorkspaceConfiguration {
     /** All projects in the workspace, keyed by project name */
     projects: Record<string, ProjectConfiguration>;
 }
+/**
+ * The kind of dependency relationship between projects.
+ * - "static": Production dependency (from `dependencies` in package.json)
+ * - "dynamic": Dynamically resolved dependency (e.g., lazy imports)
+ * - "implicit": Declared via `implicitDependencies` in project config
+ * - "devDependency": Development-only dependency (from `devDependencies`)
+ * - "peerDependency": Peer dependency (from `peerDependencies`)
+ */
+export type DependencyType = "devDependency" | "dynamic" | "implicit" | "peerDependency" | "static";
 /**
  * A dependency relationship in the project graph.
  */
@@ -176,7 +279,7 @@ export interface ProjectGraphDependency {
     /** The target project */
     target: string;
     /** The type of dependency */
-    type: "static" | "dynamic" | "implicit";
+    type: DependencyType;
 }
 /**
  * A node in the project graph.
@@ -370,6 +473,141 @@ export interface TaskRunnerContext {
     /** The workspace root directory */
     workspaceRoot: string;
 }
+/**
+ * Input for a concurrent command -- either a string or a config object.
+ */
+export type ConcurrentCommandInput = string | {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    name?: string;
+    /** Initial PTY dimensions (only used when stdin is "pty"). */
+    ptySize?: {
+        cols: number;
+        rows: number;
+    };
+    stdin?: "inherit" | "null" | "pipe" | "pty";
+};
+/**
+ * Configuration for a single command to run concurrently.
+ */
+export interface ConcurrentCommandConfig {
+    /** The command string to execute (passed to shell). */
+    command: string;
+    /** Working directory for the command. */
+    cwd?: string;
+    /** Additional environment variables merged with process env. */
+    env?: Record<string, string>;
+    /** Human-readable name for this command (used in prefixes/logs). */
+    name?: string;
+    /**
+     * Initial PTY dimensions. Only used when stdin is "pty".
+     * Defaults to 80x24 if not specified.
+     */
+    ptySize?: {
+        cols: number;
+        rows: number;
+    };
+    /** Whether to use shell execution (default: true). */
+    shell?: boolean;
+    /**
+     * Stdin mode for the child process.
+     * - "null" (default): stdin closed, child cannot read input
+     * - "pipe": stdin is piped, can be written to programmatically
+     * - "inherit": child inherits parent's stdin (for interactive commands like vite dev)
+     * - "pty": child runs inside a pseudo-terminal (isatty() returns true, enables interactive prompts)
+     */
+    stdin?: "inherit" | "null" | "pipe" | "pty";
+}
+/**
+ * Options controlling the concurrent runner behavior.
+ */
+export interface ConcurrentRunnerOptions {
+    /** Conditions under which to kill other processes: "success", "failure". */
+    killOthers?: ("failure" | "success")[];
+    /** Signal to send when killing processes (default: "SIGTERM"). */
+    killSignal?: string;
+    /** Milliseconds to wait after kill signal before sending SIGKILL (default: 5000). */
+    killTimeout?: number;
+    /** Maximum number of processes to run simultaneously. 0 = unlimited. */
+    maxProcesses?: number;
+    /** Callback for real-time process events. */
+    onEvent?: (event: ProcessEvent) => void;
+    /** Restart options for failed commands. */
+    restart?: {
+        /** Delay between restarts in ms. "exponential" for 2^attempt * 1000ms. */
+        delay?: number | "exponential";
+        /** Maximum restart attempts per command. 0 = no restarts. -1 = infinite. */
+        tries: number;
+    };
+    /**
+     * Custom shell path for command execution.
+     * Overrides the platform default (/bin/sh on Unix, cmd.exe on Windows).
+     * Automatically detected from npm's `script-shell` config if not set.
+     */
+    shellPath?: string;
+    /** Success condition: "first", "last", "all", or "command-&lt;name|index>". */
+    successCondition?: string;
+    /** Commands to run sequentially after all processes complete. */
+    teardown?: string[];
+    /** Working directory for teardown commands. */
+    teardownCwd?: string;
+    /** Print a timing summary table after completion. Default: false. */
+    timings?: boolean;
+}
+/**
+ * An event emitted during concurrent execution.
+ */
+export interface ProcessEvent {
+    /** Command name (for close events). */
+    commandName?: string;
+    /** Duration in milliseconds (for close events). */
+    durationMs?: number;
+    /** Exit code (for close events). */
+    exitCode?: number;
+    /** Index of the command that produced this event. */
+    index: number;
+    /** Kill the child process/PTY. Only present on "started" events. */
+    kill?: (signal?: string) => void;
+    /** Whether the process was killed (for close events). */
+    killed?: boolean;
+    /** Event type: "stdout", "stderr", "close", "error", "started". */
+    kind: "close" | "error" | "started" | "stderr" | "stdout";
+    /** Error message (for error events). */
+    message?: string;
+    /** Resize the child's PTY. Only present on "started" events with stdin "pty". */
+    resize?: (cols: number, rows: number) => void;
+    /** Text content (for stdout/stderr events). */
+    text?: string;
+    /** Write data to the child's stdin (pipe) or PTY. Only present on "started" events. */
+    write?: (data: string) => void;
+}
+/**
+ * Result of a close event for a single command.
+ */
+export interface ConcurrentCloseEvent {
+    /** The command string that was executed. */
+    command: string;
+    /** Duration in milliseconds. */
+    durationMs: number;
+    /** Exit code. -1 if killed by signal. */
+    exitCode: number;
+    /** Index of the command. */
+    index: number;
+    /** Whether the process was forcefully killed. */
+    killed: boolean;
+    /** The command name (if provided). */
+    name?: string;
+}
+/**
+ * Overall result of a concurrent run.
+ */
+export interface ConcurrentRunResult {
+    /** Close events for all commands, in completion order. */
+    closeEvents: ConcurrentCloseEvent[];
+    /** Whether the run succeeded according to the success condition. */
+    success: boolean;
+}
 /**
  * Interface for lifecycle event handlers.
  */