### Clone and Build Wireit

Source: https://github.com/google/wireit/blob/main/CONTRIBUTING.md

Clone the repository, install dependencies, and build the project. This is the initial setup step for development.

```sh
git clone https://github.com/google/wireit.git
cd wireit
npm ci
npm run build
```

--------------------------------

### Install VSCode Extension

Source: https://github.com/google/wireit/blob/main/README.md

Install the Wireit VSCode extension from the marketplace using the command line.

```sh
code --install-extension google.wireit
```

--------------------------------

### Install Wireit

Source: https://github.com/google/wireit/blob/main/README.md

Install Wireit as a development dependency using npm.

```sh
npm i -D wireit
```

--------------------------------

### Wireit CLI Orchestration Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cli.md

Demonstrates the basic orchestration flow for the Wireit CLI, including getting options, running tasks, and handling errors.

```typescript
const optionsResult = await getOptions()
if (!optionsResult.ok) {
  // Log error and exit
  process.exit(1)
}

const options = optionsResult.value
const result = await run(options)

if (!result.ok) {
  for (const failure of result.error) {
    options.logger.log(failure)
  }
  process.exitCode = 1
}
```

--------------------------------

### ServiceConfig Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/config.md

An example of how to configure service readiness detection using a regex pattern to match output lines.

```typescript
{
  readyWhen: {
    lineMatches: /listening on port \d+/
  }
}
```

--------------------------------

### Example GitHub Actions Workflow with Wireit Caching

Source: https://github.com/google/wireit/blob/main/README.md

A complete GitHub Actions workflow demonstrating the setup for Node.js, Wireit caching, and running npm tests. Wireit automatically leverages the GitHub Actions cache.

```yaml
# File: .github/workflows/tests.yml

name: Tests
on: [push, pull_request]
jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      # Set up GitHub Actions caching for Wireit.
      - uses: google/wireit@setup-github-actions-caching/v2

      # Install npm dependencies.
      - run: npm ci

      # Run tests. Wireit will automatically use
      # the GitHub Actions cache whenever possible.
      - run: npm test

```

--------------------------------

### Example Output for SpawnError

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Provides an example of the user-facing message when a script process fails to spawn.

```text
❌ mypackage:build — spawn error: command not found
```

--------------------------------

### NoCommandScriptConfig Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/config.md

An example of how to configure a script with no command in Wireit's configuration file. This script acts as a dependency container.

```json
{
  "wireit": {
    "build": {
      "dependencies": ["build:compile", "build:types"]
    }
  }
}
```

--------------------------------

### Service Script Configuration Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/config.md

An example of a service script configuration in Wireit. This configures a Node.js server to run and specifies a 'readyWhen' condition based on log output.

```json
{
  "wireit": {
    "server": {
      "command": "node server.js",
      "service": {
        "readyWhen": {
          "lineMatches": "listening on port"
        }
      }
    }
  }
}
```

--------------------------------

### StandardScriptConfig Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/config.md

An example of a standard script configuration in Wireit. This script executes a command, caches its output, and cleans previous outputs if specified.

```json
{
  "wireit": {
    "build": {
      "command": "tsc",
      "files": ["src/**/*.ts"],
      "output": ["lib/**"],
      "clean": true
    }
  }
}
```

--------------------------------

### SimpleLogger Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/logger.md

Demonstrates how to instantiate and use the SimpleLogger. Ensure Console and SimpleLogger are imported correctly.

```typescript
import {SimpleLogger} from './logging/simple-logger.js'
import {Console} from './logging/logger.js'

const console = new Console(process.stdout, process.stderr)
const logger = new SimpleLogger(process.cwd(), console)
```

--------------------------------

### Wireit Configuration Example

Source: https://github.com/google/wireit/blob/main/_autodocs/README.md

A sample Wireit configuration defining a 'build' script with command, dependencies, files, output, and clean options.

```json
{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc",
      "dependencies": ["lint"],
      "files": ["src/**/*.ts"],
      "output": ["lib/**"],
      "clean": true
    }
  }
}
```

--------------------------------

### DependencyOnMissingScript Example

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Shows an example error message for DependencyOnMissingScript, indicating a specified script was not found in a dependent package.

```text
❌ package.json:8:5 — Script "nonexistent" not found in ./components
```

--------------------------------

### LocalCache Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cache.md

Demonstrates how to use the LocalCache to get cached script outputs or set new ones if a cache miss occurs. Ensure the 'script' and 'fingerprint' variables are defined before use.

```typescript
import {LocalCache} from './caching/local-cache.js'
import {Fingerprint} from './fingerprint.js'

const cache = new LocalCache()

// Check cache
const hit = await cache.get(script, fingerprint)
if (hit) {
  console.log('Cache hit!')
  await hit.apply()
} else {
  console.log('Cache miss, running script...')
  // ... run script and capture output
  
  // Save output
  const files = [
    {absolute: '/path/to/lib/index.js', relative: 'lib/index.js'},
    {absolute: '/path/to/lib/index.d.ts', relative: 'lib/index.d.ts'},
  ]
  await cache.set(script, fingerprint, files)
}
```

