cmdchain 0.1.0__tar.gz → 0.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. cmdchain-0.1.2/PKG-INFO +863 -0
  2. {cmdchain-0.1.0 → cmdchain-0.1.2}/README.md +3 -3
  3. {cmdchain-0.1.0 → cmdchain-0.1.2}/pyproject.toml +3 -2
  4. {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/core.py +52 -12
  5. cmdchain-0.1.2/src/cmdchain/__init__.py +10 -0
  6. {cmdchain-0.1.0 → cmdchain-0.1.2}/tests/test_core.py +3 -1
  7. cmdchain-0.1.0/PKG-INFO +0 -22
  8. {cmdchain-0.1.0 → cmdchain-0.1.2}/.github/workflows/ci.yml +0 -0
  9. {cmdchain-0.1.0 → cmdchain-0.1.2}/.github/workflows/publish.yml +0 -0
  10. {cmdchain-0.1.0 → cmdchain-0.1.2}/.gitignore +0 -0
  11. {cmdchain-0.1.0 → cmdchain-0.1.2}/LICENSE-APACHE +0 -0
  12. {cmdchain-0.1.0 → cmdchain-0.1.2}/LICENSE-MIT +0 -0
  13. {cmdchain-0.1.0 → cmdchain-0.1.2}/benchmarks/bench.py +0 -0
  14. {cmdchain-0.1.0 → cmdchain-0.1.2}/benchmarks/bench_from_file.py +0 -0
  15. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/01_basic_pipe.py +0 -0
  16. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/02_capture_interpolate.py +0 -0
  17. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/03_filter.py +0 -0
  18. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/04_file_io.py +0 -0
  19. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/05_each.py +0 -0
  20. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/06_disk_image.py +0 -0
  21. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/07_video_convert.py +0 -0
  22. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/08_checks.py +0 -0
  23. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/09_meter.py +0 -0
  24. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/10_report_sbom.py +0 -0
  25. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/11_compilable.py +0 -0
  26. {cmdchain-0.1.0 → cmdchain-0.1.2}/examples/12_webhook_metrics.py +0 -0
  27. {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-favicon.svg +0 -0
  28. {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-horizontal-dark.svg +0 -0
  29. {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-horizontal-light.svg +0 -0
  30. {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-logo-dark.svg +0 -0
  31. {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-logo-light.svg +0 -0
  32. {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-mark-dark.svg +0 -0
  33. {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain-mark-light.svg +0 -0
  34. {cmdchain-0.1.0 → cmdchain-0.1.2}/logos/clichain_angular_chain_final.svg +0 -0
  35. {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/__init__.py +0 -0
  36. {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/checks.py +0 -0
  37. {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/cli.py +0 -0
  38. {cmdchain-0.1.0 → cmdchain-0.1.2}/src/clichain/py.typed +0 -0
  39. {cmdchain-0.1.0 → cmdchain-0.1.2}/tests/__init__.py +0 -0
  40. {cmdchain-0.1.0 → cmdchain-0.1.2}/tests/test_compile.py +0 -0
@@ -0,0 +1,863 @@
1
+ Metadata-Version: 2.4
2
+ Name: cmdchain
3
+ Version: 0.1.2
4
+ Summary: Fluent CLI tool chaining for Python
5
+ Author-email: Darcy Luis Neves Bras da Silva <stardevelin@gmail.com>
6
+ License-Expression: MIT OR Apache-2.0
7
+ License-File: LICENSE-APACHE
8
+ License-File: LICENSE-MIT
9
+ Keywords: chain,cli,pipe,subprocess
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: Apache Software License
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.10
21
+ Provides-Extra: compile
22
+ Requires-Dist: pyinstaller>=6.0; extra == 'compile'
23
+ Description-Content-Type: text/markdown
24
+
25
+ <p align="center">
26
+ <picture>
27
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-dark.svg">
28
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-light.svg">
29
+ <img alt="clichain" src="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-dark.svg" width="340">
30
+ </picture>
31
+ </p>
32
+
33
+ <p align="center">
34
+ Fluent CLI tool chaining for Python.<br>
35
+ <code>pip install cmdchain</code>
36
+ </p>
37
+
38
+ <p align="center">
39
+ <a href="https://github.com/dardevelin/clichain/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/dardevelin/clichain/actions/workflows/ci.yml/badge.svg"></a>
40
+ <a href="https://pypi.org/project/cmdchain/"><img alt="PyPI" src="https://img.shields.io/pypi/v/cmdchain"></a>
41
+ <a href="https://pypi.org/project/cmdchain/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/cmdchain"></a>
42
+ <a href="LICENSE-MIT"><img alt="License" src="https://img.shields.io/badge/license-MIT%2FApache--2.0-blue"></a>
43
+ </p>
44
+
45
+ <p align="center">
46
+ <a href="#install">Install</a> &middot;
47
+ <a href="#quickstart">Quickstart</a> &middot;
48
+ <a href="#api-reference">API</a> &middot;
49
+ <a href="#cli">CLI</a> &middot;
50
+ <a href="#performance">Performance</a> &middot;
51
+ <a href="#security">Security</a> &middot;
52
+ <a href="#license">License</a>
53
+ </p>
54
+
55
+ ---
56
+
57
+ clichain replaces bash scripts with typed, inspectable, lazy-evaluated pipelines
58
+ of CLI commands connected by real kernel pipes. Zero runtime dependencies. Python 3.10+.
59
+
60
+ ```bash
61
+ pip install cmdchain
62
+ ```
63
+
64
+ ```python
65
+ from clichain import tool # module name is clichain
66
+
67
+ echo = tool("echo")
68
+ grep = tool("grep")
69
+ sort = tool("sort")
70
+ wc = tool("wc")
71
+
72
+ result = (
73
+ echo("cherry\napple\nbanana\napricot")
74
+ .pipe(grep("a"))
75
+ .pipe(sort())
76
+ .pipe(wc("-l"))
77
+ .run()
78
+ )
79
+
80
+ print(result.stdout.strip()) # 3
81
+ ```
82
+
83
+ Nothing executes until `.run()`. The chain is data -- a list of step descriptions
84
+ that can be inspected, validated, and reused before any process spawns.
85
+
86
+ ## Why not bash?
87
+
88
+ Bash works. Until it doesn't. Quoting breaks, error handling is `set -e` and hope,
89
+ debugging is `echo` statements, and CI failures give you exit code 1 with no context.
90
+
91
+ clichain gives you the same pipe-based execution model with:
92
+
93
+ - **Type safety** -- args are lists, never shell-interpreted
94
+ - **Streaming** -- kernel pipes between commands, same as bash `|`
95
+ - **Preflight checks** -- verify tools exist and versions match before execution
96
+ - **Error diagnostics** -- error codes, execution traces, source locations
97
+ - **Profiling** -- time, lines, bytes, spawns per step
98
+ - **SBOM** -- full bill of materials for every execution
99
+ - **Compilation** -- bundle scripts to single binaries for CI
100
+
101
+ ## Install
102
+
103
+ The PyPI package name is **cmdchain**, the Python module is **clichain**.
104
+
105
+ ```bash
106
+ pip install cmdchain
107
+ ```
108
+
109
+ ```python
110
+ from clichain import tool
111
+ ```
112
+
113
+ Zero runtime dependencies. Python 3.10+ only.
114
+
115
+ For compiling scripts to standalone binaries:
116
+
117
+ ```bash
118
+ pip install cmdchain[compile]
119
+ ```
120
+
121
+ ## Development setup
122
+
123
+ Clone the repository and install in editable mode with dev tooling:
124
+
125
+ ```bash
126
+ git clone https://github.com/dardevelin/clichain.git
127
+ cd clichain
128
+ python -m venv .venv
129
+ source .venv/bin/activate # or .venv\Scripts\activate on Windows
130
+ pip install -e .
131
+ pip install --dependency-group dev
132
+ ```
133
+
134
+ This gives you:
135
+ - **pytest** -- test runner (`python -m pytest`)
136
+ - **ruff** -- linter and formatter (`ruff check src/ tests/` and `ruff format src/ tests/`)
137
+ - **basedpyright** -- type checker
138
+
139
+ Run the full check suite:
140
+
141
+ ```bash
142
+ ruff check src/ tests/ # lint
143
+ ruff format --check src/ tests/ # format check
144
+ python -m pytest tests/ # unit tests (62 tests)
145
+ ```
146
+
147
+ Compile end-to-end tests require pyinstaller and are skipped by default:
148
+
149
+ ```bash
150
+ pip install cmdchain[compile]
151
+ python -m pytest tests/test_compile.py # compile + run binary tests
152
+ ```
153
+
154
+ ### Project structure
155
+
156
+ ```
157
+ src/clichain/
158
+ __init__.py # public API: tool, Cmd, Pipeline, Result, set_output
159
+ core.py # steps, pipeline execution, streaming, profiling, SBOM
160
+ checks.py # preflight checks: binary, env, file_exists
161
+ cli.py # CLI: explain, check, compile
162
+ py.typed # PEP 561 typed package marker
163
+ tests/
164
+ test_core.py # unit tests for all primitives
165
+ test_compile.py # end-to-end compile tests (requires pyinstaller)
166
+ examples/ # runnable examples covering all features
167
+ benchmarks/ # performance comparisons vs bash
168
+ ```
169
+
170
+ ## Quickstart
171
+
172
+ ### Basic pipe
173
+
174
+ ```python
175
+ from clichain import tool
176
+
177
+ echo = tool("echo")
178
+ grep = tool("grep")
179
+
180
+ result = echo("hello\nworld").pipe(grep("hello")).run()
181
+ print(result.stdout) # hello\n
182
+ print(result.ok) # True
183
+ ```
184
+
185
+ ### Multi-stage pipe
186
+
187
+ Consecutive `.pipe()` calls are connected by kernel pipes -- all processes run concurrently,
188
+ data streams through without Python buffering:
189
+
190
+ ```python
191
+ result = (
192
+ echo("foo\nbar\nbaz")
193
+ .pipe(grep("ba"))
194
+ .pipe(sort())
195
+ .pipe(wc("-l"))
196
+ .run()
197
+ )
198
+ ```
199
+
200
+ ### Adding arguments
201
+
202
+ `tool()` returns a callable. Call it with arguments to get a command ready to execute:
203
+
204
+ ```python
205
+ grep = tool("grep")
206
+
207
+ # These are equivalent:
208
+ grep("-r", "-i", "pattern", ".")
209
+ grep("-ri", "pattern", ".")
210
+ ```
211
+
212
+ Arguments are passed as a list to `subprocess.Popen` -- never through a shell.
213
+ No quoting issues, no injection.
214
+
215
+ ### Capture and interpolate
216
+
217
+ Capture a step's output and reference it in later arguments with `{name}`:
218
+
219
+ ```python
220
+ pwd = tool("pwd")
221
+ ls = tool("ls")
222
+
223
+ result = (
224
+ pwd()
225
+ .capture("cwd")
226
+ .pipe(ls("{cwd}"))
227
+ .run()
228
+ )
229
+ ```
230
+
231
+ `.capture()` buffers the output and strips whitespace. `{name}` uses Python's
232
+ `str.format_map()` for substitution. Only the final output of a piped group
233
+ can be captured.
234
+
235
+ ### Filter with Python logic
236
+
237
+ `.filter()` receives each line (stripped of newline), keeps lines where the function returns True.
238
+ It streams line-by-line through a thread -- no full buffering:
239
+
240
+ ```python
241
+ ls = tool("ls")
242
+ wc = tool("wc")
243
+
244
+ result = (
245
+ ls(".")
246
+ .filter(lambda f: f.endswith(".py"))
247
+ .pipe(wc("-l"))
248
+ .run()
249
+ )
250
+ ```
251
+
252
+ Filters can be chained:
253
+
254
+ ```python
255
+ result = (
256
+ echo("1\n2\n3\n4\n5")
257
+ .filter(lambda line: int(line) > 2)
258
+ .filter(lambda line: int(line) < 5)
259
+ .run()
260
+ )
261
+ # result.lines == ["3", "4"]
262
+ ```
263
+
264
+ ### Peek
265
+
266
+ Observe data flowing through without modifying it. Useful for debugging:
267
+
268
+ ```python
269
+ seen = []
270
+ result = (
271
+ echo("hello\nworld")
272
+ .peek(fn=lambda line: seen.append(line))
273
+ .pipe(wc("-l"))
274
+ .run()
275
+ )
276
+ # seen == ["hello\n", "world\n"]
277
+ # result.stdout.strip() == "2" -- data passed through unchanged
278
+ ```
279
+
280
+ With a label (prints to the configured output destination):
281
+
282
+ ```python
283
+ .peek(label="after filter")
284
+ # [after filter] hello
285
+ # [after filter] world
286
+ ```
287
+
288
+ ### Feed
289
+
290
+ Provide a string as stdin to the first command:
291
+
292
+ ```python
293
+ sort = tool("sort")
294
+
295
+ result = sort().feed("cherry\napple\nbanana\n").run()
296
+ # result.lines == ["apple", "banana", "cherry"]
297
+ ```
298
+
299
+ ### File I/O
300
+
301
+ **Read from file** -- the file descriptor is passed directly to the process.
302
+ The kernel handles buffering, no Python overhead:
303
+
304
+ ```python
305
+ sort = tool("sort")
306
+
307
+ # bash: sort < input.txt
308
+ sort().from_file("input.txt").run()
309
+ ```
310
+
311
+ With explicit block size -- a thread reads N bytes at a time.
312
+ Useful when Python needs to mediate (e.g., meter on binary data).
313
+ ~5-10% throughput cost vs kernel mode:
314
+
315
+ ```python
316
+ sort().from_file("large.bin", block_size=65536).run()
317
+ ```
318
+
319
+ **Write to file:**
320
+
321
+ ```python
322
+ echo = tool("echo")
323
+ sort = tool("sort")
324
+ make = tool("make")
325
+
326
+ # bash: sort < input.txt > output.txt
327
+ sort().from_file("input.txt").redirect(stdout="output.txt").run()
328
+
329
+ # Append mode: >>
330
+ echo("new line").redirect(stdout="log.txt", append=True).run()
331
+
332
+ # Separate stderr:
333
+ make().redirect(stdout="build.log", stderr="errors.log").run()
334
+ ```
335
+
336
+ ### Merge stderr
337
+
338
+ Combine stderr into stdout (bash `2>&1`):
339
+
340
+ ```python
341
+ bash = tool("bash")
342
+ result = bash("-c", "echo out; echo err >&2").merge_stderr().run()
343
+ # result.stdout contains both "out" and "err"
344
+ ```
345
+
346
+ ### Collect
347
+
348
+ Explicit buffering boundary. Forces all data to be collected in memory before
349
+ the next step proceeds:
350
+
351
+ ```python
352
+ echo = tool("echo")
353
+ result = echo("hello").collect().run()
354
+ ```
355
+
356
+ Most useful before `.each()` when you want to ensure all input is gathered
357
+ before spawning per-line commands.
358
+
359
+ ### Per-line execution with each
360
+
361
+ `.each()` runs a command for every line of input. Each line becomes different arguments --
362
+ a separate process per line:
363
+
364
+ ```python
365
+ find = tool("find")
366
+ ffmpeg = tool("ffmpeg")
367
+
368
+ # Convert all .mkv files to .mp3
369
+ (
370
+ find(".", "-name", "*.mkv")
371
+ .each(lambda f: ffmpeg("-i", f, "-vn", f.replace(".mkv", ".mp3")))
372
+ .run()
373
+ )
374
+ ```
375
+
376
+ **Parallel execution** with `workers`:
377
+
378
+ ```python
379
+ # 4 ffmpeg processes at a time
380
+ .each(lambda f: ffmpeg("-i", f, "-vn", f + ".mp3"), workers=4)
381
+ ```
382
+
383
+ `.each()` stops on first failure -- remaining lines are skipped.
384
+
385
+ **When to use `.each()` vs `.pipe()`:**
386
+ - `.each()` -- command args change per line (different `-i` file each time)
387
+ - `.pipe()` -- command reads stdin line by line (grep, sort, awk)
388
+
389
+ `.pipe()` is one process, streaming. `.each()` is one process per line.
390
+
391
+ ### Meter
392
+
393
+ Count bytes and lines flowing through the pipeline. Streams line-by-line,
394
+ reports throughput periodically:
395
+
396
+ ```python
397
+ seq = tool("seq")
398
+ sort = tool("sort")
399
+ wc = tool("wc")
400
+
401
+ result = (
402
+ seq("1000000")
403
+ .meter(label="raw")
404
+ .pipe(sort("-rn"))
405
+ .meter(label="sorted")
406
+ .pipe(wc("-l"))
407
+ .run()
408
+ )
409
+ ```
410
+
411
+ Parameters:
412
+ - `label` -- prefix for the output
413
+ - `interval` -- seconds between reports (default `1.0`, use `0` for every line)
414
+ - `to` -- custom destination: `None` (uses configured output), a callable receiving `MeterStats`, or a file-like object
415
+
416
+ ```python
417
+ # Custom callback -- collect stats programmatically
418
+ stats_log = []
419
+ echo("a\nb\nc").meter(to=lambda stats: stats_log.append(stats), interval=0).run()
420
+
421
+ # MeterStats fields:
422
+ # stats.label str
423
+ # stats.bytes int -- total bytes seen
424
+ # stats.lines int -- total lines seen
425
+ # stats.elapsed float -- seconds since start
426
+ # stats.bytes_per_sec float
427
+ # stats.lines_per_sec float
428
+ ```
429
+
430
+ When a meter is present, the execution report includes a bytes column.
431
+ Without meter, the column is hidden -- no overhead unless you ask for it.
432
+
433
+ ### Version constraints
434
+
435
+ ```python
436
+ ffmpeg = tool("ffmpeg", version=">=6.0", msg="brew install ffmpeg")
437
+ jq = tool("jq", version=">=1.7")
438
+ ```
439
+
440
+ **`tool()` parameters:**
441
+ - `name` -- binary name (looked up on `$PATH`)
442
+ - `version` -- semver constraint. Supports `>=`, `<=`, `>`, `<`, `==` and comma-separated combinations like `>=6.0,<8.0`
443
+ - `on_fail` -- what to do if the check fails: `"error"` (default, stops execution), `"warn"` (logs, continues), `"pass"` (silent, continues)
444
+ - `msg` -- custom message shown on failure
445
+
446
+ Version detection tries `--version`, `-version`, `version`, `-v` flags in order
447
+ and regex-matches the first semver string from the output.
448
+
449
+ ### Preflight checks
450
+
451
+ Binary checks run automatically before execution by default. You can also add
452
+ custom checks for environment variables, files, or arbitrary conditions:
453
+
454
+ ```python
455
+ from clichain import env, file_exists
456
+
457
+ result = pipeline.run(pre=[
458
+ env("API_KEY", on_fail="error", msg="set in .env"),
459
+ env("DEBUG", on_fail="warn"),
460
+ file_exists("input.mkv"),
461
+ ])
462
+ ```
463
+
464
+ **Check levels:**
465
+ | Level | Stops execution | Shows message |
466
+ |---|---|---|
467
+ | `error` | yes | yes |
468
+ | `warn` | no | yes |
469
+ | `pass` | no | no |
470
+
471
+ **Skip all validation:**
472
+
473
+ ```python
474
+ result = pipeline.run(validate=False)
475
+ ```
476
+
477
+ **Check without running:**
478
+
479
+ ```python
480
+ checks = pipeline.check() # returns list[CheckResult]
481
+ for c in checks:
482
+ print(c.ok, c.name, c.found, c.msg)
483
+ ```
484
+
485
+ `CheckResult` fields: `ok`, `name`, `expected`, `found`, `msg`, `on_fail`.
486
+
487
+ ## API reference
488
+
489
+ ### tool()
490
+
491
+ ```python
492
+ tool(
493
+ name: str,
494
+ version: str | None = None,
495
+ on_fail: "error" | "warn" | "pass" = "error",
496
+ msg: str = "",
497
+ ) -> Cmd
498
+ ```
499
+
500
+ Creates a command wrapper for a binary. Call the result with arguments:
501
+
502
+ ```python
503
+ grep = tool("grep")
504
+ grep("-ri", "pattern", ".") # returns a new Cmd with those args
505
+ ```
506
+
507
+ ### Pipeline primitives
508
+
509
+ | Method | What it does | Streaming |
510
+ |---|---|---|
511
+ | `.pipe(cmd)` | Connect stdout to stdin via kernel pipe | yes |
512
+ | `.filter(fn)` | Keep lines where `fn(line)` is True | yes, via thread |
513
+ | `.each(fn, workers=1)` | Run command per input line, stops on first failure | per-line spawn |
514
+ | `.peek(label=, fn=)` | Observe data without modifying | yes, via thread |
515
+ | `.meter(label=, to=, interval=1.0)` | Count bytes/lines, report throughput | yes, via thread |
516
+ | `.collect()` | Explicit buffering boundary | no |
517
+ | `.capture(name)` | Buffer and bind to `{name}` for interpolation | no |
518
+ | `.feed(data)` | String as stdin (inserted at start) | no |
519
+ | `.from_file(path, block_size=0)` | File as stdin (`0` = kernel, `N` = chunked thread) | yes |
520
+ | `.redirect(stdout=, stderr=, append=False)` | Write to file | yes |
521
+ | `.merge_stderr()` | Combine stderr into stdout (2>&1) | yes |
522
+
523
+ ### Execution and inspection
524
+
525
+ | Method | What it does |
526
+ |---|---|
527
+ | `.run(validate=True, pre=None)` | Execute pipeline, returns `Result` |
528
+ | `.check()` | Validate binaries exist, returns `list[CheckResult]` |
529
+ | `.describe()` | Print steps and requirements without executing |
530
+
531
+ ### Result
532
+
533
+ ```python
534
+ result = pipeline.run()
535
+
536
+ # Status
537
+ result.ok # bool: returncode == 0
538
+ result.returncode # int: exit code or negative signal number
539
+ result.stdout # str: captured output
540
+ result.stderr # str: captured errors
541
+ result.lines # list[str]: stdout split by newline, stripped
542
+
543
+ # Diagnostics
544
+ result.checks # list[CheckResult]: preflight results
545
+ result.profile # list[StepProfile]: timing per step group
546
+ result.elapsed # float: total seconds
547
+
548
+ # Methods
549
+ result.report() # print full execution report
550
+ result.explain() # print error diagnosis with trace
551
+ result.sbom() # dict: software bill of materials
552
+ result.sbom_json(indent=2) # str: SBOM as JSON
553
+ ```
554
+
555
+ **`StepProfile` fields:**
556
+ - `name` -- step group description
557
+ - `elapsed` -- seconds
558
+ - `lines_in`, `lines_out` -- line counts at group boundaries
559
+ - `spawns` -- number of processes created
560
+ - `bytes_in`, `bytes_out` -- byte counts (only when `.meter()` is present, otherwise `None`)
561
+
562
+ ### Output control
563
+
564
+ ```python
565
+ import sys
566
+ import logging
567
+ import clichain
568
+
569
+ clichain.set_output(sys.stderr) # default -- stderr
570
+ clichain.set_output(None) # silent -- no output
571
+ clichain.set_output(logging.info) # callable -- receives each line as a string
572
+ clichain.set_output(open("log.txt", "a")) # file-like -- anything with .write()
573
+ ```
574
+
575
+ All library output goes through this single destination: check results, peek output,
576
+ meter stats, reports, and error explanations. Set once at the top of your script.
577
+
578
+ ### Describe
579
+
580
+ Inspect what a pipeline will do without executing:
581
+
582
+ ```python
583
+ pipeline.describe()
584
+ ```
585
+
586
+ ```
587
+ ========================================================================
588
+ pipeline: 3 steps
589
+ ------------------------------------------------------------------------
590
+ [0] FromFile < input.txt
591
+ [1] Cmd sort
592
+ [2] Cmd wc -l
593
+ ------------------------------------------------------------------------
594
+ requires:
595
+ sort /usr/bin/sort ok
596
+ wc /usr/bin/wc ok
597
+ ------------------------------------------------------------------------
598
+ < input.txt
599
+ ========================================================================
600
+ ```
601
+
602
+ Available via environment variable -- works with compiled binaries:
603
+
604
+ ```bash
605
+ CLICHAIN_DESCRIBE=describe ./my_binary # human-readable
606
+ CLICHAIN_DESCRIBE=json ./my_binary # machine-readable JSON
607
+ ```
608
+
609
+ The JSON output includes generator info, environment (OS, arch), steps with types and names,
610
+ tools with paths/versions/found status, and files read/written.
611
+
612
+ ### Error diagnostics
613
+
614
+ ```python
615
+ result.explain()
616
+ ```
617
+
618
+ ```
619
+ error[S13]: signal 13 (SIGPIPE: broken pipe -- downstream closed
620
+ before upstream finished)
621
+
622
+ execution trace:
623
+ [0] Cmd seq 100000
624
+ [1] Filter filter at script.py:12
625
+ [2] Cmd sort -rn <--
626
+ [3] Cmd head -10
627
+ [4] Cmd wc -l
628
+
629
+ source: script.py:15
630
+
631
+ This usually means a downstream command (like head or grep -m)
632
+ closed its input before the upstream command finished writing.
633
+ This is often normal behavior, not a real error.
634
+ ```
635
+
636
+ The execution trace shows every step, marks the failure with `<--`, and includes
637
+ source locations for Python callables (filter/each lambdas) and the `.run()` call site.
638
+
639
+ Error codes follow the pattern `S{n}` for signals, `X{n}` for exit codes.
640
+ Each has a registry entry with a detailed explanation:
641
+
642
+ | Code | Meaning |
643
+ |---|---|
644
+ | `S2` | SIGINT -- interrupted (ctrl+c) |
645
+ | `S9` | SIGKILL -- killed (OOM killer, timeout) |
646
+ | `S11` | SIGSEGV -- segmentation fault (bug in the tool) |
647
+ | `S13` | SIGPIPE -- broken pipe (downstream closed early) |
648
+ | `S15` | SIGTERM -- terminated (process manager, CI shutdown) |
649
+ | `X1` | General error -- check stderr |
650
+ | `X2` | Invalid arguments |
651
+ | `X126` | Permission denied -- binary not executable |
652
+ | `X127` | Command not found |
653
+
654
+ ### Execution report
655
+
656
+ ```python
657
+ result.report()
658
+ ```
659
+
660
+ ```
661
+ ========================================================================
662
+ clichain 0.1.0 | python 3.14.3 | Darwin 25.4.0 arm64
663
+ hostname /path/to/project
664
+ 2026-04-02T08:56:47.959010+00:00
665
+ OK 0.0069s
666
+ ========================================================================
667
+ tool version path
668
+ ------------------------------------------------------------------------
669
+ sort 2.3 /usr/bin/sort
670
+ uniq - /usr/bin/uniq
671
+ ------------------------------------------------------------------------
672
+ < /tmp/input.txt
673
+ > /tmp/output.txt
674
+ ------------------------------------------------------------------------
675
+ # time in out spawn command
676
+ ------------------------------------------------------------------------
677
+ 0 0.007s 0 3 3 < input.txt | sort | uniq -c
678
+ | sort -rn
679
+ 1 0.000s 3 3 0 redirect > output.txt
680
+ ------------------------------------------------------------------------
681
+ 0.007s total
682
+ ------------------------------------------------------------------------
683
+ [ok] sort: /usr/bin/sort
684
+ [ok] uniq: /usr/bin/uniq
685
+ ========================================================================
686
+ ```
687
+
688
+ Long command chains wrap at pipe (`|`) boundaries to stay within 72 columns.
689
+ When `.meter()` is present, a bytes column appears in the profile table.
690
+
691
+ ### SBOM
692
+
693
+ Every execution produces a software bill of materials:
694
+
695
+ ```python
696
+ result.sbom() # dict
697
+ result.sbom_json() # formatted JSON string
698
+ result.sbom_json(indent=4) # custom indentation
699
+ ```
700
+
701
+ ```json
702
+ {
703
+ "generator": {
704
+ "name": "clichain",
705
+ "version": "0.1.0",
706
+ "python": "3.14.3"
707
+ },
708
+ "environment": {
709
+ "os": "Darwin",
710
+ "os_version": "25.4.0",
711
+ "arch": "arm64",
712
+ "hostname": "build-runner-01",
713
+ "cwd": "/home/ci/project"
714
+ },
715
+ "timestamp": "2026-04-02T08:40:24.941071+00:00",
716
+ "elapsed": 0.0086,
717
+ "exit_code": 0,
718
+ "tools": [
719
+ {"name": "sort", "path": "/usr/bin/sort", "version": "2.3"},
720
+ {"name": "wc", "path": "/usr/bin/wc"}
721
+ ],
722
+ "files_read": ["/tmp/input.txt"],
723
+ "files_written": ["/tmp/output.txt"],
724
+ "call_tree": [
725
+ {"step": 0, "type": "FromFileStep", "path": "/tmp/input.txt"},
726
+ {"step": 1, "type": "CmdStep", "cmd": "sort"},
727
+ {"step": 2, "type": "CmdStep", "cmd": "wc -l"},
728
+ {"step": 3, "type": "RedirectStep", "stdout": "/tmp/output.txt"}
729
+ ]
730
+ }
731
+ ```
732
+
733
+ ## CLI
734
+
735
+ ```bash
736
+ clichain explain S13 # explain an error code
737
+ clichain check script.py # preflight all tools in a script
738
+ clichain compile script.py # bundle to standalone binary
739
+ clichain compile script.py -o name --clean
740
+ ```
741
+
742
+ ### explain
743
+
744
+ Look up any error code interactively:
745
+
746
+ ```bash
747
+ $ clichain explain X127
748
+ error[X127]: exit 127
749
+ command not found
750
+
751
+ The binary was not found in any directory listed in $PATH.
752
+ Check that the tool is installed and its location is in your PATH.
753
+ ```
754
+
755
+ ### check
756
+
757
+ Preflight a script -- imports the module and validates all `tool()` declarations:
758
+
759
+ ```bash
760
+ $ clichain check my_pipeline.py
761
+ tool: ffmpeg (ffmpeg)
762
+ ok: ffmpeg (7.0.1 at /usr/bin/ffmpeg)
763
+ tool: jq (jq)
764
+ error: jq — jq not found on $PATH
765
+ ```
766
+
767
+ Note: `clichain check` executes the script to discover tools. Only run on trusted code.
768
+
769
+ ### compile
770
+
771
+ Bundle a clichain script to a standalone binary. Requires `pip install cmdchain[compile]`.
772
+
773
+ ```bash
774
+ clichain compile my_pipeline.py -o my_pipeline
775
+ clichain compile my_pipeline.py -o my_pipeline --clean # clean build artifacts
776
+ ```
777
+
778
+ The compiled binary supports `CLICHAIN_DESCRIBE`:
779
+
780
+ ```bash
781
+ ./my_pipeline # runs normally
782
+ CLICHAIN_DESCRIBE=describe ./my_pipeline # shows requirements
783
+ CLICHAIN_DESCRIBE=json ./my_pipeline # JSON description
784
+ ```
785
+
786
+ ## Streaming architecture
787
+
788
+ Consecutive commands connected by `.pipe()` run as concurrent OS processes linked by kernel pipes.
789
+ Data flows in ~64KB chunks managed by the kernel -- Python never touches it:
790
+
791
+ ```
792
+ [echo ...] --kernel pipe--> [grep ...] --kernel pipe--> [sort] --kernel pipe--> [wc -l]
793
+ ```
794
+
795
+ When a Python step (`.filter()`, `.peek()`, `.meter()`) sits between commands, clichain creates
796
+ an OS pipe pair and runs a thread to bridge them. The thread reads lines from the upstream pipe,
797
+ processes them, and writes to the downstream pipe:
798
+
799
+ ```
800
+ [echo ...] --kernel pipe--> [thread: filter(fn)] --os pipe--> [wc -l]
801
+ ```
802
+
803
+ Steps that require all data before proceeding are explicit buffering boundaries:
804
+ - `.collect()` -- explicit
805
+ - `.capture()` -- needs full output to store
806
+ - `.each()` -- needs lines to iterate
807
+
808
+ The pipeline planner groups consecutive streamable steps (commands, filters, peeks, meters)
809
+ together so they run as a single streaming unit. Non-streamable steps force a boundary
810
+ between groups.
811
+
812
+ ## Performance
813
+
814
+ Benchmarked against equivalent bash on macOS arm64:
815
+
816
+ | Workload | bash | clichain | ratio |
817
+ |---|---|---|---|
818
+ | 3-stage pipe | 9.1ms | 6.6ms | 0.73x |
819
+ | 4-stage pipe | 8.5ms | 7.8ms | 0.92x |
820
+ | Python filter between cmds | 35.5ms | 18.2ms | 0.51x |
821
+ | 1M lines through pipes | 123ms | 117ms | 0.96x |
822
+ | Feed + sort 10k lines | 13.8ms | 5.7ms | 0.42x |
823
+
824
+ Streaming pipes are on par or faster than bash.
825
+
826
+ `.each()` spawns a process per line -- inherently expensive. Use `workers=N` for parallelism,
827
+ or `.pipe()` when the tool reads stdin (one process, streaming).
828
+
829
+ `from_file(block_size=0)` (default) matches native bash `< file` redirection.
830
+ `block_size=N` adds ~5-10% overhead for the control it provides.
831
+
832
+ ## Security
833
+
834
+ clichain has the same trust model as bash: you trust the commands you run and the inputs
835
+ you provide. The difference is clichain makes that trust boundary visible and auditable.
836
+
837
+ **By design:**
838
+
839
+ - Commands are passed as argument lists to `subprocess.Popen`, never through `shell=True`
840
+ - `from_file()` and `redirect()` operate on any path the process has access to -- no sandboxing
841
+ - `{name}` interpolation inserts captured values as literal arguments, not shell expressions. If captured data comes from untrusted sources, the values become arguments to downstream commands
842
+ - All spawned processes inherit the parent environment including sensitive variables
843
+ - `sbom()` and `report()` include host-identifying information (hostname, cwd, tool paths)
844
+ - `clichain check` executes the target script to discover tools -- only run on trusted code
845
+ - Version detection (`--version`) executes binaries during preflight
846
+
847
+ **Process management:**
848
+
849
+ On SIGINT/SIGTERM, clichain terminates all child processes gracefully (SIGTERM, 5s grace period,
850
+ SIGKILL), joins threads, and closes file handles. No orphan processes. Signal handlers are only
851
+ installed on the main thread.
852
+
853
+ ## Future
854
+
855
+ The following features are being considered based on demand:
856
+
857
+ - **Plugin system** -- typed wrappers for specific tools with autocomplete and version-aware flag mapping
858
+ - **`from_bash`** -- parse bash one-liners into clichain pipelines (dev-only migration tool)
859
+ - **Stub generation** -- `.pyi` stubs from `$PATH` scanning for IDE autocomplete
860
+
861
+ ## License
862
+
863
+ Dual licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at your option.
@@ -1,8 +1,8 @@
1
1
  <p align="center">
2
2
  <picture>
3
- <source media="(prefers-color-scheme: dark)" srcset="logos/clichain-horizontal-dark.svg">
4
- <source media="(prefers-color-scheme: light)" srcset="logos/clichain-horizontal-light.svg">
5
- <img alt="clichain" src="logos/clichain-horizontal-dark.svg" width="340">
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-dark.svg">
4
+ <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-light.svg">
5
+ <img alt="clichain" src="https://raw.githubusercontent.com/dardevelin/clichain/main/logos/clichain-horizontal-dark.svg" width="340">
6
6
  </picture>
7
7
  </p>
8
8
 
@@ -4,8 +4,9 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "cmdchain"
7
- version = "0.1.0"
7
+ version = "0.1.2"
8
8
  description = "Fluent CLI tool chaining for Python"
9
+ readme = "README.md"
9
10
  requires-python = ">=3.10"
10
11
  license = "MIT OR Apache-2.0"
11
12
  keywords = ["cli", "subprocess", "pipe", "chain"]
@@ -41,7 +42,7 @@ dev = [
41
42
  ]
42
43
 
43
44
  [tool.hatch.build.targets.wheel]
44
- packages = ["src/clichain"]
45
+ packages = ["src/clichain", "src/cmdchain"]
45
46
 
46
47
  [tool.ruff]
47
48
  target-version = "py310"
@@ -157,9 +157,11 @@ class Result:
157
157
  sep = "=" * W
158
158
  div = "-" * W
159
159
  v, py = gen["version"], gen["python"]
160
+ commit = gen.get("commit", "")
161
+ ver = f"{v} ({commit})" if commit else v
160
162
  plat = f"{env['os']} {env['os_version']} {env['arch']}"
161
163
  _emit(sep)
162
- _emit(f" clichain {v} | python {py} | {plat}")
164
+ _emit(f" clichain {ver} | python {py} | {plat}")
163
165
  _emit(f" {env['hostname']} {env['cwd']}")
164
166
  _emit(f" {data['timestamp']}")
165
167
  _emit(f" {status} {data['elapsed']}s")
@@ -315,12 +317,16 @@ class Result:
315
317
 
316
318
  import platform
317
319
 
320
+ gen: dict = {
321
+ "name": "clichain",
322
+ "version": _version,
323
+ "python": sys.version.split()[0],
324
+ }
325
+ if _git_hash:
326
+ gen["commit"] = _git_hash
327
+
318
328
  sbom: dict = {
319
- "generator": {
320
- "name": "clichain",
321
- "version": _version,
322
- "python": sys.version.split()[0],
323
- },
329
+ "generator": gen,
324
330
  "environment": {
325
331
  "os": platform.system(),
326
332
  "os_version": platform.release(),
@@ -484,7 +490,37 @@ def _explain_exit(code: int) -> str:
484
490
 
485
491
 
486
492
  _output: IO[str] | Callable[[str], None] | None = sys.stderr
487
- _version: str = "0.1.0"
493
+ _git_hash: str = ""
494
+
495
+
496
+ def _get_version() -> str:
497
+ try:
498
+ from importlib.metadata import version
499
+
500
+ return version("cmdchain")
501
+ except Exception:
502
+ return "0.0.0"
503
+
504
+
505
+ _version: str = _get_version()
506
+
507
+
508
+ def _detect_git_hash() -> str:
509
+ try:
510
+ result = subprocess.run(
511
+ ["git", "rev-parse", "--short", "HEAD"],
512
+ capture_output=True,
513
+ text=True,
514
+ timeout=2,
515
+ )
516
+ if result.returncode == 0:
517
+ return result.stdout.strip()
518
+ except (FileNotFoundError, subprocess.TimeoutExpired):
519
+ pass
520
+ return ""
521
+
522
+
523
+ _git_hash = _detect_git_hash()
488
524
 
489
525
 
490
526
  def set_output(dest: IO[str] | Callable[[str], None] | None) -> None:
@@ -1029,12 +1065,16 @@ class Pipeline:
1029
1065
  }
1030
1066
  steps.append(node)
1031
1067
 
1068
+ desc_gen: dict = {
1069
+ "name": "clichain",
1070
+ "version": _version,
1071
+ "python": sys.version.split()[0],
1072
+ }
1073
+ if _git_hash:
1074
+ desc_gen["commit"] = _git_hash
1075
+
1032
1076
  result: dict = {
1033
- "generator": {
1034
- "name": "clichain",
1035
- "version": _version,
1036
- "python": sys.version.split()[0],
1037
- },
1077
+ "generator": desc_gen,
1038
1078
  "environment": {
1039
1079
  "os": platform.system(),
1040
1080
  "arch": platform.machine(),
@@ -0,0 +1,10 @@
1
+ """cmdchain — alias for clichain.
2
+
3
+ pip install cmdchain
4
+ from clichain import tool # preferred
5
+ from cmdchain import tool # also works
6
+ """
7
+
8
+ from clichain import * # noqa: F403
9
+ from clichain import __all__ as __all__
10
+ from clichain import __version__ as __version__
@@ -425,7 +425,9 @@ def test_sbom_generator():
425
425
  sbom = result.sbom()
426
426
  assert "generator" in sbom
427
427
  assert sbom["generator"]["name"] == "clichain"
428
- assert sbom["generator"]["version"] == "0.1.0"
428
+ from clichain.core import _version
429
+
430
+ assert sbom["generator"]["version"] == _version
429
431
  assert "python" in sbom["generator"]
430
432
 
431
433
 
cmdchain-0.1.0/PKG-INFO DELETED
@@ -1,22 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: cmdchain
3
- Version: 0.1.0
4
- Summary: Fluent CLI tool chaining for Python
5
- Author-email: Darcy Luis Neves Bras da Silva <stardevelin@gmail.com>
6
- License-Expression: MIT OR Apache-2.0
7
- License-File: LICENSE-APACHE
8
- License-File: LICENSE-MIT
9
- Keywords: chain,cli,pipe,subprocess
10
- Classifier: Development Status :: 3 - Alpha
11
- Classifier: Intended Audience :: Developers
12
- Classifier: License :: OSI Approved :: Apache Software License
13
- Classifier: License :: OSI Approved :: MIT License
14
- Classifier: Programming Language :: Python :: 3
15
- Classifier: Programming Language :: Python :: 3.10
16
- Classifier: Programming Language :: Python :: 3.11
17
- Classifier: Programming Language :: Python :: 3.12
18
- Classifier: Programming Language :: Python :: 3.13
19
- Classifier: Typing :: Typed
20
- Requires-Python: >=3.10
21
- Provides-Extra: compile
22
- Requires-Dist: pyinstaller>=6.0; extra == 'compile'
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes