4.1Registration

Tasks are registered via the tasks API, which is available from the public API. During config file loading, calls to tasks.register() delegate to the active Nadle instance via an AsyncLocalStorage context. Each Nadle instance owns its own task registry, ensuring full isolation between instances. There are three registration forms:

All three forms return a configuration builder that exposes a .config() method (see 02-task-configuration.md).

4.2Naming Rules

Task names must match the pattern: ^[a-z]([a-z0-9-]*[a-z0-9])?$ (case-insensitive).

If a task name is invalid, registration fails with an error.

4.3Duplicate Detection

Task names must be unique within a workspace. The same name may appear in different workspaces. If a duplicate name is registered in the same workspace, registration fails with an error.

4.4Task Identity

A task is uniquely identified by a task identifier string:

The separator is a colon (:). The last segment is always the task name; preceding segments form the workspace ID.

4.5Status Lifecycle

A task moves through the following statuses:

                                    +-> Finished
                                    |
Registered -> Scheduled -> Running -+-> Failed
                  |                 |
                  |                 +-> Canceled
                  |
                  +-> UpToDate
                  |
                  +-> FromCache

4.6Reusable Task Types

The defineTask() function creates a reusable task type with a typed options contract. It is an identity function that enables type inference for the run function’s options parameter.

A reusable task type is then registered with tasks.register(name, taskObject, resolver) where the resolver provides the concrete options for this instance.

---

5.1Configuration Fields

All fields are optional.

5.2Builder Pattern

The configuration builder exposes a single method:

• config(builderOrObject) — accepts a static object or a callback returning the object.

Calling .config() replaces the entire configuration (it does not merge). The last call wins.

5.3dependsOn Resolution

Dependency strings are resolved as follows:

1. No colon (e.g., "build") — resolved within the current workspace.
2. With colon (e.g., "packages:foo:build") — the last segment is the task name; preceding segments form the workspace ID. Resolved by workspace ID or label.
3. Root workspace — use "root:taskName" (root workspace ID is always "root").

If a dependency is not found in the target workspace, Nadle falls back to the root workspace. If still not found, an error is raised with suggestions.

Excluded tasks (via --exclude) are filtered out of the resolved dependency set.

5.4Declarations DSL

Declarations describe file patterns for inputs and outputs. There are two types:

Outputs.files and Outputs.dirs are aliases for Inputs.files and Inputs.dirs respectively — there is no functional difference.

5.5Environment Variables

The env field accepts a map of key-value pairs where values may be strings, numbers, or booleans. Non-string values are converted to strings (via String(val)) before being applied to the worker process environment.

Environment variables are applied before the task function runs and restored to their original values afterward.

5.6Working Directory

The workingDir field is resolved relative to the project root workspace’s absolute path. If omitted, it defaults to the project root. The resolved absolute path is provided to the task function via the runner context.

---

6.1DAG Construction

The scheduler maintains three internal graphs:

Additionally, an indegree map tracks the number of unresolved dependencies for each task.

6.2Cycle Detection

After analysis, cycles are detected using depth-first traversal. For each task, the scheduler walks its dependency chain. If a task is encountered that already exists in the current path, a cycle is detected.

• If a cycle is found, Nadle raises an error that includes the full cycle path (e.g., a -> b -> c -> a).
• Cycle detection runs before any task execution begins.

6.3Workspace Task Expansion

When a task is specified at the root workspace level and child workspaces have tasks with the same name, Nadle automatically expands the request to include the matching child workspace tasks. This only applies to tasks registered in the root workspace.

6.4Execution Modes

6.5Exclusion

Tasks specified via --exclude are removed from consideration during analysis. They are filtered out of dependency sets, so they and their exclusive subtrees are not scheduled.

6.6Execution Plan

The execution plan is the ordered list of tasks produced by simulating Kahn’s algorithm to completion. This plan is used by dry-run mode to display the intended execution order.

---

7.1Worker Pool

The pool is configured with:

Worker count values are clamped to [1, availableParallelism]. Percentage strings (e.g., "50%") are multiplied by availableParallelism and rounded.

7.2Worker Parameters

Each task dispatch sends these parameters to the worker:

7.3Message Protocol

Workers communicate back to the pool via MessagePort. There are exactly three message types:

7.4Worker Execution Flow

