cmdchain 0.1.2__tar.gz → 0.2.0__tar.gz

cmdchain-0.2.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      dev-tools:
+        patterns: ["*"]

cmdchain-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_call: # publish.yml runs this before uploading
+
+permissions:
+  contents: read
+
+# Actions are pinned by commit SHA (tag in the comment); Dependabot keeps them current.
+# Tools come from the `dev` dependency group via uv.lock, so a new ruff or basedpyright
+# release cannot break main without a code change.
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.15"
+      - run: uv sync --locked
+      - run: uv run ruff check src/ tests/ examples/
+      - run: uv run ruff format --check src/ tests/ examples/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.15"
+      - run: uv sync --locked
+      - run: uv run basedpyright src/ tests/
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        # 3.15t is the free-threaded build: the concurrency tests run without a GIL.
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15", "3.15t"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      # pytest settings (pyproject.toml) turn every warning into an error, ResourceWarning
+      # included, and give each test a 60 s timeout so a regression cannot hang the job.
+      - run: uv run coverage run -m pytest -v
+      - run: uv run coverage report
+
+  prerelease:
+    # The next Python, so breakage shows up before its release. Allowed to fail.
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.16"
+      - run: uv sync --locked
+      - run: uv run pytest -v
+
+  compile:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.15"
+      - run: uv sync --locked --extra compile
+      - run: uv run pytest -v tests/test_compile.py
+
+  examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: "3.15"
+      - run: uv sync --locked
+      # 12_webhook_metrics.py is skipped: it posts to a remote HTTP endpoint.
+      # 06 and 07 only describe their pipelines, so they run without pv or ffmpeg.
+      - run: |
+          for f in examples/*.py; do
+            case "$f" in *12_webhook_metrics.py) continue ;; esac
+            echo "=== $f ==="
+            (cd "$RUNNER_TEMP" && uv run --project "$GITHUB_WORKSPACE" python -W error "$GITHUB_WORKSPACE/$f") || exit 1
+          done

cmdchain-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    # Nothing is uploaded unless the full CI suite passes on the release commit.
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI trusted publishing; also produces attestations
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

{cmdchain-0.1.2 → cmdchain-0.2.0}/.gitignore

@@ -21,3 +21,5 @@ venv/
 .vscode/
 *.swp
 *.swo
+.coverage
+.coverage.*

cmdchain-0.2.0/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the version is 0.x,
+a breaking change bumps the minor version and everything else bumps the patch version.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-11-03
+
+A rewrite of the executor for safety and correctness. Every item below has a test.
+
+### Breaking changes
+
+- **Python 3.11+** is required (3.10 reached end of life in October 2026). POSIX only.
+- `result.sbom()` / `sbom_json()` now return a **CycloneDX 1.6** document. The previous
+  run record is `result.manifest()` / `manifest_json()`.
+- `redirect()` streams straight to its file and **consumes** what it writes, like `>`:
+  redirected stdout no longer appears in `result.stdout`, and redirected stderr not in
+  `result.stderr`. `redirect(stderr=...)` now writes the commands' stderr (it used to
+  write stdout's text).
+- A writer killed by **SIGPIPE** because its reader exited early (`yes | head -1`) is no
+  longer a failure; use `run(ignore_sigpipe=False)` for the old behaviour.
+- **Version checks fail closed**: if a tool's version cannot be determined, a `version=`
+  constraint is not met (`on_fail="warn"` to continue). Invalid constraints raise
+  `ValueError` when the tool is defined. Only `--version` is probed (`version_args=` for
+  other flags).
+- **Pipelines are immutable**: builder methods return a new pipeline instead of
+  appending to the one they were called on. A second input source raises `ValueError`.
+- After `.capture()`, only `{name}` for captured names is substituted; other braces are
+  literal (they used to raise `KeyError`).
+- `CLICHAIN_DESCRIBE` only enables describe mode for `1`, `true`, `yes`, `describe`,
+  `text` or `json` (it used to be any non-empty value, including `0`), and raises
+  `DescribeExit` (a `SystemExit` subclass) instead of calling `sys.exit()`.
+- A signal during `run()` reaches the previously installed handler after cleanup:
+  `KeyboardInterrupt` for SIGINT by default, instead of `SystemExit(130)`.
+- Missing input files and unwritable redirects return a failed `Result` (returncode 1)
+  instead of raising `OSError`. Exceptions from your own callbacks propagate instead of
+  being printed by the thread and silently truncating output.
+- `clichain check` exits 1 when a check fails, and no longer executes pipelines run by
+  the script.
+- `clichain.core` is gone; import from `clichain`.
+
+### Added
+
+- `tool(..., env=, inherit_env=, cwd=, version_args=, ok_codes=)`; `ok_codes={0, 1}` makes
+  an expected status (grep with no match, diff with differences) a success.
+- `feed()` accepts `bytes`.
+- Live output: `run(live="auto" | "blocks" | "grouped" | "lines")` or `Live(...)`. Every
+  job (a run, or an `each()` line; or every process with `unit="process"`) gets its own
+  buffer, so concurrent tools never mangle each other's output. Blocks redraw in place on
+  a terminal; grouped output uses `::group::` on GitHub Actions. Default: nothing live.
+- `tool(..., tty=True)`: the command's stderr is a pseudo-terminal, so tools that only
+  show progress on a terminal (git, curl, rsync) do; stdout stays a pipe.
+- `run(..., timeout=, check=, encoding=, errors=, ignore_sigpipe=, output=)`;
+  `PipelineError` for `check=True`; exit code 124 (`X124`) for timeouts.
+- `result.stdout_bytes`, and lossless handling of binary / non-UTF-8 data
+  (`errors="surrogateescape"` by default).
+- `result.manifest(redact=True)`, which removes hostname, cwd and directory paths.
+- `capture(name, reject_options=True)` against option injection.
+- `pipe()` accepts a `Pipeline`, not only a `Cmd`.
+- Free-threaded Python support, tested in CI.
+
+### Changed
+
+- `StepProfile.bytes_in` / `bytes_out` are measured at every group boundary (they were
+  only set when a meter was present, and always equal); the report always has a bytes
+  column. Both are now `int`, never `None`.
+
+### Fixed
+
+- Hangs: a command writing more than 64 KB to stderr; a filter/peek/meter callback that
+  raises; a bridge in front of an early-exit reader (`... | filter | head -1`); a stopped
+  run whose processes left descendants holding a pipe open.
+- File descriptor leaks (stderr pipes, bridge inputs).
+- Meter statistics accumulating across runs of the same pipeline; meter callbacks
+  receiving a live, still-changing object.
+- `explain` codes: invalid input to `clichain explain` no longer crashes; exit codes above
+  128 that are not signals (e.g. 255) are explained as exit codes.
+- Parallel `each()`: a callback error stops the remaining lines; a failing line's stderr
+  is kept even when an earlier line was skipped.
+
+### Security
+
+- The version probe never passes positional words (`version`) or `-v`, which tools
+  without a version flag treated as file operands (BSD `rm` deleted `./version`), and it
+  runs with stdin closed (it consumed the caller's stdin).
+- `import clichain` no longer runs `git`; the commit is looked up lazily, labelled
+  `source_commit`, from the repository of the calling script.
+- CI actions are pinned by commit SHA, tools come from `uv.lock`, Dependabot keeps them
+  current, and publishing runs only after the full CI suite passes.
+
+### Performance
+
+- Bridges process data in blocks: filter about 6x, peek 11x and meter 49x faster on
+  2M lines. Redirected output never passes through Python memory.
+
+## [0.1.2] - 2026-04-02
+
+### Added
+
+- `cmdchain` import alias for the `clichain` module.
+
+### Fixed
+
+- Logo rendering on PyPI; the version is single-sourced from `pyproject.toml`.
+
+## [0.1.1] - 2026-04-02
+
+### Added
+
+- Git commit hash in the SBOM and reports; README included on PyPI.
+
+## [0.1.0] - 2026-04-02
+
+First release: `tool()`, pipelines with `pipe`, `filter`, `each`, `peek`, `meter`,
+`capture`, `feed`, `from_file`, `redirect`; preflight checks; reports and SBOM; the
+`clichain` CLI (`explain`, `check`, `compile`).
+
+[Unreleased]: https://github.com/dardevelin/clichain/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/dardevelin/clichain/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/dardevelin/clichain/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/dardevelin/clichain/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/dardevelin/clichain/releases/tag/v0.1.0

cmdchain-0.2.0/CLAUDE.md

@@ -0,0 +1,47 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+clichain: fluent, lazily-evaluated pipelines of CLI commands connected by real kernel pipes. Zero runtime dependencies, Python 3.11+ (free-threaded builds included), POSIX only.
+
+**Versioning:** Semantic Versioning, recorded in `CHANGELOG.md` (Keep a Changelog). While 0.x, a breaking change bumps the minor version, anything else the patch; bump `version` in `pyproject.toml` and run `uv lock`. Releases are git tags `vX.Y.Z`; publishing a GitHub release uploads to PyPI after CI passes.
+
+**Naming split:** the PyPI distribution is `cmdchain`, the import module is `clichain`; `src/cmdchain/` only re-exports `clichain`. The version is single-sourced in `pyproject.toml` and read via `importlib.metadata.version("cmdchain")` (in `manifest.py`), so it reads `0.0.0` unless the package is installed.
+
+## Commands
+
+```bash
+uv sync                                         # .venv + dev tools from uv.lock (CI uses --locked)
+uv run ruff check src/ tests/ examples/
+uv run ruff format --check src/ tests/ examples/
+uv run basedpyright src/ tests/
+uv run pytest                                   # all tests
+GITHUB_ACTIONS=true CI=true TERM=dumb CLICHAIN_DESCRIBE=json uv run pytest   # must pass too: CI's env
+uv run pytest tests/test_core.py::test_feed     # single test
+uv run coverage run -m pytest && uv run coverage report   # also measures subprocesses
+uv run -p 3.15t pytest                          # free-threaded interpreter
+uv sync --extra compile && uv run pytest tests/test_compile.py   # pyinstaller; skipped without it
+```
+
+Tests are hermetic: `tests/conftest.py` pins every environment variable the library reads (`HERMETIC_ENV`), and `tests/test_environment.py` fails if the library starts reading one that is not pinned. A local pass that differs from CI usually means a new environment dependency. pytest config makes **every warning an error** (so a leaked fd's `ResourceWarning` fails the test) and gives each test a 60 s timeout. `tests/conftest.py` fails any test whose worker threads raised unhandled exceptions, and provides `run_snippet()` for anything that could hang or involves signals: it runs code in a fresh interpreter in its own session and kills the whole session on timeout. CI runs 3.11–3.15 and 3.15t on Ubuntu and macOS, plus an allowed-to-fail 3.16 job; tests shell out to coreutils, so code must work with both GNU and BSD tools.
+
+## Architecture
+
+Flow: `tool()` → immutable `Pipeline` of frozen step dataclasses → `run()` (`pipeline.py`) → `execute()` (`execute.py`) → `Result`.
+
+- **Immutability.** Every builder method returns a new `Pipeline`; `Cmd` is a one-step `Pipeline` whose `__call__` appends args. Steps are frozen, and runtime state (meter stats, captured values, stderr) lives in per-run objects. Pipelines can therefore be shared and run concurrently. `.feed()` / `.from_file()` set the pipeline's stdin (stored at index 0) and a second source raises.
+- **Steps own their description** (`steps.py`): `title()`, `node()` (manifest fields) and the `streamable` class flag. Only `execute.py` knows how to run them. A new step type needs a dataclass there plus handling in `_Run.run_group` (buffered) or `_StreamGroup` (streaming).
+- **Planning** (`execute.plan`): consecutive streamable steps form one group; a `RedirectStep` right after them joins as the group's sink (streams to the file). Every other step is its own buffering boundary; text passes between groups as `str`.
+- **Streaming group** (`_StreamGroup`): processes run in byte mode; Python bridges (filter/peek/meter) are `_Worker` threads processing line batches (`_batches`) and decoding only for callbacks. stderr is drained concurrently into a bounded `_Tail`.
+- **Abandonable pipe I/O:** pipes are unbuffered, and every blocking read or write goes through `_read`/`_send`, which `poll()` and ask the group's `_give_up()`. That returns True once the run is stopped or aborting and none of the group's direct children is alive, so a descendant holding a pipe open can't block teardown. Children deliberately share the terminal's process group (no `process_group=0`), so tty prompts keep working; descendants are not signalled.
+- **Resource invariants (keep them):** every fd has a single owner. The main thread holds it in `owned` until it hands it to a child (and closes its copy) or to a worker (which closes it in `finally`). Never close an fd another thread may use. Stopping signals processes and never closes fds. A worker that stops closes its output first, then its input.
+- **Process supervision** (`process.py`): one `ProcessGroup` per top-level run is shared by nested `each()` runs, including thread-pool workers. `stop(reason, returncode, message)` is thread- and signal-safe (RLock, because a handler can interrupt the main thread mid-critical-section). The first stop decides the Result's returncode and message (timeout → 124); `finish()` makes later stops (a late timer) no-ops. `SignalGuard` installs handlers only on the main thread, skips ignored signals, and after cleanup `deliver()` re-sends the signal to the previous handler (KeyboardInterrupt, default SIGTERM death, or a custom handler → Result 128+n).
+- **Error model:** command and environment failures (exit codes, 127 not found, missing files/dirs → 1, timeouts → 124) become a failed `Result`; exceptions from user callbacks propagate out of `run()` after cleanup; bad definitions (`tool(version="x")`, second source) raise at build time. `run(check=True)` raises `PipelineError`.
+- **Interpolation:** after `.capture(name)`, only `{name}` for names captured so far is replaced (`CmdStep.argv`); other braces are literal.
+- **Version probing** (`checks.detect_version`): only `--version` (or `version_args`), stdin closed, cached per (path, args) under a lock. Unknown version + constraint fails closed. Constraints are parsed at `tool()` time.
+- **Live output** (`live.py`): `run(live=...)` builds a `Console`; the executor only calls `console.job(label)` (per run and per `each()` line), `job.source(label)` (per process, and for teed stdout), `source.write(bytes)` from the stderr drain threads, `source.done(rc)` and `job.finish(rc)`. Mode (capture/lines/grouped/blocks) and unit (job/process: with "process", `job.source()` makes a block of its own) live only in the console. One writer per stream: lines/grouped write whole lines under the console lock; in blocks mode the renderer thread is the only terminal writer and everything else updates the model under the lock. `tty=True` gives a child's stderr a raw pty (never stdout).
+- **Output and records:** `render.py` holds the `set_output` destination (resolved once per run; `run(output=)` overrides) and a global emit lock, plus all explain/report/describe text. `manifest.py` owns the tool/file inventory used by `describe`, `manifest()`, `sbom()` (CycloneDX 1.6) and `report()`. `manifest(redact=True)` strips host details.
+- **Side channels:** `CLICHAIN_DESCRIBE` (`1/true/yes/describe/text` or `json`) makes `run()` print and raise `DescribeExit` (a SystemExit). It is stripped from child envs. `clichain check` uses `dry_run()` (a process-wide flag, so threads the script starts are covered too) so `run()` records instead of executing, and exits 1 on blocking check failures.
+- **Error codes** (`S<signal>` / `X<exit>`): tables live in `errors.py` and are shared by `Result.explain()` and `clichain explain`.