# v0.4.16 — Toolchain & Bootstrap

v0.4.16 makes the Harness distributable as a normal npm development tool while provisioning its external engineering toolchain explicitly and reproducibly.

## Distribution boundary

The Harness itself is an npm package and CLI. It is not an application runtime dependency and it does not use npm `postinstall` to mutate the host.

Recommended project installation:

```bash
npm install --save-dev agentic-engineering-harness
npm exec aeh -- init --setup
```

For a repository that already declares the Harness but has no local `node_modules`, use a pinned temporary bootstrap invocation and let `aeh setup` install the project dependencies afterwards:

```bash
npm exec --yes --package=agentic-engineering-harness@0.4.16 -- aeh setup
```

## Explicit provisioning

`aeh setup` is the host/toolchain mutation boundary. It:

1. loads `.harness/toolchain.yaml`;
2. inspects active Harness runtimes, orchestration, validators and project stack;
3. computes the minimum required tool closure;
4. reuses `.harness/toolchain.lock.json` when it exists;
5. provisions missing managed tools through mise;
6. optionally provisions heavy validators as immutable OCI images;
7. installs detected project dependencies from lockfiles;
8. writes machine-local `.harness/toolchain.state.json`;
9. makes the provisioned bin paths visible to all subsequent Harness subprocesses;
10. leaves verification to `aeh doctor`.

There is no requirement to run `mise activate` in the user's interactive shell.

## Source, lock and machine state

```text
.harness/toolchain.yaml
        |
        | desired tool constraints/capabilities
        v
AEH resolver
        |
        +--> .config/mise/conf.d/aeh.toml
        |       generated mise layer
        |
        +--> .harness/toolchain.lock.json
        |       exact logical versions + OCI digests
        |
        `--> .harness/toolchain.state.json
                machine-local bin paths; gitignored
```

`toolchain.yaml` is authoritative source configuration. `toolchain.lock.json` should normally be committed after the first successful setup. `toolchain.state.json` must not be committed because it contains machine-local paths.

When a lock exists, setup uses its exact resolved versions unless `--update-lock` is requested.

## Automatic capability resolution

Default auto mode selects tools only when they are needed.

Examples:

```text
runtime:codex              -> codex
runtime:opencode           -> opencode
orchestration:paseo        -> paseo
code-intelligence:graphify -> uv + graphify
validation:opa             -> opa
security-tool:opengrep     -> opengrep
validator:trivy            -> trivy
project:bun                -> bun
project:dotnet             -> dotnet
```

The resolver also recognizes Node/package-manager files, Python/uv, .NET project files/global.json, Go modules and Cargo projects as capability evidence. The default pack currently provisions the common Harness/Pawra requirements; project overlays can add additional language tools without changing AEH core.

## Project-pinned versions

Before creating a new lock, AEH respects existing project version authority where supported:

- `.node-version` / `.nvmrc` override the default Node version;
- `global.json` pins the .NET SDK;
- `packageManager: bun@...` pins Bun;
- projects may directly override any default tool definition in `.harness/toolchain.yaml`.

A first setup may resolve `latest` declarations; after it succeeds the AEH lock becomes the reproducible resolved environment. `aeh setup --update-lock` is the explicit upgrade operation.

## Mise backend

Mise is the default provisioning adapter because it can install tools from multiple ecosystems without making those tools npm dependencies of AEH. Where the mise registry provides an Aqua mapping, the default pack prefers Aqua over raw GitHub release autodetection.

The default pack uses:

```text
node                       core mise backend
bun                        core mise backend
dotnet                     core mise backend
npm:@openai/codex          Codex
npm:@getpaseo/cli          Paseo
aqua:anomalyco/opencode    OpenCode
aqua:open-policy-agent/opa
aqua:opengrep/opengrep
aqua:aquasecurity/trivy
uv
pipx:graphifyy             Graphify CLI
```

AEH first tries an existing `mise` executable. If it is absent, explicit setup bootstraps the configured minimum mise release through a pinned npm invocation equivalent to:

```bash
npm exec --yes --package=mise@2026.7.0 -- mise --version
```

This is an explicit setup action rather than an npm installation side effect. The version is taken from `manager.minimumVersion`, not hard-coded in setup logic.

## OCI validator strategy

The toolchain supports:

```yaml
strategy:
  validators: local
  containerEngine: podman
