running-commands-and-tools
Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8
- Forks
- 2
01 前言 Front Matter
- name
- running-commands-and-tools
- description
- Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.
- when_to_use
- Run.collect, Run.text, Run.json, Run.detach, ToolDiscovery, LocalExec, ExecContext, Redaction, Retry, ScriptedSpawner, ChildProcessSpawner, run git/pnpm/npm/npx from Effect
02 资源文件 3
- 参考文档references/run-combinators.md9.5 KB
- 参考文档references/subprocess-traps.md3.2 KB
- 参考文档references/tool-discovery.md6.2 KB
03 SKILL.md 正文
Running commands and finding tools
@effected/commands is the kit's tool-and-output layer over core's
subprocess contract: Run turns a core ChildProcess.Command into typed
structured output; ToolDiscovery answers "is this tool here, and which
copy should I run?" Both are boundary tier — effect is the only peer,
zero @effected/* edges, zero node: imports.
What you have
| Construct | Import | Reach for it when |
|---|---|---|
Run.collect, .collectTee, .text, .lines, .json, .exitCode, .succeeds, .stream, .detach |
import { Run } from "@effected/commands" |
Running a core ChildProcess.Command and capturing typed output |
Run.jsonLine |
@effected/commands |
Framing ONE schema-decoded JSON payload line out of a child's otherwise noisy stdout (a subprocess protocol envelope) |
ToolDiscovery, Tool.named |
@effected/commands |
Checking whether a CLI tool is installed, and which copy (local vs global) to run |
LocalExec, ExecContext |
@effected/commands |
Prefixing a command through the project's local launcher (npx/pnpm exec/bun x) |
Redaction |
@effected/commands |
Scrubbing a secret from argv or captured stdout/stderr |
Retry |
@effected/commands |
Classifying a CommandFailedError as transient and retrying it |
ScriptedSpawner |
@effected/commands |
A shipped scripted ChildProcessSpawner double for tests |
CommandFailedError, CommandOutputError |
@effected/commands |
Handling "couldn't run/ran and failed" vs "ran, but output is unusable" |
Standards
- Every subprocess concept here is core's, and no implementation of one
is. Never add a
Commandtype, a service wrappingChildProcessSpawner, a spawner backend, anode:child_processimport, or a shell helper that interpolates a tool name — core'seffect/processalready declares the vocabulary, andRunis free functions for exactly this reason: core's spawner already is the runner service. - A non-zero exit is a result for
collect/exitCode/succeeds/jsonLine, a typed error fortext/lines/json. The split mirrors core's own contract and is deliberate — do not "fix" either half to match the other. - A JSON protocol payload from a child goes through
Run.jsonLine, never a hand-rolled last-line parse. It scans stdout lines from the end and takes the first that both JSON-parses and schema-decodes, so a child's ownconsole.lognoise is tolerated on both sides of the payload. Two consequences to design for: if several lines decode, the last wins, so give the envelope a required discriminant (anokliteral) that an accidental log line cannot satisfy; and it parses regardless of the exit code, because an in-bandokfield outranks the code — a child that crashed after flushing still reported. Whole- stdout JSON with exit-code semantics isRun.json; the two are not interchangeable. - Add env vars on top of the parent environment through
Run.extendEnv, never a baresetEnv. A baresetEnvreplaces the child's whole environment (noPATH, noHOME) unlessextendEnvis explicitly set. - When you need both output and exit code, use
Run.collector read both off the same spawner handle. Composing two convenience members re-executes the command — idempotent commands hide it, anything else fails on the second run while the captured "failure" belongs to the first, successful one. - Decide tool presence by whether the process ran, never by exit code or
a
command -vprobe. A tool whose version flag exits 1 still exists; acommand -v-shaped probe is an injection hazard and breaks on Windows. commandsdeclaresLocalExec;@effected/workspacesimplements it. Never add a direct@effected/workspacesedge to this package — a single-package consumer wiresLocalExec.layerFor("npm")or.layerNoneinstead of pulling in workspace discovery at all.- Redact by value first, then apply the flag-name backstop. Value-based redaction catches a secret wherever it appears, including embedded in a larger string; the heuristic backstop only covers what a caller forgot to declare — always run both, never one instead of the other.
Option.none()is a realLocalExecanswer, not an error. "No project-local way to run tools here" is a legitimate global-only context, not a fabrication or a failure to raise.
Footguns
- Collecting stdout/stderr/exit code sequentially deadlocks the moment
either OS pipe buffer fills — this is why the internal collection uses
unbounded concurrency; a mocked spawner over in-memory streams cannot
reproduce this class of bug, so the real dual-stream backpressure test
must never be deleted. See
references/run-combinators.md. Run.detachmust unref before its scope closes — reversed, the scoped release kills the child anyway, defeating detachment entirely.Run.texttrims leading and trailing whitespace, which silently corrupts any column-oriented output whose columns start with whitespace (a status column, say). Route that output throughRun.collectand parse the raw stdout instead.- The tool-discovery evidence cache must give a failed or not-found probe a short TTL and a found probe an infinite one — the opposite of a plain cache's default failure-memoization, or a transient probe failure sticks for the process lifetime and a tool installed mid-process stays absent forever.
Additional resources
- references/run-combinators.md — the
full
Runcombinator table,RunOptions, and all seven subprocess traps (deadlocking collection,collectTee'sRsplit, detach/unref ordering, env-extension, text-trim corruption, double-execution) with the error taxonomy. Load when: choosing a combinator, tuningRunOptions, or classifying a command failure. - references/tool-discovery.md —
ToolDiscovery's presence semantics,VersionProbevariants, the evidence-cache TTL rules, andLocalExec's full contract-inversion story including the four package managers' argv prefixes. Load when: resolving tool presence/version, or wiring a project-local launcher. - references/subprocess-traps.md —
Redaction's value-based and heuristic layers,Retry's transient classification, and the shippedScriptedSpawnertest double. Load when: redacting a secret, retrying a transient command failure, or scripting a fake spawner for a test.
Point elsewhere, don't restate
effect-v4-module-index— whateffect/processdeclares (ChildProcess/ChildProcessSpawner), and the routing-by-task row for "spawn a subprocess".effect-v4-idioms,effect-v4-services-layers— general v4 generator, error-handling and service/layer rules; nothing here repeats them.effect-v4-testing— stub the spawner, notRun—Runis free functions, so there is nothing service-shaped to mock.effected-packages— the full@effected/commandspackage profile.actions-cache-and-artifacts,actions-state-and-secrets,release-and-publish,testing-actions— what@effected/github-actions,@effected/npmand test doubles built on top of this package do that this package deliberately does not.
04 同仓库更多 Skills
testing-actions
Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.
supply-chain-attestation
Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.
structuring-an-action
Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.
running-commands-and-tools
Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.
release-and-publish
Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.
hardening-a-parser-port
Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.