create-zush-package

Create a zush Python-package plugin

A Python package becomes a zush plugin by shipping a __zush__.py manifest at its top level. zush rebuild finds it, reads each target's function signature, and bakes everything into ~/.zush/pyindex.json. At dispatch, zush imports only the one target module and calls the function. You never import or decorate anything from zush.

Canonical reference (read for anything below not covered here):

• https://github.com/ZackaryW/zush/blob/main/docs/python-packages.md
• https://github.com/ZackaryW/zush/blob/main/docs/commands.md

Steps

1. Confirm the package layout. There must be an importable package directory (the folder with __init__.py, or an installed distribution). The manifest goes at that package's top level: mypkg/__zush__.py.

2. Write the manifest as a single module-level ZUSH dict. All three sections are optional; most plugins start with just commands. Nesting maps to dotted command paths; leaves are "relative/path.py::function" targets, relative to the package dir:

   ZUSH = {
       "commands": {
           "git": {                       # nesting -> dotted path
               "clean": "ops/git.py::clean",   # -> zush git.clean
               "sync":  "ops/git.py::sync",    # -> zush git.sync
           },
       },
   }
   

3. Write the target functions as normal typed functions — no decorators. mypkg/ops/git.py:

   def clean(path: str, force: bool = False):
       return f"clean {path} (force={force})"
   
   def sync():
       return "synced"
   

   The return value, if any, is printed.

4. Make the package importable, then index and run:

   pip install -e .        # or: uv pip install -e .
   zush rebuild            # writes ~/.zush/pyindex.json
   zush git.clean ./tmp --force
   zush git.sync
   

Argument parsing — driven by the function signature

zush reads each target's signature at rebuild time. Shape the signature to shape the CLI:

Parameter shape	Becomes
no default (required)	a positional argument
has a default	an option --name
bool default	a flag (present = True)
int / float / str typed	value coerced to that type
parameter named ctx	injected service context, not a CLI argument
*args / **kwargs	ignored by the parser

So def migrate(target: str, steps: int = 1, dry_run: bool = False) is run as zush db.migrate head --steps 3 --dry-run.

Optional sections

Add to the same ZUSH dict when needed — distinct concerns, scaffold only what is asked:

• hooks: pre/post/error with [] wildcards — https://github.com/ZackaryW/zush/blob/main/docs/hooks.md
• services: shared ctx injected into ctx-named params — https://github.com/ZackaryW/zush/blob/main/docs/services.md

Notes

• If two installed plugins declare the same dotted command, the last one indexed wins and zush rebuild prints a collision warning. Pick a unique top-level namespace.
• Re-run zush rebuild after installing or changing the plugin.
• Override where rebuild scans / writes with ZUSH_PATH and ZUSH_INDEX (useful for testing against an isolated plugin set).