--------------------------------

### Wireit Configuration Example

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

This JSON object demonstrates a typical Wireit configuration within a package.json file, defining scripts, commands, dependencies, and file watching.

```json
{
  "scripts": {
    "build": "wireit",
    "test": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc",
      "dependencies": ["lint"],
      "files": ["src/**/*.ts", "tsconfig.json"],
      "output": ["lib/**"],
      "clean": true
    },
    "test": {
      "command": "jest",
      "dependencies": ["build"],
      "files": ["test/**/*.ts", "lib/**"],
      "env": {"NODE_ENV": "test"}
    },
    "lint": {
      "command": "eslint src",
      "files": ["src/**/*.ts", ".eslintrc.json"]
    }
  }
}
```

--------------------------------

### QuietLogger Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/logger.md

Shows how to create an instance of QuietLogger. It requires the package root and a Console object.

```typescript
const logger = new QuietLogger(process.cwd(), console)
```

--------------------------------

### Example Output for MissingPackageJson Error

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Illustrates the message when Wireit cannot find a package.json file.

```text
❌ /some/path — package.json not found
```

--------------------------------

### Instantiate QuietCiLogger

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/logger.md

Example of how to instantiate the QuietCiLogger. This logger is automatically selected in CI environments.

```typescript
const logger = new QuietCiLogger(process.cwd(), console)
```

--------------------------------

### Change Script to Wireit Example

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Shows how to fix a ScriptNotWireit error by changing the script command to 'wireit' in package.json.

```json
{
  "scripts": {
    "build": "wireit"
  }
}
```

--------------------------------

### Instantiate MetricsLogger

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/logger.md

Example of how to instantiate the MetricsLogger. This logger is used to track performance metrics.

```typescript
const logger = new MetricsLogger(process.cwd(), console)
```

--------------------------------

### CombinationLogger Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/logger.md

Demonstrates how to instantiate and use CombinationLogger to combine multiple loggers for dual-logging purposes.

```typescript
const mainLogger = new QuietLogger(pkg, console)
const debugLogger = new DebugLogger(pkg, debugConsole)
const combined = new CombinationLogger(
  [mainLogger, debugLogger],
  console
)
```

--------------------------------

### InvalidUsage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Shows an example of an InvalidUsage error message, specifically related to an incorrect value for the WIREIT_PARALLEL environment variable.

```text
❌ — Expected WIREIT_PARALLEL to be a positive integer, got "abc"
```

--------------------------------

### Wireit Example Error Object

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cli.md

An example of an error object returned by getOptions() for invalid usage scenarios.

```typescript
{
  ok: false,
  error: {
    type: 'failure',
    reason: 'invalid-usage',
    message: 'Expected WIREIT_PARALLEL to be a positive integer, got "abc"',
    script: {packageDir, name: 'build'},
  }
}
```

--------------------------------

### Compute Fingerprint Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/fingerprint.md

Demonstrates how to use the static `Fingerprint.get` method to compute a script's fingerprint and handle success or failure.

```typescript
const fingerprint = await Fingerprint.get(scriptConfig)
if (fingerprint.ok) {
  console.log('Fingerprint:', fingerprint.value.hash)
} else {
  console.error('Failed to compute fingerprint:', fingerprint.error)
}
```

--------------------------------

### DependencyOnMissingPackageJson Example

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Illustrates an error message for DependencyOnMissingPackageJson, showing a dependency pointing to a non-existent package path.

```text
❌ package.json:8:5 — Dependency refers to missing package at ./missing
```

--------------------------------

### Instantiate DebugLogger

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/logger.md

Example of how to instantiate the DebugLogger. This logger is enabled by setting the WIREIT_DEBUG_LOG_FILE environment variable.

```typescript
const debugStream = await fs.createWriteStream(
  '/tmp/wireit-debug.log'
)
const debugConsole = new Console(debugStream, debugStream, true)
const logger = new DebugLogger(process.cwd(), debugConsole)
```

--------------------------------

### Monorepo Configuration Example

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

This JSON snippet shows how to configure Wireit for a monorepo using npm workspaces. It defines build dependencies across packages.

```json
{
  "workspaces": ["packages/*"],
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "dependencies": ["./packages/*:build"]
    }
  }
}
```

--------------------------------

### ArrayNode Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/config.md

An example illustrating the structure of an ArrayNode, showing its value, offset, length, and individual elements with their locations.

```typescript
{
  value: ['src/**/*.ts', 'tsconfig.json'],
  offset: 100,
  length: 45,
  elements: [
    {value: 'src/**/*.ts', offset: 101, length: 12},
    {value: 'tsconfig.json', offset: 114, length: 16},
  ]
}
```

--------------------------------

### Wireit Logger Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/logger.md

Demonstrates how to import logger options, log various event types, print metrics, and clean up logger resources using the Disposable interface.

```typescript
import {getOptions} from './cli-options.js'

const optionsResult = await getOptions()
const {logger} = optionsResult.value

// Log events
logger.log({
  type: 'success',
  reason: 'exit-zero',
  script: {packageDir: '/path', name: 'build'},
})

// Print metrics
logger.printMetrics()

// Clean up
using _ = logger // Calls [Symbol.dispose]()
```