1. Initialize Nadle in the worker thread on the first task dispatch using a lightweight path: the worker receives the fully resolved options (including the project structure) from the main thread, loads config files to populate task function closures and the task registry, but skips project resolution, option merging, and task input resolution. The instance is cached at module scope and reused for subsequent dispatches within the same thread, so config files are loaded at most once per worker thread lifetime.
2. Look up the task by ID in the registry.
3. Resolve the task’s configuration and options.
4. Resolve the working directory (relative to project root).
5. Run cache validation (see 05-caching.md).
6. Based on validation result:
   • not-cacheable or cache-disabled: send "start", apply env, execute, restore env.
   • up-to-date: send "up-to-date", return.
   • restore-from-cache: restore outputs, update cache pointer, send "from-cache".
   • cache-miss: log reasons, send "start", apply env, execute, restore env, save outputs and metadata.

7.5Environment Injection

Before executing the task function:

1. The original process environment is merged with the task’s env field.
2. After execution, injected keys are removed and original values restored.

Non-string env values are converted to strings before application.

7.6Cancellation

If a task fails and other tasks are still running:

1. The pool is destroyed, which terminates all worker threads.
2. A terminated worker throws a “Terminating worker thread” error.
3. The pool detects this error and checks if the task’s status is Running.
4. If Running, the task is marked as Canceled (not Failed).

7.7Cleanup

The pool is always destroyed in a finally block after execution, whether it succeeds or fails. This ensures all worker threads are terminated.

7.8Task Chaining

After a task completes successfully, the pool queries the scheduler for newly ready tasks (those whose indegree has reached zero). Each ready task is dispatched to the pool, enabling concurrent execution of independent tasks.

---

8.1Precondition

A task is cacheable only if both inputs and outputs are declared in its configuration. If either is missing, the task is always executed.

8.2Validation Outcomes

Cache validation produces exactly one of five results:

8.3Validation Flow

1. Check if task is cacheable (inputs AND outputs defined). If not, return not-cacheable.
2. Check if caching is enabled (cache flag). If not, return cache-disabled.
3. Compute input fingerprints from config files and declared input patterns.
4. Compute cache key from {taskId, inputsFingerprints, env}.
5. Check if a cache entry exists for this key.
6. If no cache entry exists, return cache-miss with reasons.
7. Read the latest run metadata.
8. Compute current output fingerprints.
9. If the latest run’s cache key matches AND output fingerprints match, return up-to-date. 10. Otherwise, return restore-from-cache.

8.4Input Fingerprinting

Each input file is hashed with SHA-256 to produce a hex-encoded fingerprint. The result is a map from absolute file path to fingerprint string.

8.5Cache Key Computation

The cache key is computed by hashing an object containing:

The hash is SHA-256 with unordered object and array comparison, producing a 64-character hex string.

8.6Up-to-date vs Restore-from-cache

| | Up-to-date | Restore-from-cache | | ---------------------------- | ------------------------- | ----------------------------------------------- | | Cache key matches latest run | Yes | Not necessarily (may match a non-latest run) | | Output files exist on disk | Yes, with correct content | May be missing or modified | | Action | Skip entirely | Copy cached outputs back, update latest pointer |

8.7Cache Miss Reasons

When a cache miss occurs, reasons are computed by comparing the previous run’s input fingerprints with the current ones:

Multiple reasons may be reported for a single cache miss.

8.8Storage Layout

Cache data is stored under the cache directory (default: .nadle/):

{cacheDir}/
  tasks/
    {encodedTaskId}/
      metadata.json                     # Latest run pointer
      runs/
        {cacheKey}/                     # 64-char hex hash
          metadata.json                 # Run metadata
          outputs/                      # Snapshot of output files
            {relative-paths}...

8.9Output Snapshot

8.10Cache Update Flow

After validation, the cache is updated based on the result:

---

9.1Project Structure

9.2Root Detection

The project root is found by searching upward from the current directory:

1. Look for a nadle.config.{js,mjs,ts,mts} file.
2. Detect a monorepo root via package manager tooling (lock files, workspace config).
3. Check for nadle.root: true in package.json.

The root workspace must have a config file. If no config file is found, Nadle raises an error with guidance to use --config.

9.3Package Manager Detection

The package manager is detected automatically from lock files and workspace configuration — it is not manually configured. Detection uses the @manypkg/tools library.

9.4Workspace Discovery

Child workspaces are discovered via the package manager’s workspace configuration:

