///
const S = Smithers
import { Package as compiler } from './bundler-packages/compiler/PACKAGE.js'
import { Package as cli } from './cli/PACKAGE.js'
import { Package as viem } from './extensions/viem/PACKAGE.js'
import { Package as factory } from './factory/PACKAGE.js'
import { Package as mcp } from './packages/mcp/PACKAGE.js'
// PACKAGE.ts files are discovered automatically: the CLI globs the tree and
// indexes each file's Package export under path-derived labels
// (//packages/evm:test, //test:conformanceFast, //:lint). Only targets passed
// to S.Package are public; consts that stay out of the map are private to
// this file. This root file holds tree-wide targets. Per-package targets
// live beside their packages, and Query patterns aggregate them here without
// central imports, so a new package joins CI by existing.
const packageJson = S.file('//package.json')
const lockfile = S.file('//pnpm-lock.yaml')
const workspaceConfig = S.file('//pnpm-workspace.yaml')
const cargoManifest = S.file('//Cargo.toml')
const cargoLockfile = S.file('//Cargo.lock')
const biomeConfig = S.file('//biome.json')
const changesetConfig = S.file('//.changeset/config.json')
// The root-level files the root `lint` script formats and checks (biome.json,
// package.json, *.md, *.ts). Package trees are linted by their own //
:lint.
const rootFiles = S.Filegroup({
srcs: S.glob(['biome.json', 'package.json', '*.md', '*.ts', 'jsr.json']),
})
const changesets = S.Filegroup({
srcs: S.glob(['.changeset/**']),
})
// The whole tree as one group, for the targets that walk it (sort-package-json,
// depcheck at the root). Generated output and caches are excluded so a build
// does not re-key them.
const tree = S.Filegroup({
srcs: S.glob([
'**/*.{ts,tsx,js,mjs,cjs,json,md,sol}',
'!**/node_modules/**',
'!**/dist/**',
'!**/coverage/**',
'!**/docs/**',
'!**/types/**',
'!**/.nx/**',
'!**/.flows/**',
'!**/.worktrees/**',
'!**/.tmp-*/**',
'!**/.smithers/**',
'!**/.cache/**',
'!**/artifacts/**',
'!**/vendor/**',
]),
})
// vendor/flows (the Smithers build source the @smthrs/* link: dependencies
// resolve through)
// are gitlinks the repository index pins. This target materializes them at
// their pinned commits and refuses a worktree that drifted from its gitlink;
// CI checks them out with the tree because the graph declares it.
const vendor = S.Git.Submodules({
config: S.file('//.gitmodules'),
paths: ['vendor/flows'],
})
// Zig must check sibling source contents on every invocation. The addon lives
// outside TEVM's captured outputs, so a cached build receipt cannot restore it.
// Include release pins so dependent checks invalidate when native revisions move.
const zevm = S.Shell.Run({
bin: S.Runtime.bin,
args: ['scripts/factory/build-native.mjs'],
data: [
workspaceConfig,
lockfile,
S.file('//scripts/factory/build-native.mjs'),
S.file('//mise.toml'),
S.file('//factory/native-dependencies.json'),
],
})
// The first half of the root `lint` script: biome over the root-level files.
// Package trees are covered by allLints below.
const lint = S.Shell.Test({
bin: S.NodeModule.Bin('@biomejs/biome'),
args: ['check', 'biome.json', 'package.json', '*.md', '*.ts'],
data: [rootFiles, biomeConfig],
})
const format = S.Shell.Diff({
bin: S.NodeModule.Bin('@biomejs/biome'),
args: ['check', '--write', '--unsafe', 'biome.json', 'package.json', '*.md', '*.ts'],
data: [rootFiles, biomeConfig],
changes: ['biome.json', 'package.json', '*.md', '*.ts'],
})
// Manifest hygiene. sort-package-json --check is the lint every gate runs,
// a plain test over the manifests; the Diff form is the --write repair,
// confined to the manifest write set. (A Generate check materializes its
// tree into a scratch copy, which cost twelve minutes per run here.)
const manifestGlobs = [
'package.json',
'bundler-packages/*/package.json',
'configs/*/package.json',
'examples/*/package.json',
'extensions/*/package.json',
'packages/*/package.json',
'tevm/package.json',
]
const manifests = S.Filegroup({
srcs: S.glob(manifestGlobs),
})
const sortManifestsCheck = S.Shell.Test({
bin: S.NodeModule.Bin('sort-package-json'),
args: ['--check', ...manifestGlobs],
data: [manifests],
})
const sortManifests = S.Shell.Diff({
bin: S.NodeModule.Bin('sort-package-json'),
args: manifestGlobs,
data: [manifests],
changes: ['package.json', '*/package.json', '*/*/package.json'],
})
// The root half of the lint:deps script: depcheck over the root manifest.
const depsLint = S.Shell.Test({
bin: S.NodeModule.Bin('depcheck'),
data: [packageJson, lockfile, rootFiles],
})
// Current Flows executes every package target by exact label but does not yet
// expose a Query value inside PACKAGE.ts. These compatibility targets keep the
// established Nx fan-out authoritative for root-wide gates while the much
// more granular package targets remain runnable one at a time. Each command is
// content-keyed on the repository inputs and can be replaced by a native query
// without changing any consumer when that authoring primitive lands.
// Postinstall stages the native addon. Keep its explicit rebuild target uncached;
// release pins invalidate aggregate verdicts when any native dependency changes.
const aggregateData = [tree, packageJson, lockfile, workspaceConfig, S.file('//factory/native-dependencies.json')]
// Flows is the outer content-addressed runner. Nx stays as the compatibility
// fan-out inside these aggregate targets, but its workspace daemon and remote
// cache must not introduce shared mutable state or network access between
// concurrently evaluated sandboxes.
const nxEnvironment = {
NX_DAEMON: 'false',
NX_NO_CLOUD: 'true',
} as const
const allBuilds = S.Shell.Test({
bin: S.PackageManager.bin,
args: ['run', 'build:dist'],
data: aggregateData,
env: nxEnvironment,
})
// The Nx fan-outs below write and read the same dist/ and types/ trees, so
// they take each other as data edges in the order the twelve-step CI ran
// them: Flows would otherwise start them all at once and one Nx process
// would read a package's types while another rewrites them.
const allTypes = S.Shell.Test({
bin: S.PackageManager.bin,
args: ['run', 'build:types'],
data: [...aggregateData, allBuilds],
env: nxEnvironment,
})
const allDeclarations = S.Alias(allTypes)
const allTypechecks = S.Shell.Test({
bin: S.PackageManager.bin,
args: ['exec', 'nx', 'run-many', '--target=typecheck'],
data: [...aggregateData, allTypes],
env: nxEnvironment,
})
// The legacy Nx test:run fan-out mixes tests with different capabilities.
// These four projects are exercised below through their first-class Flows
// targets, where egress and secrets stay explicit. Everything else gets only
// loopback: enough for in-process HTTP/WebSocket suites, never internet access.
const allHermeticTests = S.Shell.Test({
bin: S.PackageManager.bin,
args: [
'exec',
'nx',
'run-many',
'--target=test:run',
'--exclude=@tevm/compiler,@tevm/viem,@tevm/mcp,@tevm/cli',
'--parallel=2',
'--skip-nx-cache',
],
data: aggregateData,
env: nxEnvironment,
sandbox: { network: 'loopback' },
})
const externalIntegrationTests = S.Suite({
tests: [compiler.test, viem.test, mcp.test, mcp.testFork, cli.testVitest],
})
const allTests = S.Suite({
tests: [allHermeticTests, externalIntegrationTests],
})
// The Nx coverage fan-out still reaches the packages whose suites fork live
// chains (state, actions, blockchain, viem, cli, whatsabi, test), so it
// declares the same three integration secrets and egress those packages'
// first-class targets declare; CI maps the secrets into the job for it.
const integrationSecrets = [
S.Secret('TEVM_TEST_ALCHEMY_KEY'),
S.Secret('TEVM_RPC_URLS_MAINNET'),
S.Secret('TEVM_RPC_URLS_OPTIMISM'),
]
const allCoverage = S.Shell.Test({
bin: S.PackageManager.bin,
args: ['run', 'test:coverage'],
data: [...aggregateData, allTypechecks],
env: nxEnvironment,
secrets: integrationSecrets,
sandbox: { network: true },
})
const allDocs = S.Shell.Test({
bin: S.PackageManager.bin,
args: ['run', 'generate:docs'],
data: [...aggregateData, allCoverage],
env: nxEnvironment,
})
const allLints = S.Shell.Test({
bin: S.PackageManager.bin,
args: ['run', 'lint:check'],
data: aggregateData,
env: nxEnvironment,
})
const allDepsLints = S.Shell.Test({
bin: S.PackageManager.bin,
args: ['run', 'lint:deps'],
data: aggregateData,
env: nxEnvironment,
})
const allPackageLints = S.Shell.Test({
bin: S.PackageManager.bin,
args: ['run', 'lint:package'],
data: [...aggregateData, allDocs],
env: nxEnvironment,
})
// Individual //:apiCompat targets remain available. Until target
// queries can be embedded, the aggregate release guard uses the publish-shape
// suite that exercises every packed package.
const allApiCompat = S.Alias(allPackageLints)
// CI's "Fixtures" step (`pnpm -r dev:run`): every package that runs its
// fixtures as a check.
const allFixtures = S.Shell.Test({
bin: S.PackageManager.bin,
args: ['exec', 'nx', 'run-many', '--target=dev:run'],
data: [...aggregateData, allPackageLints],
env: nxEnvironment,
secrets: integrationSecrets,
sandbox: { network: true },
})
const cargoBuilds = S.Shell.Test({
bin: S.Host.bin('cargo'),
args: ['build', '--workspace'],
data: [cargoManifest, cargoLockfile],
})
const cargoTests = S.Shell.Test({
bin: S.Host.bin('cargo'),
args: ['test', '--workspace'],
data: [cargoManifest, cargoLockfile],
})
// CI's "Validate Cargo workspace" step: `cargo check --workspace --quiet`,
// keyed through the cargo workspace layer on every crate's sources.
const cargoCheck = S.Shell.Test({
bin: S.Host.bin('cargo'),
args: ['check', '--workspace', '--quiet'],
data: [
cargoManifest,
cargoLockfile,
S.Filegroup({ srcs: S.glob(['bundler-packages/*-rs/src/**', 'bundler-packages/*-rs/Cargo.toml']) }),
],
})
// Every PR touching a publishable package needs a changeset; status against
// origin/main is the same check release:check runs.
// `changeset status` validates every pending changeset and that each
// internal dependency names the current version, so the manifests are key
// material beside the changesets. It always diffs against a git base, so
// there are two forms: the branch form diffs against origin/main (the ci
// job checks out full history for it; a developer host has the ref), and
// the candidate form diffs against HEAD, which is what an Agent.Diff
// candidate tree can answer and exactly the changesets the agent added.
const changesetCheck = S.Shell.Test({
bin: S.NodeModule.Bin('@changesets/cli', 'changeset'),
args: ['status', '--verbose', '--since=origin/main'],
data: [changesets, changesetConfig, tree, S.gitDiff()],
})
// A candidate tree (Agent.Diff scratch copy) carries no git repository, so
// the lane form validates from files alone: every pending changeset names
// workspace packages with a valid bump and a summary, and every internal
// dependency uses workspace: or the current version, the rule `changeset
// status` enforces at release time.
const changesetCandidateCheck = S.Shell.Test({
bin: S.Runtime.bin,
args: ['scripts/factory/changeset-candidate.mjs'],
data: [changesets, changesetConfig, workspaceConfig, tree],
})
// Agentic lints over the diff. Each enforces a CLAUDE.md rule that prose
// cannot: a clean diff is vacuously green with zero agent spawns, --fix lets
// the agent correct findings inside its write set, and the verdict caches
// on the diff like any other test. Agents are declared in WORKSPACE.ts.
// Exported symbols need JSDoc that typedoc can render. Grounds the
// scripts/jsdoc-helper tooling as a lint with a fix verb instead of a batch
// script.
const jsdocLint = S.Agent.Lint({
agent: S.Agents.luna,
prompt: S.file('//workflows/lints/jsdoc.md'),
data: [S.gitDiff({ paths: ['packages/**/src/**', 'bundler-packages/**/src/**', 'extensions/**/src/**'] })],
fixes: ['packages/**/src/**', 'bundler-packages/**/src/**', 'extensions/**/src/**'],
})
// A diff that changes published source carries a changeset whose level
// matches the change. changesetCheck above only tests presence; judging
// patch vs minor vs major is judgment work.
const changesetLint = S.Agent.Lint({
agent: S.Agents.luna,
prompt: S.file('//workflows/lints/changeset.md'),
data: [
S.gitDiff({
paths: ['packages/**/src/**', 'bundler-packages/**/src/**', 'extensions/**/src/**', 'tevm/**', '.changeset/**'],
}),
],
fixes: ['.changeset/**'],
})
// Tests exercise real objects, never mocks (CLAUDE.md testing conventions).
const noMocksLint = S.Agent.Lint({
agent: S.Agents.luna,
prompt: S.file('//workflows/lints/no-mocks.md'),
data: [S.gitDiff({ paths: ['**/*.spec.ts', '**/*.test.ts'] })],
fixes: ['**/*.spec.ts', '**/*.test.ts'],
})
// A new public symbol is re-exported through every barrel up to the tevm
// meta package; a missed barrel is silent at type-check time.
const barrelExportsLint = S.Agent.Lint({
agent: S.Agents.luna,
prompt: S.file('//workflows/lints/barrel-exports.md'),
data: [
S.gitDiff({
added: ['packages/**/src/**', 'bundler-packages/**/src/**', 'extensions/**/src/**'],
addedLines: '^export ',
}),
],
fixes: ['packages/**/src/**/index.{js,ts}', 'bundler-packages/**/src/**/index.{js,ts}', 'tevm/**/index.ts'],
})
// Snapshots must not embed the recording machine (absolute paths, temp dirs).
const snapshotPathsLint = S.Agent.Lint({
agent: S.Agents.luna,
prompt: S.file('//workflows/lints/snapshot-paths.md'),
data: [S.gitDiff({ paths: ['**/__snapshots__/**', '**/__rpc_snapshots__/**', '**/*.spec.ts'] })],
fixes: ['**/__snapshots__/**', '**/__rpc_snapshots__/**', '**/*.spec.ts'],
})
// A new action, JSON-RPC handler, or bundler option needs guide coverage
// under docs/node or sites/core.
const docsParityLint = S.Agent.Lint({
agent: S.Agents.luna,
prompt: S.file('//workflows/lints/docs-parity.md'),
data: [
S.gitDiff({
added: [
'packages/actions/src/**',
'packages/memory-client/src/**',
'packages/decorators/src/**',
'tevm/*/index.ts',
],
}),
],
fixes: ['docs/node/pages/**', 'sites/core/pages/**'],
})
// PRs #1894, #1971, #1969, #2049/#2081, and #2076 show a recurring
// failure mode: the internal value is plausible while the JSON-RPC wire
// value, type union, dispatch registration, or public client surface is not.
const rpcContractLint = S.Agent.Lint({
agent: S.Agents.luna,
prompt: S.file('//workflows/lints/rpc-contract.md'),
data: [
S.gitDiff({
paths: [
'packages/actions/src/**',
'packages/jsonrpc/src/**',
'packages/memory-client/src/**',
'packages/decorators/src/**',
'packages/procedures/src/**',
'packages/server/src/**',
'tevm/**/index.ts',
],
}),
],
fixes: [
'packages/actions/src/**',
'packages/jsonrpc/src/**',
'packages/memory-client/src/**',
'packages/decorators/src/**',
'packages/procedures/src/**',
'packages/server/src/**',
'tevm/**',
],
})
// A coverage increase is not necessarily a regression proof. This lint is
// grounded in follow-up review findings on stateful, negative, and alternate
// encoding branches in PRs #2076, #2079, #2090, and #2094.
const regressionProofLint = S.Agent.Lint({
agent: S.Agents.luna,
prompt: S.file('//workflows/lints/regression-proof.md'),
data: [
S.gitDiff({
paths: [
'packages/**/src/**',
'bundler-packages/**/src/**',
'extensions/**/src/**',
'test/**/*.spec.ts',
'test/**/*.test.ts',
'test/**/fixtures/**',
],
}),
],
fixes: [
'packages/**/*.spec.ts',
'packages/**/*.test.ts',
'bundler-packages/**/*.spec.ts',
'bundler-packages/**/*.test.ts',
'extensions/**/*.spec.ts',
'extensions/**/*.test.ts',
'test/**',
],
})
// The author's merged PRs are materially narrower than closed/unmerged work,
// but PR #2091 proves raw size is the wrong signal. This check-only lint
// distinguishes coherent mechanical fan-out from unrelated agent churn.
const scopeCoherenceLint = S.Agent.Lint({
agent: S.Agents.luna,
prompt: S.file('//workflows/lints/scope-coherence.md'),
data: [S.gitDiff()],
})
const agentLints = S.Suite({
tests: [
jsdocLint,
changesetLint,
noMocksLint,
barrelExportsLint,
snapshotPathsLint,
docsParityLint,
rpcContractLint,
regressionProofLint,
scopeCoherenceLint,
],
})
// The claude-code-review.yml checklist as a target: the same review,
// runnable locally before pushing.
const prReview = S.Agent.Lint({
agent: S.Agents.reviewPool,
prompt: S.file('//.github/workflows/claude-code-review.yml'),
data: [S.gitDiff()],
})
// Filegroup groups files, Suite groups tests, Alias renames one target. A
// dependency edge always means "materialize files", never "execute".
const preCommit = S.Suite({
tests: [lint, changesetCheck, factory.check],
})
// Agent candidate loops can execute deterministic tool gates against their
// scratch tree, but cannot recursively spawn another Agent.Lint. The script
// runs static analysis and hermetic tests sequentially, using one daemonless
// Nx scheduler at a time. It permits loopback for local integration servers
// but never egress. External integrations remain a maintainer-only pre-push
// lane with their own declared secrets and network capabilities below.
const mechanicalPrePush = S.Shell.Test({
bin: S.Runtime.bin,
args: ['scripts/factory/mechanical-pre-push.mjs'],
data: aggregateData,
env: nxEnvironment,
sandbox: { network: 'loopback' },
})
const prePush = S.Suite({
tests: [mechanicalPrePush, externalIntegrationTests, agentLints],
})
// Every commit is retained as a memory fact, so agent targets see recent
// history without re-reading git.
const retainCommit = S.Memory.Retain({
source: S.gitCommit('HEAD'),
tags: ['commit'],
})
const postCommit = S.Suite({
tests: [retainCommit],
})
// ci.yml's steps as one suite, in its order: build dist, build types, tests,
// fixtures, rust tests, typecheck, lint, lint deps, lint packages, docs,
// cargo check. An unaffected target is a cache hit, so the whole suite is
// cheap on a small PR. The `build:rust:app` step targets an nx project name
// (my_rust_node_lib) that no longer exists; cargoBuilds covers what it meant.
const ci = S.Suite({
tests: [
allBuilds,
allTypes,
allDeclarations,
allCoverage,
allFixtures,
cargoTests,
allTypechecks,
allLints,
sortManifestsCheck,
allDepsLints,
allPackageLints,
allDocs,
cargoBuilds,
cargoCheck,
factory.check,
changesetCheck,
],
})
// changesets owns versioning. version applies pending changesets to manifests
// and changelogs (release:version, a Diff over the tree, then
// `pnpm install --lockfile-only` for the lockfile). publish builds everything,
// runs scripts/prepare-changeset-publish.mjs, and pushes each bumped package to
// npm with provenance through the scripts/pnpm-publish-wrapper PATH shim
// (release:publish). The per-package apiCompat gates prove the chosen bumps
// cover the real API deltas before anything is public.
const versionPackages = S.Changesets.Version({
config: changesetConfig,
data: [changesets],
changes: ['**/package.json', '**/CHANGELOG.md', '.changeset/**'],
})
const version = S.Shell.Diff({
bin: S.PackageManager.bin,
args: ['install', '--lockfile-only'],
data: [versionPackages, packageJson, workspaceConfig],
changes: ['pnpm-lock.yaml'],
sandbox: { network: true },
})
const publish = S.Shell.Run({
bin: S.PackageManager.bin,
args: ['run', 'release:publish'],
data: [allBuilds, allTypes, allDeclarations, cargoBuilds],
env: nxEnvironment,
gates: [ci, allApiCompat],
secrets: [S.Secret('NPM_TOKEN')],
sandbox: 'none',
approval: 'required',
})
// prerelease.yml: main publishes under the `next` dist-tag while
// .changeset/pre.json is present. enter/exit are the two Diff halves of
// prerelease mode (prerelease.yml's `changeset pre enter next`,
// prerelease-exit.yml's `changeset pre exit`).
const prereleaseEnter = S.Shell.Diff({
bin: S.NodeModule.Bin('@changesets/cli', 'changeset'),
args: ['pre', 'enter', 'next'],
data: [changesets, changesetConfig],
changes: ['.changeset/pre.json'],
})
const prereleaseExit = S.Shell.Diff({
bin: S.NodeModule.Bin('@changesets/cli', 'changeset'),
args: ['pre', 'exit'],
data: [changesets, changesetConfig],
changes: ['.changeset/pre.json'],
})
const prerelease = S.Shell.Run({
bin: S.PackageManager.bin,
args: ['run', 'release:publish'],
data: [allBuilds, allTypes, allDeclarations, cargoBuilds, S.file('//.changeset/pre.json')],
env: nxEnvironment,
gates: [ci, allApiCompat],
secrets: [S.Secret('NPM_TOKEN')],
sandbox: 'none',
approval: 'required',
})
// snapshot.yml: a one-off snapshot release of every package from the
// current tree (changesets-snapshot), on dispatch only.
const snapshot = S.Shell.Run({
command: 'pnpm exec changeset version --snapshot snapshot && pnpm run release:publish',
data: [allBuilds, allTypes, allDeclarations],
env: nxEnvironment,
gates: [ci],
secrets: [S.Secret('NPM_TOKEN'), S.Secret('GITHUB_TOKEN')],
sandbox: 'none',
approval: 'required',
})
// Committing and PR-opening are targets, so their guards are the same suites
// CI runs; a commit that would fail CI cannot be created. Invoking the
// target is the consent for its outward action.
const commit = S.Git.Commit({
gates: [preCommit],
message: S.Agents.luna!,
})
const pr = S.Git.Pr({
gates: [prePush],
secrets: [S.Secret('GITHUB_TOKEN')],
sandbox: { network: true },
})
// The root `clean` script: nx reset, every package's clean, node_modules.
// The nx cache is gone; per-package cleans are `smthrs '//**:clean'`; the
// workspace install layer owns node_modules. What remains is the tree-level
// output the runners write.
const clean = S.Clean({
paths: ['.nx', 'artifacts', 'dist', '.flows/tmp'],
})
export const Package = S.Package({
defaultVisibility: 'public',
targets: {
agentLints,
allApiCompat,
allBuilds,
allCoverage,
allDeclarations,
allDepsLints,
allDocs,
allFixtures,
allHermeticTests,
allLints,
allPackageLints,
allTests,
allTypechecks,
allTypes,
barrelExportsLint,
cargoBuilds,
cargoCheck,
cargoTests,
changesetCandidateCheck,
changesetCheck,
changesetLint,
ci,
clean,
commit,
depsLint,
docsParityLint,
externalIntegrationTests,
format,
jsdocLint,
lint,
mechanicalPrePush,
noMocksLint,
postCommit,
pr,
prReview,
preCommit,
prePush,
prerelease,
prereleaseEnter,
prereleaseExit,
publish,
regressionProofLint,
retainCommit,
rpcContractLint,
scopeCoherenceLint,
snapshot,
snapshotPathsLint,
sortManifests,
sortManifestsCheck,
vendor,
version,
zevm,
},
})