--------------------------------

### Add Script to Scripts Section Example

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Provides an example of how to fix a WireitScriptNotInScriptsSection error by adding the script to the 'scripts' section in package.json.

```json
{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {}
  }
}
```

--------------------------------

### UnknownErrorThrown Example

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Provides an example of an UnknownErrorThrown error message, indicating an unexpected runtime error during script execution.

```text
❌ mypackage:build — Unexpected error: Cannot read property 'x' of undefined
```

--------------------------------

### Use GitHub Cache for Build

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

Runs the build script using the GitHub Actions cache. This example demonstrates how to override the default local cache.

```bash
WIREIT_CACHE=github npm run build
```

--------------------------------

### Executor Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/executor.md

Demonstrates how to instantiate and use the Executor to execute scripts. Handles potential errors and prepares for persistent services.

```typescript
import {Executor} from './executor.js'
import {WorkerPool} from './util/worker-pool.js'
import {LocalCache} from './caching/local-cache.js'

const executor = new Executor(
  config,
  logger,
  new WorkerPool(4),
  new LocalCache(),
  'no-new',
  undefined,
  false
)

const {persistentServices, errors} = await executor.execute()

if (errors.length > 0) {
  console.error('Execution failed:', errors)
  process.exit(1)
}

// Wait for persistent services in watch mode, etc.
```

--------------------------------

### Analyzer Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/analyzer.md

Demonstrates how to instantiate and use the Analyzer to analyze a script. Handles both successful analysis and failure cases.

```typescript
import {Analyzer} from './analyzer.js'
import {SimpleLogger} from './logging/simple-logger.js'
import {Console} from './logging/logger.js'

const analyzer = new Analyzer('npm', logger)
const result = await analyzer.analyze(
  {packageDir: '/path/to/pkg', name: 'build'},
  undefined
)

if (result.config.ok) {
  console.log('Script config:', result.config.value)
} else {
  console.error('Analysis failures:', result.config.error)
}
```

--------------------------------

### Example Output for ExitNonZero Error

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Illustrates the user-facing message when a script fails due to a non-zero exit code.

```text
❌ mypackage:build — script exited with status code 1
```

--------------------------------

### Example Output for StartCancelled Error

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Illustrates the message shown when a script is cancelled due to an upstream failure.

```text
❌ mypackage:test — not started (dependency failed)
```

--------------------------------

### QuietLogger getWatchLogger Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/logger.md

Provides an example implementation of the getWatchLogger method for QuietLogger. This resets state between iterations while maintaining the logger type.

```typescript
getWatchLogger(): Logger {
  return new QuietLogger(this.#packageRoot, this.#console)
}
```

--------------------------------

### Example Output for NoScriptsSectionInPackageJson Error

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Illustrates the message when a package.json file does not contain a 'scripts' section.

```text
❌ mypackage — No "scripts" section in package.json
```

--------------------------------

### Example Output for Killed Error

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Illustrates the message when Wireit kills a running script.

```text
❌ mypackage:build — killed by wireit
```

--------------------------------

### InvalidConfigSyntax Example

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Illustrates an InvalidConfigSyntax error message, showing a specific validation failure related to the 'files' property.

```text
❌ package.json:10:20 — "files" must be an array, got string
```

--------------------------------

### Initialize and Run Watcher

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/watcher.md

Instantiates a Watcher with specified options and starts the watch process. Handles SIGINT signal to abort the watcher gracefully.

```typescript
import {Watcher} from './watcher.js'
import {LocalCache} from './caching/local-cache.js'
import {QuietLogger} from './logging/quiet-logger.js'

const watcher = new Watcher(
  {packageDir: '/path', name: 'build'},
  undefined,
  logger,
  new WorkerPool(4),
  new LocalCache(),
  'no-new',
  'npm',
  {strategy: 'event'}
)

process.on('SIGINT', () => {
  watcher.abort()
})

await watcher.watch()
console.log('Watch ended')
```

--------------------------------

### GitHubActionsCache Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cache.md

Demonstrates how to create and use the GitHubActionsCache, including handling potential errors during initialization and falling back to no caching if the cache is unavailable.

```typescript
const result = await GitHubActionsCache.create(logger)
if (!result.ok) {
  console.error('GitHub cache unavailable:', result.error)
  // Fall back to no caching
} else {
  const cache = result.value
  const hit = await cache.get(script, fingerprint)
  // ... use cache
}
```

--------------------------------

### Example Output for LaunchedIncorrectly Error

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Shows the user-facing message when Wireit is launched incorrectly, advising on the correct usage.

```text
❌ /path/to/package — Launching Wireit with npx is not supported. Use: npm run <script> or yarn <script>
```

--------------------------------

### Cycle Example

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Illustrates an error message for a detected circular dependency, showing the sequence of scripts involved in the cycle.

```text
❌ package.json:8:5 — Circular dependency: build → lint → build
```

--------------------------------

