feat(cli): machine-output mode — stream discipline, flag propagation, scrubber

[John-David Dalton (jdalton)]

Summary

Three-layer redesign that delivers a pipe-safe --json / --markdown contract across every command and every child process socket-cli spawns. Replaces an earlier narrow-scope attempt (module-level noLogMode + out() wrapper) that only fixed six dry-run formatters and would not survive handoff to child tools.

The problem

socket fix --json --dry-run | jq breaks because dry-run preview text routes to stdout instead of stderr. But that's the tip of the iceberg — the deeper failure modes are:

1. Child-process stdout contamination: when socket-cli pipes coana/sfw/npm/pnpm/yarn/pip/etc. stdout into its own, any chatter those tools emit lands in the captured payload.
2. Inconsistent stream discipline in socket-cli itself: status messages, warnings, and previews written to logger.log (stdout) instead of logger.error (stderr).
3. No coverage for tools that violate the Unix convention (yarn berry/yarn 6 write progress to stdout; synp/gem/cdxgen have no TTY check).

The fix — three composable layers

Layer 1: stream discipline (CLAUDE.md rule + targeted audit)

• New rule in CLAUDE.md under SHARED STANDARDS: stdout = the data the command was asked to produce; stderr = everything else.
• Audit: dry-run previews, output-scan-report.mts status lines, coana-fix.mts "Copying fixes result to …" message, cmd-oops.mts dry-run preview all moved from logger.log to logger.error.

Layer 2: per-(tool, subcommand) flag propagation

utils/spawn/machine-mode.mts is a single source of truth for what flags and env vars each child tool needs under machine mode. Verified from each tool's own source:

Tool	Forwarded flags	Env
coana	--silent --socket-mode <tempfile> (read file)	—
sfw	Forward to inner PM (transparent)	—
npm	--json --loglevel=error on JSON-aware subcommands	NO_COLOR=1
pnpm	--reporter=json / --reporter=silent	NO_COLOR=1
yarn classic	--json --silent	NO_COLOR=1
yarn berry (v4)	--json where supported	YARN_ENABLE_PROGRESS_BARS=0, YARN_ENABLE_INLINE_BUILDS=0, YARN_ENABLE_MESSAGE_NAMES=0, YARN_ENABLE_COLORS=0, YARN_ENABLE_HYPERLINKS=0
yarn 6 / zpm	--json on supported cmds; --silent on install+add	—
vltpkg	--view=json (uniform across subcommands)	—
pip/pip3	-q	PIP_NO_COLOR=1
uv	--quiet	—
cargo	-q	—
gem	--quiet --no-color	—
go	-json on build/list/test/vet	—

Universal env vars on every tool: NO_COLOR=1, FORCE_COLOR=0, CLICOLOR_FORCE=0.

Layer 3: output scrubber

utils/output/scrubber.mts is a Node Transform stream that:

1. Strips BOM and ANSI escapes (OSC + CSI, via ansiRegex() from @socketsecurity/lib/ansi).
2. Splits input on newlines (handles partial lines across chunks).
3. Classifies each line:
   • NUL-sentinel-bracketed span → stdout (socket-cli's own payload, zero ambiguity).
   • Valid JSON (JSON.parse succeeds) → stdout.
   • Known noise pattern ([INFO], npm notice, progress glyphs) → stderr.
   • Unknown → stderr (safe default — payload stays clean).
4. Exposes a tracing mode (SOCKET_SCRUB_TRACE=1) for debugging.
5. Supports tool-specific adapters (jc-inspired): synp, zpm, gem adapters ship with this PR; each ~30 LOC.

The scrubber is bounded (100 MB buffer cap; fallback to streaming passthrough if exceeded).

Layer 4: sentinel wrapping for our own payload

utils/output/emit-payload.mts's emitPayload() / emitJsonPayload() wraps socket-cli's own JSON/Markdown output in NUL-bracketed sentinels under machine mode. NUL bytes never appear in legitimate JSON or Markdown, so extraction is unambiguous.

Plus: ambient mode context

utils/output/ambient-mode.mts lets spawn wrappers and output helpers consult the current mode without threading flags through every function signature. Set once at argv-parse time in meowOrExit / meowWithSubcommands; reset between invocations to keep vitest cases isolated.

Flag rename

--no-log → --quiet. New description: "Route non-essential output (status, progress, warnings) to stderr so stdout carries only the payload. Implied by --json and --markdown."

What's deleted

• utils/output/no-log.mts (module-level noLogMode singleton).
• out() wrapper in utils/dry-run/output.mts (now plain logger.error).
• setNoLogMode/isNoLogMode callers.
• no-log.test.mts.

Research provenance

Each child tool's forwarding rule was verified from local source checkouts or installed packages:

• coana: /Users/.../coana-package-manager/packages/cli/src/index.ts — --socket-mode <file> + --silent (Winston silent=true) confirmed.
• yarn berry: /Users/.../berry/packages/plugin-essentials/sources/commands/*.ts — --json per-subcommand matrix confirmed; YARN_ENABLE_* env vars from yarnpkg-core/Configuration.ts.
• yarn 6 / zpm: /Users/.../zpm/packages/zpm/src/commands/*.rs — --json per-subcommand matrix confirmed; no NO_COLOR respect.
• synp: node_modules/synp@1.9.14/cli/*.js — no flags exist; console.log('Created …') to stdout on success; colored ANSI error on stderr unconditionally.
• npm/pnpm/pip/uv/cargo/gem/go/vltpkg: public documentation + manual --help inspection.

Test plan

• pnpm run type clean
• pnpm run lint clean
• pnpm run build:cli succeeds
• pnpm --filter @socketsecurity/cli run test:unit — 5,202 tests pass (74 new, 134 existing assertions updated to reflect stderr routing)
• CI green

Follow-ups (tracked separately, out of scope)

• Cross-repo structured NDJSON event contract (cargo's --message-format=json pattern) — per-tool Socket event types.
• Coana upstream: native --machine-output flag that routes Winston logger to stderr and emits JSON to stdout.
• zpm upstream: add NO_COLOR/FORCE_COLOR respect.
• synp upstream: add --quiet and --json.
• Full socket-cli sweep of the remaining ~500 logger.log call sites for stream-discipline conformance (a lib-side fix to @socketsecurity/lib/logger to route info/step/progress to stderr will automate most of these).

[John-David Dalton (jdalton)]

Cursor (@cursor) review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e04fa30. Configure here.}

[John-David Dalton (jdalton)]

Cursor (@cursor) review

[John-David Dalton (jdalton)]

Cursor (@cursor) review

[John-David Dalton (jdalton)]

Cursor (@cursor) review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ed83f91. Configure here.}

[John-David Dalton (jdalton)]

Cursor (@cursor) review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ed83f91. Configure here.}

[John-David Dalton (jdalton)]

Cursor (@cursor) review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ed83f91. Configure here.}