• pnpm: pnpm-workspace.yaml
• npm/yarn: workspaces field in root package.json

Each discovered package directory becomes a workspace (see 07-workspace.md).

Workspaces are sorted by their relative path for deterministic ordering.

9.5Project Resolution Flow

1. Find the project root (config file or monorepo root).
2. Detect the package manager.
3. Discover all workspaces.
4. Create the root workspace with its config file path.
5. Create child workspaces with their package metadata.
6. Resolve workspace dependencies from package.json.
7. Apply alias configuration (if any).
8. Validate workspace labels for uniqueness.

9.6Current Workspace

The current workspace is determined by the directory where Nadle is invoked. It defaults to the root workspace. The current workspace ID affects which workspace receives task registrations when loading config files.

---

10.1Workspace Fields

10.2Identity

Workspace IDs are derived from the relative path by replacing path separators with colons:

The root workspace always has the ID "root" and the relative path ".".

Backslashes (Windows paths) are normalized to forward slashes before conversion.

10.3Config Files

Each workspace may have its own nadle.config.{js,mjs,ts,mts} file:

• The root workspace’s config file is required.
• Child workspace config files are optional.
• Workspace config files are loaded after the root config file.
• Config files register tasks scoped to their workspace.

10.4Workspace Dependencies

Workspace dependencies are populated from the package.json dependency fields:

• dependencies
• devDependencies
• peerDependencies
• optionalDependencies

If a dependency references another workspace in the project (e.g., via workspace:* protocol), it is recorded as a workspace dependency. These dependencies are informational and used for workspace ordering — they do not automatically create task dependencies.

10.5Aliases

Aliases provide human-readable labels for workspaces. They are configured via the configure() function in the root config file:

• Object map: { "shared/api": "api" } — maps workspace paths to labels.
• Function: (workspacePath) => label | undefined — returns a label or undefined.

10.6Task Scoping

• Tasks are scoped to the workspace whose config file registered them.
• The same task name may exist in different workspaces.
• When resolving a task reference without a workspace prefix, Nadle looks in the current workspace first.
• If the task is not found in the current workspace, Nadle falls back to the root workspace.

---

11.1Supported Formats

Config files may use any of these extensions:

11.2Default Config File

The default config file name is nadle.config.ts. Nadle searches for config files in this precedence order:

1. nadle.config.js
2. nadle.config.ts
3. nadle.config.mjs
4. nadle.config.mts

If multiple exist, the first match wins (JS before TS, TS before MTS).

The --config flag overrides this search and specifies an explicit path.

11.3Runtime Transpilation

Config files are loaded using jiti, which provides:

• ESM support regardless of the project’s module format.
• TypeScript transpilation without a separate build step.
• Interop for default exports.

11.4Loading Flow

Config files are loaded within an AsyncLocalStorage context bound to the active Nadle instance. This enables tasks.register() and configure() to route registrations to the correct instance without requiring explicit parameters.

1. CLI parse: yargs parses command-line arguments.
2. Config file resolution: find and load the root config file.
3. Root config execution: the config file runs within the instance context, calling tasks.register() and optionally configure().
4. Workspace config loading: for each workspace with a config file, set the workspace context and load the file (still within the same instance context).
5. Project resolution: resolve project structure, workspaces, and dependencies.
6. Task finalization: flush the task registry buffer into the final registry.
7. Options merge: combine defaults, file options, and CLI options.

11.5The `configure()` Function

The configure() function may be called from the root config file only. It sets file-level options that are merged between defaults and CLI options.

Accepted options:

If configure() is called from a non-root workspace config file, it raises an error.

11.6Option Precedence

Options are merged in this order (later wins):

Built-in defaults < File options (configure()) < CLI flags

11.7Built-in Defaults

11.8Worker Count Resolution

Worker count values can be:

• An integer: used directly.
• A percentage string (e.g., "50%"): multiplied by availableParallelism and rounded.

The result is always clamped to [1, availableParallelism]. The minWorkers value is additionally capped at maxWorkers.

11.9Supported Log Levels

The following log levels are supported, in increasing verbosity:

1. "error" — errors only
2. "log" — standard output (default)
3. "info" — informational messages
4. "debug" — debug-level output

---

12.1Command Structure

nadle [tasks...] [options]

• tasks — zero or more task names or task identifiers to execute.
• If no tasks are specified and stdin is a TTY, Nadle enters interactive task selection.