### Example Output for PackageJsonParseError

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Shows the user-facing message when package.json has invalid JSON syntax, including the location of the error.

```text
❌ package.json:5:12 — Unexpected token }
```

--------------------------------

### LocalCache Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cache.md

Demonstrates how to use the LocalCache to retrieve a cached result or store new output if no cache hit occurs.

```typescript
const cache = new LocalCache()
const hit = await cache.get(script, fingerprint)
if (hit) {
  await hit.apply()
} else {
  // Run script and save output
  await cache.set(script, fingerprint, outputFiles)
}
```

--------------------------------

### Deferred Promise Wrapper Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/utilities.md

Shows how to use the Deferred class to create a Promise that can be resolved or rejected externally. Import Deferred from 'wireit/deferred'.

```typescript
import { Deferred } from 'wireit/deferred';

const deferred = new Deferred<string>()

setTimeout(() => {
  deferred.resolve('done')
}, 1000)

const result = await deferred.promise
// result === 'done'
```

--------------------------------

### LineMonitor Stream Monitoring Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/utilities.md

Demonstrates capturing output line-by-line from a stream using LineMonitor. Import LineMonitor from 'wireit/line-monitor'. The callback is invoked for each line received.

```typescript
import { LineMonitor } from 'wireit/line-monitor';

const monitor = new LineMonitor(process.stdout)
monitor.onLine(line => {
  if (line.includes('listening')) {
    console.log('Server ready!')
  }
})
```

--------------------------------

### Disposable Interface Implementation

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/logger.md

An example implementation of the Disposable interface, demonstrating how to end a stream when the logger is no longer needed.

```typescript
[Symbol.dispose](): void {
  this.#stream.end()
}
```

--------------------------------

### Example Usage of Result Type

Source: https://github.com/google/wireit/blob/main/_autodocs/types.md

Demonstrates how to handle the Result type to check for success or failure and access the corresponding value or error.

```typescript
const result = await analyze()
if (result.ok) {
  console.log('Success:', result.value)
} else {
  console.log('Error:', result.error)
}
```

--------------------------------

### AsyncCache Usage Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/utilities.md

Demonstrates how to use AsyncCache to ensure a computation is only performed once, even with concurrent requests for the same key. Import AsyncCache from 'wireit/async-cache'.

```typescript
import { AsyncCache } from 'wireit/async-cache';

const cache = new AsyncCache<string, Config>()
const config1 = await cache.get('pkg1', async () => {
  return loadConfig('pkg1')
})
const config2 = await cache.get('pkg1', async () => {
  return loadConfig('pkg1')
})
// compute only called once
```

--------------------------------

### Full Fingerprint Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/fingerprint.md

Illustrates the complete structure of a fingerprint object, including platform details, command, file hashes, and dependencies. This is used to uniquely identify the state of a script and its inputs.

```typescript
{
  __FingerprintDataBrand__: [never],
  fullyTracked: true,
  platform: 'linux',
  arch: 'x64',
  nodeVersion: '18.12.0',
  command: 'tsc',
  extraArgs: [],
  clean: true,
  files: {
    'src/index.ts': 'abc123def456...',
    'tsconfig.json': 'ghi789jkl012...',
  },
  output: ['lib/**'],
  dependencies: {
    '/path/to/lint': 'mno345pqr678...',
  },
  service: undefined,
  env: {NODE_ENV: 'production'},
}
```

--------------------------------

### Get Wireit CLI Options

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cli.md

Parses all CLI options from environment variables and command-line arguments. This function is essential for initializing Wireit's execution context.

```typescript
export const getOptions = async (): Promise<Result<Options>>
```

--------------------------------

### Options

Source: https://github.com/google/wireit/blob/main/_autodocs/types.md

All CLI options parsed from environment and arguments.

```APIDOC
## Interface: Options

### Description
Represents all CLI options parsed from environment and arguments.

### Properties
* `script: ScriptReference` - The script to execute.
* `watch: false | {strategy: 'event'} | {strategy: 'poll'; interval: number}` - Watch mode configuration.
* `extraArgs: string[] | undefined` - Additional arguments to pass to the script.
* `numWorkers: number` - The number of worker threads to use.
* `cache: 'local' | 'github' | 'none'` - The cache strategy to use.
* `failureMode: FailureMode` - The failure mode for the script.
* `agent: Agent` - The NPM user agent.
* `logger: Logger` - The logger implementation.
```

--------------------------------

### Example of ServiceExitedUnexpectedly Error Message

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Illustrates a typical error message when a service exits unexpectedly. This message format helps users quickly identify the failing package and the nature of the error.

```text
❌ mypackage:server — Service exited unexpectedly with code 1
```

--------------------------------

### Wireit Architecture Overview

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

Illustrates the flow of execution within Wireit, from the CLI entry point through option parsing, analysis, execution, caching, logging, and parallel task processing.

