toolrack-cli 0.1.0__tar.gz → 0.3.0__tar.gz

{toolrack_cli-0.1.0/src/toolrack_cli.egg-info → toolrack_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolrack-cli
-Version: 0.1.0
+Version: 0.3.0
 Summary: Turn a folder of small scripts plus YAML sidecars into one typed, completable CLI
 Author: Jan Chimiak
 License-Expression: MIT
@@ -33,6 +33,9 @@ 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).
 
+[![PyPI](https://img.shields.io/pypi/v/toolrack-cli)](https://pypi.org/project/toolrack-cli/)
+[![Unit tests](https://github.com/anfit/toolrack/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/anfit/toolrack/actions/workflows/unit-tests.yml)
+
 ![Animated toolrack walkthrough: register, discover, and run scripts](docs/assets/toolrack-demo.gif)
 
 ## Quickstart
@@ -127,10 +130,72 @@ Which also makes the AI prompt much nicer:
 
 > Hey AI, make me one like this, but mauve.
 
+## Testing Your Tools
+
+Installing `toolrack-cli` also gives your test suite a pytest plugin. It runs the
+real CLI in a subprocess against a repository, so tests cover what users run:
+sidecar parsing, argument mapping, exit codes and the script itself. Python,
+Bash and SQL scripts are all supported.
+
+**Check the whole repo in CI.** `core validate` is read-only and exits non-zero
+on a missing script or sidecar, an invalid sidecar, a bad `aliases.cfg`, or two
+scripts that map to the same command. Unregistered sidecar pairs and a stale
+cache are warnings; `--strict` makes them failures.
+
+```sh
+my core validate --strict
+```
+
+**Or from pytest**, against your real repo (`toolrack_project`) or a throwaway
+one (`toolrack_repo`):
+
+```python
+def test_repo_is_valid(toolrack_project):
+    toolrack_project.validate(strict=True)   # AssertionError lists every problem
+
+def test_python_tool(toolrack_repo):
+    toolrack_repo.add_script(
+        "greet/hello.py",
+        "import sys\nprint('hi', sys.argv[2])\n",
+        {"description": "Say hi.", "args": [{"name": "name", "required": True}]},
+    )
+    assert toolrack_repo.run("greet", "hello", "--name", "Ada").check().stdout == "hi Ada\n"
+
+def test_bash_tool(toolrack_repo, toolrack_require_bash):      # skips without bash
+    toolrack_repo.add_script("ops/fail.sh", "exit 3\n", {"description": "Fails."})
+    assert toolrack_repo.run("ops", "fail").returncode == 3
+
+def test_sql_tool(toolrack_repo, toolrack_require_posix):      # no database needed
+    psql = toolrack_repo.stub_executable("psql", record_env=("PGDATABASE",))
+    script = toolrack_repo.add_script("db/ping.sql", "SELECT 1;", {"description": "Ping."})
+    toolrack_repo.run("db", "ping", env={"PGDATABASE": "dev"}).check()
+    assert psql.calls()[0]["argv"] == ["-f", str(script)]
+```
+
+SQL scripts run as `psql -f <file>`, so `stub_executable` puts a recording fake
+`psql` first on `PATH` instead of needing a database. It works on POSIX hosts
+only. `ToolrackRepo` is in `toolrack.testing` if you prefer to use it without
+the fixtures.
+
+## Migrating From a Checked-Out toolrack
+
+If you installed the engine editable from a clone (`pip install -e path/to/toolrack`,
+distribution name `toolrack`), switch your scripts repo to the PyPI release:
+
+```sh
+python3 ./sync_toolrack.py                              # refresh setup_toolrack.py
+python3 ./setup_toolrack.py --yes --force --cli-name <your-command>
+```
+
+Setup removes the old editable install, installs `toolrack-cli`, rewrites the
+wrappers, and regenerates completion. Full steps, plus the manual route, are in
+the [toolrack-template README](https://github.com/anfit/toolrack-template#migrating-from-a-checked-out-toolrack).
+
 ## Deployment Model
 
-`toolrack` is meant to be installed into a scripts repository and launched
-through a repo-local wrapper in `bin/`.
+`toolrack` is meant to be installed into a scripts repository's virtualenv
+(`pip install toolrack-cli`) and launched through a repo-local wrapper in `bin/`.
+The PyPI distribution is `toolrack-cli`; the package and command are `toolrack`.
 
 The wrapper is responsible for:
 
@@ -157,6 +222,13 @@ Defaults:
 - `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
+- `core validate [--strict]`: read-only repository check for CI (see [Testing Your Tools](#testing-your-tools))
+- `core init [path] [--no-example]`: create a minimal scripts repository; never overwrites existing files
+- `core doctor`: diagnose the installation and setup (legacy `toolrack` install shadowing `toolrack-cli`,
+  missing `bash` or `psql` for registered scripts, command not on `PATH`, validation errors); exits 1 on failures
+
+Starting without the template: `pip install toolrack-cli`, then
+`python -m toolrack core init my-tools` and `cd my-tools`.
 
 ## Scripts Repo Contract
 
@@ -189,8 +261,11 @@ For a starter repository layout, use
 
 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
+Click. `core install-completion <shell>` prints a script that calls the Python
 interpreter directly and falls back to the wrapper if that interpreter moves.
+This applies to bash, zsh and fish; the zsh and fish scripts are covered by
+string-level tests only, not exercised in a real zsh or fish, so report any
+problems.
 
 ## Development
 

{toolrack_cli-0.1.0 → toolrack_cli-0.3.0}/README.md

@@ -7,6 +7,9 @@ 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).
 
+[![PyPI](https://img.shields.io/pypi/v/toolrack-cli)](https://pypi.org/project/toolrack-cli/)
+[![Unit tests](https://github.com/anfit/toolrack/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/anfit/toolrack/actions/workflows/unit-tests.yml)
+
 ![Animated toolrack walkthrough: register, discover, and run scripts](docs/assets/toolrack-demo.gif)
 
 ## Quickstart
@@ -101,10 +104,72 @@ Which also makes the AI prompt much nicer:
 
 > Hey AI, make me one like this, but mauve.
 
+## Testing Your Tools
+
+Installing `toolrack-cli` also gives your test suite a pytest plugin. It runs the
+real CLI in a subprocess against a repository, so tests cover what users run:
+sidecar parsing, argument mapping, exit codes and the script itself. Python,
+Bash and SQL scripts are all supported.
+
+**Check the whole repo in CI.** `core validate` is read-only and exits non-zero
+on a missing script or sidecar, an invalid sidecar, a bad `aliases.cfg`, or two
+scripts that map to the same command. Unregistered sidecar pairs and a stale
+cache are warnings; `--strict` makes them failures.
+
+```sh
+my core validate --strict
+```
+
+**Or from pytest**, against your real repo (`toolrack_project`) or a throwaway
+one (`toolrack_repo`):
+
+```python
+def test_repo_is_valid(toolrack_project):
+    toolrack_project.validate(strict=True)   # AssertionError lists every problem
+
+def test_python_tool(toolrack_repo):
+    toolrack_repo.add_script(
+        "greet/hello.py",
+        "import sys\nprint('hi', sys.argv[2])\n",
+        {"description": "Say hi.", "args": [{"name": "name", "required": True}]},
+    )
+    assert toolrack_repo.run("greet", "hello", "--name", "Ada").check().stdout == "hi Ada\n"
+
+def test_bash_tool(toolrack_repo, toolrack_require_bash):      # skips without bash
+    toolrack_repo.add_script("ops/fail.sh", "exit 3\n", {"description": "Fails."})
+    assert toolrack_repo.run("ops", "fail").returncode == 3
+
+def test_sql_tool(toolrack_repo, toolrack_require_posix):      # no database needed
+    psql = toolrack_repo.stub_executable("psql", record_env=("PGDATABASE",))
+    script = toolrack_repo.add_script("db/ping.sql", "SELECT 1;", {"description": "Ping."})
+    toolrack_repo.run("db", "ping", env={"PGDATABASE": "dev"}).check()
+    assert psql.calls()[0]["argv"] == ["-f", str(script)]
+```
+
+SQL scripts run as `psql -f <file>`, so `stub_executable` puts a recording fake
+`psql` first on `PATH` instead of needing a database. It works on POSIX hosts
+only. `ToolrackRepo` is in `toolrack.testing` if you prefer to use it without
+the fixtures.
+
+## Migrating From a Checked-Out toolrack
+
+If you installed the engine editable from a clone (`pip install -e path/to/toolrack`,
+distribution name `toolrack`), switch your scripts repo to the PyPI release:
+
+```sh
+python3 ./sync_toolrack.py                              # refresh setup_toolrack.py
+python3 ./setup_toolrack.py --yes --force --cli-name <your-command>
+```
+
+Setup removes the old editable install, installs `toolrack-cli`, rewrites the
+wrappers, and regenerates completion. Full steps, plus the manual route, are in
+the [toolrack-template README](https://github.com/anfit/toolrack-template#migrating-from-a-checked-out-toolrack).
+
 ## Deployment Model
 
-`toolrack` is meant to be installed into a scripts repository and launched
-through a repo-local wrapper in `bin/`.
+`toolrack` is meant to be installed into a scripts repository's virtualenv
+(`pip install toolrack-cli`) and launched through a repo-local wrapper in `bin/`.
+The PyPI distribution is `toolrack-cli`; the package and command are `toolrack`.
 
 The wrapper is responsible for:
 
@@ -131,6 +196,13 @@ Defaults:
 - `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
+- `core validate [--strict]`: read-only repository check for CI (see [Testing Your Tools](#testing-your-tools))
+- `core init [path] [--no-example]`: create a minimal scripts repository; never overwrites existing files
+- `core doctor`: diagnose the installation and setup (legacy `toolrack` install shadowing `toolrack-cli`,
+  missing `bash` or `psql` for registered scripts, command not on `PATH`, validation errors); exits 1 on failures
+
+Starting without the template: `pip install toolrack-cli`, then
+`python -m toolrack core init my-tools` and `cd my-tools`.
 
 ## Scripts Repo Contract
 
@@ -163,8 +235,11 @@ For a starter repository layout, use
 
 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
+Click. `core install-completion <shell>` prints a script that calls the Python
 interpreter directly and falls back to the wrapper if that interpreter moves.
+This applies to bash, zsh and fish; the zsh and fish scripts are covered by
+string-level tests only, not exercised in a real zsh or fish, so report any
+problems.
 
 ## Development
 

{toolrack_cli-0.1.0 → toolrack_cli-0.3.0}/pyproject.toml

@@ -39,6 +39,10 @@ dev = [
 [project.scripts]
 toolrack = "toolrack.entrypoint:main"
 
+# Fixtures for testing your own scripts repo; inert unless a test requests them.
+[project.entry-points.pytest11]
+toolrack = "toolrack.pytest_plugin"
+
 [tool.setuptools.dynamic]
 version = { attr = "toolrack.__version__" }
 

{toolrack_cli-0.1.0 → toolrack_cli-0.3.0}/src/toolrack/__init__.py

@@ -1,3 +1,3 @@
 """toolrack - typed dispatcher for a user-owned scripts repository."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"