@aaac/toolchain

Artifact-bound toolchain declarations — defines which tools operate on which artifacts.

Install

npm install @aaac/toolchain

What it does

toolchain-contracts is a declarative contract layer that binds tools → artifacts. Each toolchain entry declares what it consumes and produces, enabling static validation and dataflow lint across artifact-contracts, agent-contracts, and toolchain-contracts.

Quick Start

Create toolchain-contracts.yaml:

schema: aaac/toolchain/0.1

system:
  id: my-project

toolchains:
  prettier:
    kind: library
    module: prettier
    artifacts:
      consumes: [source-code]
      produces: [source-code]
    operations: [format]

  eslint:
    kind: cli
    command: npx eslint --fix
    artifacts:
      consumes: [source-code]
      produces: [source-code]

  speckeeper:
    kind: component
    component_contract: ./speckeeper.component.yaml
    artifacts:
      consumes: [spec-md, codebase]
      produces: [conformance-report]

Validate it:

npx aaac-toolchain validate toolchain-contracts.yaml

DSL Schema

| Field | Description | |-------|-------------| | schema | Schema version (e.g. aaac/toolchain/0.1) | | system | Project identity (id, optional name) | | toolchains | Map of toolchain ID → toolchain definition |

Each toolchain entry:

| Field | Description | |-------|-------------| | kind | Binding type: library, cli, or component | | module | npm package name (required for library) | | command | Shell command (for cli when no cli_contract) | | cli_contract | Path to cli-contracts YAML (alternative for cli) | | component_contract | Path to the component contract this toolchain embodies (required for component) | | artifacts | consumes and produces artifact IDs | | operations | Operation names, in the namespace component_contract names — that component's operations when it is set, the tool's own verbs (format, lint) when it is not |

Kind types

| Kind | Meaning | Required field | |------|---------|----------------| | library | npm package invoked programmatically | module | | cli | External CLI tool | command or cli_contract | | component | AaaC component with its own contract | component_contract |

$refs

Split toolchain definitions across files using $refs:

schema: aaac/toolchain/0.1

system:
  id: my-project

toolchains:
  inline-tool:
    kind: library
    module: inline-lib
    artifacts:
      consumes: [source-code]

$refs:
  - ./formatting.yaml
  - ./linting.yaml

Referenced files contain additional toolchains entries that are merged into the root document. Duplicate toolchain IDs across files are rejected.

CLI Commands

aaac-toolchain validate

Validate schema and semantic rules for a toolchain-contracts file.

npx aaac-toolchain validate toolchain-contracts.yaml

# Optional: check artifact IDs against a known set
npx aaac-toolchain validate toolchain-contracts.yaml \
  --artifact-ids source-code spec-md codebase conformance-report

aaac-toolchain lint

Check dataflow integrity across contract layers.

npx aaac-toolchain lint toolchain-contracts.yaml \
  --artifact-contracts artifact-contracts.yaml \
  --agent-contracts agent-contracts.yaml

Exit codes

| Code | Meaning | |-----:|---------| | 0 | All checks pass | | 1 | Validation or lint issues found | | 2 | File read or schema error |

Library API

import {
  loadToolchainContracts,
  parseToolchainFile,
  validateToolchainContracts,
  lintDataflow,
} from "@aaac/toolchain";

// Load and parse (resolves $refs)
const doc = await loadToolchainContracts("./toolchain-contracts.yaml");

// Validate
const issues = validateToolchainContracts(doc, {
  artifactIds: ["source-code", "spec-md"],
});

// Lint dataflow against other contract layers
const lintIssues = lintDataflow(doc, {
  artifacts: [{ id: "source-code", derived_from: [] }],
  agents: [{ id: "reviewer", consumes: ["source-code"], produces: ["review-report"] }],
});

| Function | Description | |----------|-------------| | loadToolchainContracts | Load YAML file, resolve $refs, validate schema | | parseToolchainFile | Parse file without $ref resolution | | validateToolchainContracts | Semantic validation (artifact IDs, duplicates) | | lintDataflow | Cross-contract dataflow integrity checks |

Related packages

• @aaac/contracts — Component contract compiler and code generators
• @aaac/runtime — Runtime SDK for executing AaaC workflows

License

MIT — see LICENSE.