```text
CLI Entry (bin/wireit.js)
  ↓
getOptions() - Parse env vars and args
  ↓
Analyzer - Load and validate package.json
  ↓
Executor or Watcher
  ├─ StandardScriptExecution
  ├─ ServiceScriptExecution
  └─ NoCommandScriptExecution
  ↓
Cache (LocalCache or GitHubActionsCache)
  ↓
Logger (SimpleLogger, QuietLogger, etc.)
  ↓
WorkerPool - Parallel execution
```

--------------------------------

### Fingerprint Get Method Signature

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/fingerprint.md

Declares the signature for the static `get` method, which computes the fingerprint for a given script configuration.

```typescript
static get(script: ScriptConfig): Promise<Result<Fingerprint>>
```

--------------------------------

### Cache Interface get() Method Signature

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cache.md

The signature for the get() method, used to check for a cache hit based on script reference and fingerprint.

```typescript
get(
  script: ScriptReference,
  fingerprint: Fingerprint
): Promise<CacheHit | undefined>
```

--------------------------------

### Run Build with Simple Logger

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

Executes the build script using the 'simple' logger, which outputs all details. This is an alternative to the auto-detected logger.

```bash
WIREIT_LOGGER=simple npm run build
```

--------------------------------

### Run Wireit Tests

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

Execute the project's test suite using npm commands. Available commands include `npm test` for the full suite, `npm run test:basic` for basic tests, `npm run test:watch` for watch mode testing, and `npm run test:cache-local` for local cache testing.

```bash
npm test
npm run test:basic
npm run test:watch
npm run test:cache-local
```

--------------------------------

### Define Service Readiness with Line Matching

Source: https://github.com/google/wireit/blob/main/README.md

Use 'service.readyWhen.lineMatches' to specify a regular expression. Wireit will monitor the service's output and consider it ready only after a matching line is found.

```json
{
  "command": "node my-server.js",
  "service": {
    "readyWhen": {
      "lineMatches": "Server listening on port \d+"
    }
  }
}
```

--------------------------------

### Example Output for ExitSignal Error

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Shows the user-facing message when a script is killed by a signal.

```text
❌ mypackage:build — killed by SIGTERM
```

--------------------------------

### getOptions()

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cli.md

Parses all CLI options from environment variables and command-line arguments. It detects the package.json location, identifies the script name, parses configuration from environment variables, detects the npm user agent, and instantiates the appropriate logger.

```APIDOC
## getOptions()

### Description
Parses all CLI options from environment variables and command-line arguments.

### Method
`async`

### Parameters
This function does not take any direct parameters. It reads configuration from environment variables and command-line arguments.

### Returns
`Promise<Options>`

```typescript
interface Options {
  script: ScriptReference
  watch: false | {strategy: 'event'} | {strategy: 'poll'; interval: number}
  extraArgs: string[] | undefined
  numWorkers: number
  cache: 'local' | 'github' | 'none'
  failureMode: FailureMode
  agent: Agent
  logger: Logger
}
```

### Environment Variables Parsed:

| Variable | Type | Values | Default |
|----------|------|--------|---------|
| `npm_lifecycle_event` | string | Script name | (required) |
| `NODE_RUN_SCRIPT_NAME` | string | Script name (node --run) | — |
| `npm_package_json` | string | package.json path | Uses env or walk |
| `NODE_RUN_PACKAGE_JSON_PATH` | string | package.json path | — |
| `WIREIT_PARALLEL` | string | number or "infinity" | os.cpus().length × 2 |
| `WIREIT_CACHE` | string | "local", "github", "none" | Auto (CI safe) |
| `WIREIT_FAILURES` | string | "no-new", "continue", "kill" | "no-new" |
| `WIREIT_LOGGER` | string | "quiet", "quiet-ci", "simple", "metrics" | Auto-detect |
| `WIREIT_DEBUG_LOG_FILE` | string | File path | (optional) |
| `WIREIT_WATCH` | string | "true" or "false" | false |
| `WIREIT_WATCH_STRATEGY` | string | "event" or "poll" | "event" |
| `WIREIT_WATCH_POLL_MS` | string | Milliseconds | 500 |
| `npm_config_user_agent` | string | npm/yarn/pnpm id | (for detection) |
| `CI` | string | "true" | (auto-detect env) |

### Behavior:
1. Detects package.json location from environment or filesystem walk
2. Identifies script name from `npm_lifecycle_event` or `NODE_RUN_SCRIPT_NAME`
3. Parses environment variables for configuration
4. Detects npm user agent (npm, yarn, pnpm, node --run)
5. Instantiates appropriate logger
6. Returns all options or error
```

--------------------------------

### Use Services for Server Tasks

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

Configure tasks as services for long-running processes like servers. Use 'readyWhen' to define conditions under which the service is considered ready, such as matching specific output.

```json
"service": {
  "readyWhen": {"lineMatches": "listening"}
}
```

--------------------------------

### Profile Execution with Metrics Logger

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

Enable the metrics logger to profile Wireit build performance and identify bottlenecks.

```bash
WIREIT_LOGGER=metrics npm run build
```

--------------------------------

### Wireit Configuration in package.json

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

Defines a 'build' script using Wireit, specifying command, dependencies, files, output, cleaning behavior, service readiness, and environment variables.

