toolrack-cli 0.1.0__py3-none-any.whl

toolrack_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: toolrack-cli
+Version: 0.1.0
+Summary: Turn a folder of small scripts plus YAML sidecars into one typed, completable CLI
+Author: Jan Chimiak
+License-Expression: MIT
+Project-URL: Repository, https://github.com/anfit/toolrack
+Project-URL: Template, https://github.com/anfit/toolrack-template
+Keywords: cli,scripts,click,dispatcher,shell-completion
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# toolrack
+
+`toolrack` is the dispatcher engine behind a user-owned scripts repository.
+It reads a registry of script paths, loads YAML sidecars beside those scripts,
+and builds a typed Click CLI at runtime.
+
+If you want the starter repository that uses this engine, see
+[`toolrack-template`](https://github.com/anfit/toolrack-template).
+
+![Animated toolrack walkthrough: register, discover, and run scripts](docs/assets/toolrack-demo.gif)
+
+## Quickstart
+
+```sh
+git clone https://github.com/anfit/toolrack-template my-tools
+cd my-tools
+python setup_toolrack.py   # venv, installs toolrack-cli from PyPI, wrappers, PATH, completion
+```
+
+The engine is published on PyPI as `toolrack-cli`; the command it installs is
+`toolrack`. To work on the engine itself, clone this repo and pass
+`--toolrack ../toolrack` to the setup script for an editable install.
+
+Open a new shell, then add a script and its sidecar:
+
+```python
+# scripts/hello/greet.py
+import sys
+print(f"Hello, {sys.argv[1]}!")
+```
+
+```yaml
+# scripts/hello/greet.yml
+description: Print a greeting.
+args:
+  - name: name
+    positional: true
+    required: true
+    help: Who to greet.
+```
+
+```sh
+my-tools core register scripts/hello/greet.py
+my-tools hello greet Alice        # -> Hello, Alice!
+my-tools hello <TAB>              # completes commands, options and choices
+```
+
+## Why This Exists
+
+AI has made it dramatically easier to write small, useful scripts. That is the
+good news. The follow-up news is that once you have twenty of them, "somewhere
+in a folder" stops being a system.
+
+`toolrack` is for that moment.
+
+The basic idea is simple:
+
+- AI is very good at helping you produce small scripts quickly.
+- A growing script library still needs structure, discoverability, and sane UX.
+- AI also benefits from compartmentalization: small scripts with narrow scope
+  are easier to write, review, test, and replace.
+- AI work is non-deterministic by nature, so every stable, tested, deterministic
+  thing you can hand off to automation is one less task balanced on your pet
+  clanker's back.
+
+This project is not trying to turn your script repo into a framework empire. It
+is trying to help your collection of tiny automations stay tidy, callable, and
+pleasant to use after the novelty phase.
+
+## Showcase
+
+The intended flow looks like this:
+
+1. Create a scripts repository with a clear layout.
+   There is a starter repo for that:
+   [`toolrack-template`](https://github.com/anfit/toolrack-template).
+2. Add small scripts under folders that match their area of work:
+   `github/`, `jira/`, `db/`, `images/`, `deploy/`, and so on.
+3. Put a sidecar next to each script so the command has typed arguments, help,
+   and completion.
+4. Plug `toolrack` into that repo so the whole thing becomes one coherent CLI.
+
+The result is one command on your `PATH`, available from PowerShell, Git Bash,
+or Cygwin, with shared help and completion instead of a growing folklore of
+"I think that one is in a repo called maybe-tools-old?"
+
+Example:
+
+```text
+my-tools github list-prs --state open --limit 20
+my-tools jira show ISSUE-123
+my-tools db query --env prod --file scripts/db/slow_report.sql
+```
+
+That is the main payoff: when you want to make a new script, it is not trapped
+in "that project you did two years ago". It lives next to two similar scripts
+in the folder dedicated to that area, where both humans and models can find the
+pattern immediately.
+
+Which also makes the AI prompt much nicer:
+
+> Hey AI, make me one like this, but mauve.
+
+## Deployment Model
+
+`toolrack` is meant to be installed into a scripts repository and launched
+through a repo-local wrapper in `bin/`.
+
+The wrapper is responsible for:
+
+- choosing the visible command name
+- setting `TOOLRACK_REPO_ROOT`
+- setting `TOOLRACK_SCRIPTS_ROOT`
+- setting `TOOLRACK_REGISTRY_FILE` or `TOOLRACK_REGISTRY_BASENAME`
+- invoking `python -m toolrack` from the repo's virtualenv
+
+Defaults:
+
+- CLI name: inferred from the wrapper filename, else `toolrack`
+- registry basename: `.toolrack`
+- repo discovery also accepts legacy `.attic` during walk-up
+
+## Core Commands
+
+`toolrack` provides a small management surface under `core`:
+
+- `core register <script_path>`: add one script to the registry
+- `core auto-register`: scan `scripts/` for sidecar-backed scripts
+- `core unregister <script_path>`: remove one script from the registry
+- `core reregister`: validate every registered script and sidecar
+- `core refresh-cache`: rebuild the cached command metadata next to `.toolrack`
+- `core list`: show registry entries and sidecar status
+- `core install-completion <shell>`: print shell completion source
+
+## Scripts Repo Contract
+
+A scripts repository normally contains:
+
+- `scripts/`: runnable `.py`, `.sh`, `.bash`, or `.sql` files
+- `.toolrack`: registry of enabled scripts
+- `.toolrack.cache.json`: cached command metadata used for faster startup and completion
+- `aliases.cfg`: optional group aliases, stored next to `.toolrack`
+- `bin/`: wrappers that export the toolrack environment variables
+
+`aliases.cfg` lets you shorten first-level or nested group paths without
+renaming folders. For example:
+
+```ini
+[groups]
+environments = env
+refactoring = refactor
+```
+
+That turns `your-tools environments get-status` into `your-tools env get-status`.
+
+Sidecars live next to scripts as `<script>.yml`. See
+[SIDECAR_SPEC.md](SIDECAR_SPEC.md).
+
+For a starter repository layout, use
+[`toolrack-template`](https://github.com/anfit/toolrack-template).
+
+## Shell completion
+
+Completion is answered from `.toolrack.cache.json` without importing Click, so
+<TAB> stays fast; anything the fast path does not model exactly falls back to
+Click. `core install-completion bash` prints a script that calls the Python
+interpreter directly and falls back to the wrapper if that interpreter moves.
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m pytest -m integration -s
+```

toolrack_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+toolrack/__init__.py,sha256=gjqPceIPB7VSFPev-EHO2L4vPqW84IrdBSOArn4Nq-E,94
+toolrack/__main__.py,sha256=c37inCl-LENkL3woa83_NG79cv-mWmnfn55o5IAyBn4,89
+toolrack/cli.py,sha256=hEeVCsmbJIE1nE27RE6GBYPKWcO71__SEOuOufAwOyc,31883
+toolrack/completion.py,sha256=zJzACXPi0S6-bYARDANEo9UGW711sImRlcX_loB6kgA,12296
+toolrack/entrypoint.py,sha256=EJb56KQP5fuiREen-CVHOhcClC5iNeZqbe4OHtFK58o,296
+toolrack/runtime.py,sha256=rvgkj6mPAb5dWAN-9NGnXk4vNGNoU4zCstM3LwpTDXc,6182
+toolrack_cli-0.1.0.dist-info/licenses/LICENSE,sha256=HY3ZcN-SJ0Ev4wQyI9ULxOGHZiyPabaYWTM1yXF1Ov4,1068
+toolrack_cli-0.1.0.dist-info/METADATA,sha256=RkDlom2_TY-jM0Tv490iQ1PZmLH-_VOCPa9wdp2LYh8,6857
+toolrack_cli-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+toolrack_cli-0.1.0.dist-info/entry_points.txt,sha256=_kYSduYA1pVXFzdvJFiSGO0Dz96OMH6whzYLeiGOekM,54
+toolrack_cli-0.1.0.dist-info/top_level.txt,sha256=FW1_1V4wV2ywBUpjvmjOK_5KeVXnVRmwWoKfGV7HQvw,9
+toolrack_cli-0.1.0.dist-info/RECORD,,

toolrack_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

toolrack_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+toolrack = toolrack.entrypoint:main

toolrack_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan Chimiak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolrack_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+toolrack