AGENT SKILL

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

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 Command type, a service wrapping ChildProcessSpawner, a spawner backend, a node:child_process import, or a shell helper that interpolates a tool name — core's effect/process already declares the vocabulary, and Run is 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 for text/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 own console.log noise 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 (an ok literal) that an accidental log line cannot satisfy; and it parses regardless of the exit code, because an in-band ok field outranks the code — a child that crashed after flushing still reported. Whole- stdout JSON with exit-code semantics is Run.json; the two are not interchangeable.
  • Add env vars on top of the parent environment through Run.extendEnv, never a bare setEnv. A bare setEnv replaces the child's whole environment (no PATH, no HOME) unless extendEnv is explicitly set.
  • When you need both output and exit code, use Run.collect or 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 -v probe. A tool whose version flag exits 1 still exists; a command -v-shaped probe is an injection hazard and breaks on Windows.
  • commands declares LocalExec; @effected/workspaces implements it. Never add a direct @effected/workspaces edge to this package — a single-package consumer wires LocalExec.layerFor("npm") or .layerNone instead 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 real LocalExec answer, 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.detach must unref before its scope closes — reversed, the scoped release kills the child anyway, defeating detachment entirely.
  • Run.text trims leading and trailing whitespace, which silently corrupts any column-oriented output whose columns start with whitespace (a status column, say). Route that output through Run.collect and 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 Run combinator table, RunOptions, and all seven subprocess traps (deadlocking collection, collectTee's R split, detach/unref ordering, env-extension, text-trim corruption, double-execution) with the error taxonomy. Load when: choosing a combinator, tuning RunOptions, or classifying a command failure.
  • references/tool-discovery.md — ToolDiscovery's presence semantics, VersionProbe variants, the evidence-cache TTL rules, and LocalExec'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 shipped ScriptedSpawner test 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 — what effect/process declares (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, not Run — Run is free functions, so there is nothing service-shaped to mock.
  • effected-packages — the full @effected/commands package profile.
  • actions-cache-and-artifacts, actions-state-and-secrets, release-and-publish, testing-actions — what @effected/github-actions, @effected/npm and test doubles built on top of this package do that this package deliberately does not.

04 同仓库更多 Skills

spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8
spencerbeggs
spencerbeggs/effected

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.

★ 8