```json
{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc",
      "dependencies": ["./other-package:build"],
      "files": ["src/**/*.ts", "tsconfig.json"],
      "output": ["lib/**"],
      "clean": true,
      "service": {
        "readyWhen": {
          "lineMatches": "Server listening"
        }
      },
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

--------------------------------

### Wireit dependencies option

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

Lists scripts that must complete before the current script can run. Supports same-package, workspace, and relative-path dependencies.

```json
"dependencies": [
  "./other-package:build",
  "lint",
  "../tools:generate"
]
```

```json
"dependencies": [
  "lint",
  "prettier:check",
  "../api:build",
  "./components:build"
]
```

--------------------------------

### Declare Build and Bundle Dependencies

Source: https://github.com/google/wireit/blob/main/README.md

Configure 'build' and 'bundle' scripts, with 'bundle' depending on 'build'. When 'npm run bundle' is executed, 'build' will run first.

```json
{
  "scripts": {
    "build": "wireit",
    "bundle": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc"
    },
    "bundle": {
      "command": "rollup -c",
      "dependencies": ["build"]
    }
  }
}
```

--------------------------------

### Enable Debug Logging to File

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

Runs the build script and directs detailed debug logs to a file named 'debug.log'. This captures all Wireit events for later analysis.

```bash
WIREIT_DEBUG_LOG_FILE=debug.log npm run build
```

--------------------------------

### Fingerprint Class Definition

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/fingerprint.md

Defines the Fingerprint class structure, including its hash and data properties, and the static `get` method.

```typescript
export class Fingerprint {
  readonly hash: FingerprintString
  readonly data: FingerprintData
  
  static get(script: ScriptConfig): Promise<Result<Fingerprint>>
}
```

--------------------------------

### Set Parallelism Level

Source: https://github.com/google/wireit/blob/main/README.md

Set the WIREIT_PARALLEL environment variable to control the number of scripts that can run concurrently. This example sets it to 1.

```sh
export WIREIT_PARALLEL=1
npm run build
```

--------------------------------

### Example Output for FailedPreviousWatchIteration Error

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Shows the user-facing message when a script is skipped in watch mode because it previously failed and its inputs are unchanged.

```text
❌ mypackage:build — skipped (previously failed, unchanged)
```

--------------------------------

### Configure npm script for Wireit

Source: https://github.com/google/wireit/blob/main/README.md

Convert an existing npm script to use Wireit by moving the command to the 'wireit' section in package.json.

```json
{
  "scripts": {
    "build": "tsc"
  }
}
```

```json
{
  "scripts": {
    "build": "wireit"
  },
  "wireit": {
    "build": {
      "command": "tsc"
    }
  }
}
```

--------------------------------

### Define Inputs and Outputs for Caching

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

Specify input files and expected output directories to enable Wireit's caching mechanism. This ensures tasks only rerun when their inputs change.

```json
"files": ["src/**"],
"output": ["lib/**"]
```

--------------------------------

### Run Wireit with Local Cache

Source: https://github.com/google/wireit/blob/main/_autodocs/README.md

Enables local caching for Wireit builds by setting the WIREIT_CACHE environment variable.

```bash
WIREIT_CACHE=local npm run build
```

--------------------------------

### Wireit CLI Main Execution Flow

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cli.md

This snippet demonstrates the main execution flow of the Wireit CLI. It shows how to parse options, analyze the script configuration, and execute the script using an executor.

```typescript
import {getOptions} from './cli-options.js'
import {Analyzer} from './analyzer.js'
import {Executor} from './executor.js'

const optionsResult = await getOptions()
if (!optionsResult.ok) {
  console.error('Failed to get options:', optionsResult.error)
  process.exit(1)
}

const {script, logger, cache, failureMode, numWorkers} = optionsResult.value

const analyzer = new Analyzer('npm', logger)
const result = await analyzer.analyze(script, undefined)

if (!result.config.ok) {
  for (const failure of result.config.error) {
    logger.log(failure)
  }
  process.exit(1)
}

const executor = new Executor(
  result.config.value,
  logger,
  new WorkerPool(numWorkers),
  cache,
  failureMode,
  undefined,
  false
)

const {errors} = await executor.execute()
process.exit(errors.length > 0 ? 1 : 0)
```

--------------------------------

### Wireit Architecture Diagram

Source: https://github.com/google/wireit/blob/main/_autodocs/README.md

Illustrates the flow of execution within Wireit, from CLI entry to script execution, caching, and logging. It highlights the differences between standard and watch modes.

```text
CLI Entry (bin/wireit.js)
    ↓
getOptions() - Parse environment and arguments
    ↓
Analyzer - Load package.json, resolve dependencies
    ↓
┌─────────────────────────────────────┐
│ Standard Mode    │    Watch Mode    │
├──────────────────┼──────────────────┤
│ Executor.execute │   Watcher.watch  │
│ - Run once       │   - Monitor files │
│ - Sequential     │   - Debounce      │
└──────────────────┼──────────────────┘
    ↓
WorkerPool - Run scripts with parallelism
    ↓