```

or:

```yaml
strategy:
  validators: prefer-container
  containerEngine: podman
```

If `prefer-container` is selected and the configured engine is available, tools with a container alternative are pulled and locked by immutable RepoDigest. A wrapper is generated under `.harness/bin` so the rest of the Harness still invokes the normal tool command.

Default OCI-capable tools currently include OPA and Trivy. If Podman is unavailable, the resolver falls back to the mise/local definition instead of making containers mandatory.

## Project dependencies

After tool provisioning, setup detects common project dependency locks:

```text
package-lock.json  -> npm ci
pnpm-lock.yaml     -> corepack pnpm install --frozen-lockfile
bun.lock/bun.lockb -> bun install --frozen-lockfile
yarn.lock          -> corepack yarn install --immutable
                      (Yarn 1 uses --frozen-lockfile)
uv.lock            -> uv sync --frozen
*.sln/*.slnx/*.csproj/global.json -> dotnet restore
```

Extra deterministic commands may be declared under `projectDependencies.commands`.

Use `--skip-project-deps` when the repository or CI owns that phase separately.

## Commands

```bash
# Show what auto mode requires
aeh toolchain show

# Compile only the generated mise layer
aeh toolchain compile

# Side-effect-free plan
aeh setup --dry-run

# Provision exactly what the project currently requires
aeh setup

# Deliberately refresh fuzzy/latest versions and rewrite the lock
aeh setup --update-lock

# Prefer OCI alternatives when available
aeh setup --prefer-containers

# Install a named capability profile
aeh setup --profile agents
aeh setup --profile validation
aeh setup --profile full

# Bootstrap a repo and immediately provision it
aeh init --setup

# Prove the actual environment satisfies the Harness configuration
aeh doctor
```

## Runtime PATH

After setup, mise bin directories and AEH-generated OCI wrappers are written to machine-local state. `runProcess` prepends those paths automatically, including when running from a Git worktree whose control checkout owns the state.

This means Codex/OpenCode/Paseo/validators can be launched from Harness code without requiring users to modify `.bashrc`, `.zshrc` or IDE shell activation.

## Packaging and publication

`package.json` publishes the CLI entrypoint plus `dist`, templates, presets, policies, schemas, skills and docs. CI runs `npm run release:check`, which includes the complete typecheck/test/build sequence and `npm pack --dry-run`.

A GitHub Release publishing workflow is included at `.github/workflows/publish.yml`. It is designed for npm Trusted Publishing through GitHub Actions OIDC rather than a long-lived write token. Because npm requires a package to exist before a trusted publisher can be attached, the **first registry publication is a one-time bootstrap operation**; after that, configure the npm package's trusted publisher to `JamesMorales04/agentic-engineering-harness` + `publish.yml`, then normal GitHub Releases can publish with short-lived OIDC credentials.

See `docs/PUBLISHING.md` for the exact bootstrap and steady-state release sequence.

## Trust and installation policy

- npm installs AEH only;
- no `postinstall` performs host mutations;
- `aeh setup` is explicit and auditable;
- system prerequisites such as Git are checked, not silently installed with sudo;
- managed tool versions and OCI digests are locked;
- machine-local paths are not versioned;
- project dependency managers use their lock/frozen modes;
- `aeh doctor` is verification, while `aeh setup` is reconciliation;
- release CI validates the actual npm tarball before publishing.

The intended lifecycle is:

```text
clone
  -> bootstrap AEH npm package
  -> aeh setup
  -> aeh doctor
  -> Paseo / engineering lead
  -> implement issue #X
```
