@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.