StandardScriptExecution / ServiceScriptExecution / NoCommandScriptExecution
    ↓
Fingerprint - Check if script needs to run
    ↓
Cache - Restore output if available
    ↓
Logger - Display results
    ↓
Exit (code 0 or 1)
```

--------------------------------

### Get Script Data Directory

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/utilities.md

Retrieves the data directory for a script, typically used for caching and state management within Wireit.

```typescript
export function getScriptDataDir(script: ScriptReference): string
```

--------------------------------

### Run Wireit with Parallel Execution

Source: https://github.com/google/wireit/blob/main/_autodocs/README.md

Configures Wireit to run up to 8 builds in parallel by setting the WIREIT_PARALLEL environment variable.

```bash
WIREIT_PARALLEL=8 npm run build
```

--------------------------------

### Enable Wireit Watch Mode

Source: https://github.com/google/wireit/blob/main/README.md

To enable watch mode, ensure the 'files' array is defined and run npm scripts with the WIREIT_WATCH=true environment variable.

```sh
WIREIT_WATCH=true npm run <script>
```

--------------------------------

### Constructing a Cache Key with Fingerprint

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/fingerprint.md

Demonstrates how to use a script's fingerprint to construct a cache key. This is useful for invalidating and retrieving cached build artifacts.

```typescript
const fingerprint = await Fingerprint.get(script)
if (fingerprint.ok) {
  // Use as cache key
  const cacheKey = `${script.name}/${fingerprint.value.hash}`
  const cached = await cache.get(script, fingerprint.value)
}
```

--------------------------------

### Validate and Extract Wireit Config from Package.json

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/utilities.md

Use `isValidPackageJson` to check if an object conforms to the PackageJson interface and `extractWireitConfig` to get the Wireit configuration section.

```typescript
export function isValidPackageJson(obj: unknown): obj is PackageJson
export function extractWireitConfig(packageJson: PackageJson): WireitSection
```

```typescript
if (isValidPackageJson(obj)) {
  const wireitConfig = extractWireitConfig(obj)
}
```

--------------------------------

### TypeScript Interface for StartCancelled Error

Source: https://github.com/google/wireit/blob/main/_autodocs/errors.md

Defines the structure for an error when a script is not started because another script failed. This error is only emitted under specific failure modes.

```typescript
interface StartCancelled extends ErrorBase {
  reason: 'start-cancelled'
}
```

--------------------------------

### Use Globs for Flexible File Matching

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

Employ glob patterns for file inputs to easily include multiple files or directories that match a pattern. This enhances flexibility when dealing with evolving project structures.

```json
"files": ["src/**/*.ts", "tsconfig.json"]
```

--------------------------------

### Configure Debug Output and Logger

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

Enable debug logging by specifying a file path with WIREIT_DEBUG_LOG_FILE, or set the logger type using WIREIT_LOGGER.

```bash
WIREIT_DEBUG_LOG_FILE=debug.log npm run build
```

```bash
WIREIT_LOGGER=simple npm run build
```

--------------------------------

### Control Cache Backend with WIREIT_CACHE

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

Use the WIREIT_CACHE environment variable to specify the cache backend. Supported values include 'github', 'local', and 'none'.

```bash
WIREIT_CACHE=github npm run build
```

```bash
WIREIT_CACHE=none npm run build
```

--------------------------------

### WorkerPool Task Execution Example

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/utilities.md

Illustrates parallel task execution using WorkerPool with a concurrency limit. Import WorkerPool from 'wireit/worker-pool'. Ensure to call pool.dispose() when done.

```typescript
import { WorkerPool } from 'wireit/worker-pool';