12.2Flags

12.3Handler Chain

After options are resolved, Nadle selects a handler using a first-match-wins chain:

Each handler is instantiated and its canHandle() method is checked. The first handler that returns true has its handle() method invoked. Only one handler runs per invocation.

12.4Exit Codes

When an error is caught during execution:

• If the error is a NadleError, exit with its errorCode.
• Otherwise, exit with code 1.

12.5Interactive Task Selection

When no tasks are specified on the command line and stdin is a TTY, Nadle enters an interactive mode where the user can select tasks from a list. This state is tracked internally and affects footer rendering.

---

13.1ExecTask

Executes an arbitrary external command.

13.2PnpmTask

Executes a pnpm command. Specialized variant of ExecTask with pnpm as the command.

13.3CopyTask

Copies files and directories using glob patterns.

13.4DeleteTask

Deletes files and directories using glob patterns.

13.5Common Properties

All built-in tasks share these characteristics:

• They all respect the workingDir from the runner context.
• ExecTask and PnpmTask force color output via FORCE_COLOR=1 environment variable.
• All tasks stream output through the task logger.

13.6Custom Task Types

Users create custom reusable task types using defineTask():

defineTask({
  run: ({ options, context }) => { ... }
})

The run function receives typed options and a runner context. The returned task object is then registered with tasks.register(name, taskObject, optionsResolver).

---

14.1Listener Interface

A listener is an object with optional methods for each lifecycle event. All event methods are optional — a listener may implement any subset.

14.2Events

Events are listed in typical emission order:

14.3Emission Order

Events are emitted sequentially through all registered listeners, in registration order. For each event:

1. Iterate through all listeners.
2. For each listener that implements the event method, call it and await the result.
3. Move to the next listener.

This means listeners are called in order and each listener’s handler completes before the next is invoked.

14.4Built-in Listeners

Nadle registers two built-in listeners in this order:

The ExecutionTracker runs first so that statistics are up-to-date when the DefaultReporter renders output.

14.5ExecutionTracker Details

The execution tracker maintains:

• Task stats: count of tasks in each status (Scheduled, Running, Finished, UpToDate, FromCache, Failed, Canceled).
• Duration: total execution time, updated every 100ms via an interval timer.
• Per-task state: status, duration, start time, and thread ID for each task.

The duration timer is unreferenced so it does not prevent the process from exiting.

14.6Custom Listeners

Custom listeners are not directly supported through the public API in the current implementation. The event emitter is initialized with a fixed set of listeners (ExecutionTracker and DefaultReporter).

---

15.1NadleError

NadleError is a specialized error class with a numeric exit code.

15.2Error Propagation

Errors flow through the system in this chain:

Task function throws
  -> Worker promise rejects
    -> Pool catches the error
      -> onTaskFailed event emitted
        -> Error re-thrown to handler
          -> onExecutionFailed event emitted
            -> Process exits with error code

15.3Exit Code Determination

if error is NadleError:
  exit with error.errorCode
else:
  exit with 1

15.4Known Error Types

15.5Stacktrace Display

By default, only the error message is shown. When --stacktrace is passed:

• The full error stack trace is printed.
• Without --stacktrace, a hint is shown suggesting the user re-run with the flag.

---

16.1Footer

The footer is a live-updating display at the bottom of the terminal showing execution progress.

16.2Task Status Messages

During execution, each task event produces a status message:

16.3Execution Result

RUN SUCCESSFUL in {duration}
{N} tasks executed[, {N} tasks up-to-date][, {N} tasks restored from cache]

RUN FAILED in {duration} ({N} tasks executed, {N} tasks failed)

For more details, re-run the command with the --stacktrace option...

16.4Summary (`—summary`)

When --summary is passed, an end-of-run profiling table is printed showing each finished task with its execution duration. This is rendered after the success message and before the final status line.

Only tasks with status Finished are included in the summary (not up-to-date or from-cache tasks).

16.5Welcome Banner

At execution start (unless --show-config is active), Nadle prints:

🛠️ Welcome to Nadle v{version}!
Using Nadle from {path}
Loaded configuration from {configFile}[ and {N} other(s) files]

16.6Task Resolution Display

If any task names were auto-corrected during resolution (e.g., fuzzy matching), the corrected mappings are displayed:

Resolved tasks:
    {original}  → {corrected}