const pool = new WorkerPool(4)
for (const item of items) {
  pool.run(async () => {
    await processItem(item)
  })
}
await pool.dispose()
```

--------------------------------

### Disable Cascade for Server Assets

Source: https://github.com/google/wireit/blob/main/README.md

Disables cascade for server assets in the 'start' script. This prevents server restarts when static assets change, as the server reads them dynamically.

```json
{
  "scripts": {
    "start": "wireit",
    "build:server": "wireit"
  },
  "wireit": {
    "start": {
      "command": "node lib/server.js",
      "service": true,
      "dependencies": [
        "build:server",
        {
          "script": "../assets:build",
          "cascade": false
        }
      ],
      "files": ["lib/**/*.js"]
    },
    "build:server": {
      "command": "tsc",
      "files": ["src/**/*.ts", "tsconfig.json"],
      "output": ["lib/**"]
    }
  }
}
```

--------------------------------

### Executor abort() Method

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/executor.md

Immediately aborts the ongoing script execution. This stops new scripts from starting, kills currently running scripts, and halts any active services.

```typescript
abort(): void
```

```typescript
executor.abort()
```

--------------------------------

### Troubleshoot Slow Execution with Parallelism

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

Check and adjust parallelism settings to diagnose and resolve slow execution issues in Wireit builds.

```bash
WIREIT_PARALLEL=1 npm run build
```

--------------------------------

### Run a Script with npm

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

This snippet shows the basic command to run a script defined in your package.json using npm.

```bash
npm run build
```

--------------------------------

### Set Wireit Failures to Kill Mode

Source: https://github.com/google/wireit/blob/main/README.md

Use this setting to immediately kill running scripts and prevent new ones from starting upon encountering a failure, enabling prompt notification.

```bash
WIREIT_FAILURES=kill
```

--------------------------------

### Fingerprint Interface

Source: https://github.com/google/wireit/blob/main/_autodocs/types.md

Represents a script's fingerprint, used for caching and freshness detection. It includes a hash and associated data. The static `get` method computes the fingerprint for a given script configuration.

```typescript
export interface Fingerprint {
  hash: FingerprintString
  data: FingerprintData
  static get(script: ScriptConfig): Promise<Result<Fingerprint>>
}
```

--------------------------------

### Define Custom Cache Interface

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

Implement the `Cache` interface for custom caching strategies. The interface requires `get` and `set` methods for retrieving and storing cached script execution results based on script references and fingerprints.

```typescript
export interface Cache {
  get(script: ScriptReference, fingerprint: Fingerprint): Promise<CacheHit | undefined>
  set(script: ScriptReference, fingerprint: Fingerprint, files: AbsoluteEntry[]): Promise<boolean>
}
```

--------------------------------

### Cache Key Structure

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/cache.md

Illustrates the components used to construct a cache key for Wireit. This includes package directory, script name, and a fingerprint hash derived from various inputs.

```plaintext
${packageDir}/${scriptName}/${fingerprintHash}
```

--------------------------------

### Run Wireit Tests

Source: https://github.com/google/wireit/blob/main/CONTRIBUTING.md

Execute the test suite for Wireit. Use 'npm test watch' to run tests in watch mode during development.

```sh
npm test
```

```sh
npm test watch
```

--------------------------------

### Define Input Files for Caching

Source: https://github.com/google/wireit/blob/main/_autodocs/index.md

Specify input files to enable caching for tasks. This is crucial for performance optimization.

```json
"files": ["src/**/*.ts"]
```

--------------------------------

### Wireit Project File Structure

Source: https://github.com/google/wireit/blob/main/_autodocs/README.md

This snippet displays the directory structure of the Wireit project, indicating the location of various documentation files and API reference modules.

```text
output/
├── README.md                      (this file)
├── index.md                       (complete index)
├── overview.md                    (architecture & concepts)
├── configuration.md               (config & env vars)
├── errors.md                      (error reference)
├── types.md                       (type definitions)
└── api-reference/
    ├── cli.md
    ├── analyzer.md
    ├── executor.md
    ├── watcher.md
    ├── cache.md
    ├── logger.md
    ├── fingerprint.md
    ├── config.md
    ├── worker-pool.md
    └── utilities.md
```

--------------------------------

### Run Build with Polling Watch Strategy

Source: https://github.com/google/wireit/blob/main/_autodocs/configuration.md

Executes the build script using the polling strategy for file watching. This is combined with the --watch flag to ensure changes are detected reliably.

```bash
WIREIT_WATCH_STRATEGY=poll npm run build --watch
```

--------------------------------

### Basic Worker Pool Usage

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/worker-pool.md

Demonstrates the fundamental pattern for creating a WorkerPool, running asynchronous tasks, and disposing of the pool when done.

```typescript
const pool = new WorkerPool(4)

for (const script of scripts) {
  pool.run(async () => {
    await executeScript(script)
  })
}

await pool.dispose()
```

--------------------------------

### File Operation Pattern

Source: https://github.com/google/wireit/blob/main/_autodocs/api-reference/utilities.md

Demonstrates a common pattern for reading files within a package directory using glob patterns and asynchronous file system operations.

```typescript
import * as fs from './util/fs.js'
import {glob} from './util/glob.js'

const files = await glob(['src/**/*.ts'], {cwd: packageDir})
for (const file of files) {
  const contents = await fs.readFile(file.absolute)
  // Process...
}
```

--------------------------------

### Configure Wireit for ESLint Linting

Source: https://github.com/google/wireit/blob/main/README.md

This snippet configures Wireit to run ESLint with caching and colorized output. It includes configuration and ignore files in the watched files to ensure ESLint re-runs when configurations change.

```json
{
  "scripts": {
    "lint": "wireit"
  },
  "wireit": {
    "lint": {
      "command": "eslint --color --cache --cache-location .eslintcache .",
      "files": ["src/**/*.ts", ".eslintignore", ".eslintrc.cjs"],
      "output": []
    }
  }
}
```

--------------------------------

### Run Wireit in Watch Mode

Source: https://github.com/google/wireit/blob/main/_autodocs/README.md

Activates watch mode for Wireit builds, automatically recompiling on file changes.

```bash
npm run build --watch
```

--------------------------------

### General Argument Passing in npm Scripts

Source: https://github.com/google/wireit/blob/main/README.md

This illustrates the general pattern for passing arguments to npm scripts when using Wireit, distinguishing between npm arguments and script arguments.

```sh
npm run {script} {npm args} {wireit args} -- {script args}
```