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

{toolrack_cli-0.2.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.2.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
@@ -222,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
 
@@ -254,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.2.0 → toolrack_cli-0.3.0}/README.md

@@ -196,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
 
@@ -228,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.2.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.2.0"
+__version__ = "0.3.0"

{toolrack_cli-0.2.0 → toolrack_cli-0.3.0}/src/toolrack/cli.py

@@ -12,9 +12,10 @@ from dataclasses import dataclass
 
 import click
 
-from toolrack import __version__, runtime
+from toolrack import __version__, runtime, shells, sidecar as _sidecar
 from toolrack.runtime import RepositoryContext
 
+_is_windows = shells.is_windows
 CLI_NAME = runtime.cli_name()
 COMPLETION_VAR = runtime.completion_var(CLI_NAME)
 DEFAULT_REGISTRY_BASENAME = runtime.registry_basename()
@@ -23,9 +24,6 @@ DEFAULT_REGISTRY_BASENAME = runtime.registry_basename()
 # the way once toolrack is used as an installed library as well as a checkout.
 
 
-def _is_windows() -> bool:
-    return os.name == "nt"
-
 
 def _fix_windows_completion_crlf() -> None:
     if not _is_windows():
@@ -185,134 +183,16 @@ def _load_aliases(repo: RepositoryContext | None = None) -> dict[str, str]:
 
 
 _sidecar_path = runtime.sidecar_path
+_to_bash_path = shells.to_bash_path
+_resolve_bash_exe = shells.resolve_bash_exe
+_load_sidecar = _sidecar.load_sidecar
+_validate_sidecar = _sidecar.validate_sidecar
 
 
 def _generate_sidecar(script_path: str) -> dict:
-    import yaml
-
-    name = os.path.basename(script_path)
-    sidecar = {
-        "# autogenerated": (
-            f"This sidecar was created automatically by `{CLI_NAME} core register`.\n"
-            "Arguments are passed through verbatim. Replace it with a typed sidecar."
-        ),
-        "description": f"Run {name} (autogenerated; edit to add proper description).",
-        "args": [
-            {
-                "name": "args",
-                "positional": True,
-                "variadic": True,
-                "required": False,
-                "help": "All arguments passed through verbatim to the script.",
-            }
-        ],
-    }
-    with open(_sidecar_path(script_path), "w", encoding="utf-8") as handle:
-        yaml.dump(sidecar, handle, default_flow_style=False, allow_unicode=True, sort_keys=False)
-    return sidecar
-
-
-def _load_sidecar(script_path: str) -> dict | None:
-    yml_path = _sidecar_path(script_path)
-    if not os.path.isfile(yml_path):
-        return None
-    import yaml
-
-    with open(yml_path, encoding="utf-8") as handle:
-        data = yaml.safe_load(handle) or {}
-    if not isinstance(data, dict):
-        raise RuntimeError(f"{yml_path}: sidecar must be a YAML mapping, got {type(data).__name__}")
-    return data
-
-
-def _validate_sidecar(sidecar: dict, script_path: str) -> None:
-    ext = os.path.splitext(script_path)[1].lower()
-    args = sidecar.get("args") or []
-    name = os.path.basename(script_path)
-
-    if ext == ".sql" and args:
-        raise RuntimeError(f"{name}: SQL scripts must not declare 'args'.")
-
-    seen_names: set[str] = set()
-    variadic_seen = False
-    for arg in args:
-        arg_name = arg.get("name", "")
-        if arg_name in seen_names:
-            raise RuntimeError(f"{name}: duplicate arg name '{arg_name}'.")
-        seen_names.add(arg_name)
-        if variadic_seen:
-            raise RuntimeError(f"{name}: '{arg_name}' appears after variadic; variadic must be last.")
-        if arg.get("variadic"):
-            if not arg.get("positional"):
-                raise RuntimeError(f"{name}: '{arg_name}' is variadic but not positional.")
-            variadic_seen = True
-        if arg.get("multiple") and arg.get("positional"):
-            raise RuntimeError(f"{name}: '{arg_name}' cannot be both multiple and positional.")
-        if arg.get("flag") and arg.get("type") not in (None, "bool"):
-            raise RuntimeError(f"{name}: '{arg_name}' is a flag but declares type '{arg['type']}'.")
-
-
-def _to_bash_path(windows_path: str, bash_exe: str = "") -> str:
-    # TODO(#5): Isolate shell/path translation behind a shell adapter layer.
-    # Windows, Git Bash, and Cygwin compatibility logic is mixed into the core
-    # dispatcher, which makes the module harder to reason about than it should be.
-    if not _is_windows():
-        return windows_path
-
-    cygpath_candidates: list[str] = []
-    if bash_exe:
-        bash_dir = os.path.dirname(os.path.abspath(bash_exe))
-        same_dir = os.path.join(bash_dir, "cygpath.exe")
-        parent_usr_bin = os.path.join(os.path.dirname(bash_dir), "usr", "bin", "cygpath.exe")
-        for candidate in (same_dir, parent_usr_bin):
-            if os.path.isfile(candidate):
-                cygpath_candidates.append(candidate)
-    cygpath_candidates.append("cygpath")
-
-    for cygpath_exe in cygpath_candidates:
-        try:
-            result = subprocess.run(
-                [cygpath_exe, "-u", windows_path],
-                capture_output=True,
-                text=True,
-                timeout=5,
-            )
-            if result.returncode == 0:
-                return result.stdout.strip()
-        except (FileNotFoundError, subprocess.TimeoutExpired):
-            continue
-
-    path = windows_path.replace("\\", "/")
-    if len(path) >= 2 and path[1] == ":":
-        path = "/" + path[0].lower() + path[2:]
-    return path
-
-
-def _resolve_bash_exe() -> str:
-    if not _is_windows():
-        return "bash"
-
-    cygwin_bash = r"C:\cygwin64\bin\bash.exe"
-    git_bash = r"C:\Program Files\Git\bin\bash.exe"
+    return _sidecar.generate_sidecar(script_path, CLI_NAME)
 
-    if not os.environ.get("MSYSTEM"):
-        path_dirs = os.environ.get("PATH", "").split(os.pathsep)
-        cygwin_bin = r"C:\cygwin64\bin"
-        gitbash_bin = r"C:\Program Files\Git\bin"
 
-        def _norm(value: str) -> str:
-            return os.path.normcase(os.path.normpath(value))
-
-        normed = [_norm(entry) for entry in path_dirs]
-        cygwin_idx = next((idx for idx, entry in enumerate(normed) if entry == _norm(cygwin_bin)), 999)
-        gitbash_idx = next((idx for idx, entry in enumerate(normed) if entry == _norm(gitbash_bin)), 999)
-        if cygwin_idx < gitbash_idx and os.path.isfile(cygwin_bash):
-            return cygwin_bash
-
-    if os.environ.get("MSYSTEM") and os.path.isfile(git_bash):
-        return git_bash
-
-    return "bash"
 
 
 def _interpreter(script_path: str) -> list[str]:
@@ -969,6 +849,46 @@ def cmd_validate(strict: bool):
         raise click.exceptions.Exit(1)
 
 
+@core.command("init")
+@click.argument("path", default=".", required=False)
+@click.option("--no-example", is_flag=True, help="Do not create the example script.")
+def cmd_init(path: str, no_example: bool):
+    """Create a minimal scripts repository (never overwrites existing files)."""
+    from toolrack import scaffold
+
+    root = os.path.abspath(path)
+    try:
+        results = scaffold.scaffold_repository(root, example=not no_example)
+    except OSError as exc:
+        raise click.ClickException(str(exc))
+    for rel, status in results:
+        click.echo(f"  {status.upper():<8} {rel}")
+    repo = scaffold.repository_context(root)
+    _refresh_cache(repo)
+    click.echo(
+        f"\nRepository ready at {root}\n"
+        f"Next: cd there, then run `python -m toolrack --help`"
+        + ("" if no_example else " and `python -m toolrack example hello --name you`")
+        + ".\nAdd a script plus a .yml sidecar under scripts/, then `core auto-register`."
+    )
+
+
+@core.command("doctor")
+def cmd_doctor():
+    """Diagnose the toolrack installation and repository setup."""
+    from toolrack import doctor
+
+    checks = doctor.run_checks(_current_repo(), CLI_NAME, _check_repository)
+    for check in checks:
+        tag = {"ok": "ok  ", "warn": "WARN", "fail": "FAIL"}[check.level]
+        click.echo(f"  [{tag}] {check.name}: {check.detail}", err=check.level != "ok")
+    failed = sum(1 for c in checks if c.level == doctor.FAIL)
+    warned = sum(1 for c in checks if c.level == doctor.WARN)
+    click.echo(f"\n{len(checks) - failed - warned} ok, {warned} warnings, {failed} failures.")
+    if failed:
+        raise click.exceptions.Exit(1)
+
+
 @core.command("refresh-cache")
 def cmd_refresh_cache():
     """Rebuild the command metadata cache next to the registry."""
@@ -993,6 +913,92 @@ def cmd_list():
         click.echo(f"  [{status}]  {entry}{sidecar_tag}")
 
 
+def _direct_completion_target() -> tuple[str, dict[str, str]]:
+    """Interpreter and environment the wrapper would use, for direct completion."""
+    repo = _current_repo()
+    python = _to_bash_path(sys.executable, _resolve_bash_exe())
+    env = {
+        "TOOLRACK_CLI_NAME": CLI_NAME,
+        "TOOLRACK_REPO_ROOT": repo.repo_root,
+        "TOOLRACK_SCRIPTS_ROOT": repo.scripts_root,
+        "TOOLRACK_REGISTRY_FILE": repo.registry_file,
+        "TOOLRACK_CACHE_FILE": repo.cache_file,
+        "TOOLRACK_ALIASES_FILE": repo.aliases_file,
+    }
+    return python, env
+
+
+def _direct_completion_helper_name() -> str:
+    ident = "".join(ch if ch.isalnum() else "_" for ch in CLI_NAME)
+    return f"_{ident}_completion_direct"
+
+
+def _bypass_wrapper_in_zsh_completion(source: str) -> str:
+    """Zsh counterpart of the Bash bypass; same fallback to the wrapper.
+
+    Only rewrites the exact invocation Click emits and otherwise returns the
+    script unchanged, so an unexpected Click version degrades to the old path.
+    """
+    import shlex
+
+    call = (
+        f'env COMP_WORDS="${{words[*]}}" COMP_CWORD=$((CURRENT-1)) '
+        f"{COMPLETION_VAR}=zsh_complete {CLI_NAME}"
+    )
+    if call not in source:
+        return source
+
+    python, env = _direct_completion_target()
+    assignments = " ".join(f"{name}={shlex.quote(value)}" for name, value in env.items())
+    helper = _direct_completion_helper_name()
+    prefix = f'env COMP_WORDS="$1" COMP_CWORD="$2" {COMPLETION_VAR}=zsh_complete'
+    definition = (
+        f"{helper}() {{\n"
+        f"    if [ -x {shlex.quote(python)} ]; then\n"
+        f"        {prefix} {assignments} {shlex.quote(python)} -m toolrack\n"
+        f"    else\n"
+        f"        {prefix} {shlex.quote(CLI_NAME)}\n"
+        f"    fi\n"
+        f"}}\n\n"
+    )
+    source = source.replace(call, f'{helper} "${{words[*]}}" $((CURRENT-1))', 1)
+    # `#compdef` must stay the first line of the file.
+    if source.startswith("#compdef"):
+        first, _, rest = source.partition("\n")
+        return f"{first}\n\n{definition}{rest}"
+    return definition + source
+
+
+def _bypass_wrapper_in_fish_completion(source: str) -> str:
+    """Fish counterpart of the Bash bypass; same fallback to the wrapper."""
+    call = (
+        f"env {COMPLETION_VAR}=fish_complete COMP_WORDS=(commandline -cp) "
+        f"COMP_CWORD=(commandline -t) {CLI_NAME}"
+    )
+    if call not in source:
+        return source
+
+    python, env = _direct_completion_target()
+    # Single-quoted fish strings cannot represent an embedded apostrophe
+    # portably; leave the script alone rather than emit a broken one.
+    if any("'" in value for value in (python, *env.values())):
+        return source
+    assignments = " ".join(f"{name}='{value}'" for name, value in env.items())
+    helper = _direct_completion_helper_name()
+    prefix = f'env COMP_WORDS="$argv[1]" COMP_CWORD="$argv[2]" {COMPLETION_VAR}=fish_complete'
+    definition = (
+        f"function {helper}\n"
+        f"    if test -x '{python}'\n"
+        f"        {prefix} {assignments} '{python}' -m toolrack\n"
+        f"    else\n"
+        f"        {prefix} {CLI_NAME}\n"
+        f"    end\n"
+        f"end\n\n"
+    )
+    source = source.replace(call, f"{helper} (commandline -cp) (commandline -t)", 1)
+    return definition + source
+
+
 def _bypass_wrapper_in_bash_completion(source: str) -> str:
     """Make Bash completion call this interpreter directly instead of the wrapper.
 
@@ -1008,19 +1014,9 @@ def _bypass_wrapper_in_bash_completion(source: str) -> str:
     if call not in source:
         return source
 
-    repo = _current_repo()
-    python = _to_bash_path(sys.executable, _resolve_bash_exe())
-    env = {
-        "TOOLRACK_CLI_NAME": CLI_NAME,
-        "TOOLRACK_REPO_ROOT": repo.repo_root,
-        "TOOLRACK_SCRIPTS_ROOT": repo.scripts_root,
-        "TOOLRACK_REGISTRY_FILE": repo.registry_file,
-        "TOOLRACK_CACHE_FILE": repo.cache_file,
-        "TOOLRACK_ALIASES_FILE": repo.aliases_file,
-    }
+    python, env = _direct_completion_target()
     assignments = " ".join(f"{name}={shlex.quote(value)}" for name, value in env.items())
-    ident = "".join(ch if ch.isalnum() else "_" for ch in CLI_NAME)
-    helper = f"_{ident}_completion_direct"
+    helper = _direct_completion_helper_name()
     definition = (
         f"{helper}() {{\n"
         f"    if [ -x {shlex.quote(python)} ]; then\n"
@@ -1050,6 +1046,10 @@ def install_completion(shell: str):
         # more explicit and less brittle than editing generated shell text.
         source = source.replace("$(env ", "$(")
         source = _bypass_wrapper_in_bash_completion(source)
+    elif shell == "zsh":
+        source = _bypass_wrapper_in_zsh_completion(source)
+    elif shell == "fish":
+        source = _bypass_wrapper_in_fish_completion(source)
     sys.stdout.write(source)
     sys.stdout.flush()
 

{toolrack_cli-0.2.0 → toolrack_cli-0.3.0}/src/toolrack/completion.py

@@ -54,6 +54,19 @@ CORE_COMMANDS: dict[str, dict] = {
         "args": [{"name": "script_path", "positional": True, "required": True}],
     },
     "reregister": {"description": "Re-validate all registered commands."},
+    "init": {
+        "description": "Create a minimal scripts repository (never overwrites existing files).",
+        "args": [
+            {"name": "path", "positional": True},
+            {
+                "name": "no_example",
+                "flag": True,
+                "option": "--no-example",
+                "help": "Do not create the example script.",
+            },
+        ],
+    },
+    "doctor": {"description": "Diagnose the toolrack installation and repository setup."},
     "validate": {
         "description": "Check registry, sidecars and aliases without changing anything (for CI).",
         "args": [

toolrack_cli-0.3.0/src/toolrack/doctor.py

@@ -0,0 +1,126 @@
+"""Environment and installation diagnostics (`toolrack doctor`).
+
+Complements `core validate`, which checks the repository's contents. Doctor
+asks "is toolrack itself set up sanely on this machine?". Click-free; every
+probe is a small function so it can be tested with injected inputs.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from typing import Callable, NamedTuple
+
+from toolrack import __version__, runtime
+
+OK, WARN, FAIL = "ok", "warn", "fail"
+
+
+class Check(NamedTuple):
+    level: str
+    name: str
+    detail: str
+
+
+def _install_description() -> str:
+    """How this copy of toolrack was installed (editable checkout vs normal)."""
+    from importlib import metadata
+
+    location = os.path.dirname(os.path.abspath(__file__))
+    try:
+        dist = metadata.distribution("toolrack-cli")
+        raw = dist.read_text("direct_url.json")
+        if raw and json.loads(raw).get("dir_info", {}).get("editable"):
+            return f"{__version__}, editable install from {location}"
+    except (metadata.PackageNotFoundError, ValueError):
+        pass
+    return f"{__version__} at {location}"
+
+
+def legacy_distribution() -> str | None:
+    """Version of a separately installed ``toolrack`` distribution, if any.
+
+    Before the PyPI release the engine was installed as ``toolrack``. Any
+    distribution of that name ships the same import package as ``toolrack-cli``
+    and can shadow it.
+    """
+    from importlib import metadata
+
+    try:
+        return metadata.version("toolrack")
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def run_checks(
+    repo: runtime.RepositoryContext,
+    cli_name: str,
+    check_repository: Callable[[runtime.RepositoryContext], tuple[list[str], list]],
+    registry_entries: list[str] | None = None,
+) -> list[Check]:
+    checks: list[Check] = []
+    add = lambda level, name, detail: checks.append(Check(level, name, detail))  # noqa: E731
+
+    add(OK, "toolrack", _install_description())
+    add(OK, "python", f"{sys.version.split()[0]} at {sys.executable}")
+
+    legacy = legacy_distribution()
+    if legacy:
+        add(
+            WARN,
+            "legacy install",
+            f"a separate 'toolrack' distribution ({legacy}) is installed and can shadow toolrack-cli; "
+            "run: pip uninstall toolrack",
+        )
+
+    if not os.path.isfile(repo.registry_file):
+        add(FAIL, "repository", f"no registry at {repo.registry_file} (run: {cli_name} init)")
+        return checks
+    add(OK, "repository", repo.repo_root)
+
+    if not os.path.isdir(repo.scripts_root):
+        add(FAIL, "scripts dir", f"missing: {repo.scripts_root}")
+    legacy_registry = os.path.join(repo.repo_root, runtime.LEGACY_REGISTRY_BASENAME)
+    if os.path.isfile(legacy_registry) and os.path.basename(repo.registry_file) != runtime.LEGACY_REGISTRY_BASENAME:
+        add(WARN, "legacy registry", f"{legacy_registry} is ignored; rename it to {runtime.DEFAULT_REGISTRY_BASENAME}")
+
+    entries = registry_entries if registry_entries is not None else runtime.read_registry(repo)
+    add(OK, "registered", f"{len(entries)} script(s)")
+
+    exts = {os.path.splitext(entry)[1].lower() for entry in entries}
+    if exts & {".sh", ".bash"}:
+        from toolrack import shells
+
+        bash = _working_bash(shells.resolve_bash_exe())
+        add(OK if bash else FAIL, "bash", bash or "registered .sh/.bash scripts need a working bash")
+    if ".sql" in exts:
+        psql = shutil.which("psql")
+        add(OK if psql else FAIL, "psql", psql or "registered .sql scripts run through psql, which is not on PATH")
+
+    wrapper = shutil.which(cli_name)
+    add(OK if wrapper else WARN, "command on PATH", wrapper or f"'{cli_name}' not found on PATH (open a new shell?)")
+
+    ok, diagnostics = check_repository(repo)
+    errors = [d for d in diagnostics if d.level == "error"]
+    warnings = [d for d in diagnostics if d.level == "warning"]
+    if errors:
+        add(FAIL, "validate", f"{len(errors)} error(s); run: {cli_name} core validate")
+    elif warnings:
+        add(WARN, "validate", f"{len(warnings)} warning(s); run: {cli_name} core validate")
+    else:
+        add(OK, "validate", f"{len(ok)} script(s) valid")
+    return checks
+
+
+def _working_bash(candidate: str) -> str | None:
+    import subprocess
+
+    try:
+        done = subprocess.run(
+            [candidate, "-c", "echo toolrack"], capture_output=True, text=True, timeout=15, check=False
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return candidate if done.returncode == 0 and done.stdout.strip() == "toolrack" else None

toolrack_cli-0.3.0/src/toolrack/scaffold.py

@@ -0,0 +1,93 @@
+"""Create a minimal scripts repository (`toolrack init`). Click-free and non-destructive."""
+
+from __future__ import annotations
+
+import os
+
+from toolrack import runtime
+
+EXAMPLE_SCRIPT = '''\
+import argparse
+
+parser = argparse.ArgumentParser(description="Print a greeting.")
+parser.add_argument("--name", required=True)
+print(f"hello, {parser.parse_args().name}")
+'''
+
+EXAMPLE_SIDECAR = """\
+description: Print a greeting.
+args:
+  - name: name
+    required: true
+    help: Name to greet.
+"""
+
+EXAMPLE_ENTRY = "scripts/example/hello.py"
+CACHE_IGNORE_LINE = ".toolrack.cache.json"
+
+
+def scaffold_repository(root: str, example: bool = True) -> list[tuple[str, str]]:
+    """Create the repository layout under ``root``; never overwrite anything.
+
+    Returns ``(relative_path, status)`` pairs where status is ``created``,
+    ``updated`` or ``kept``.
+    """
+    root = os.path.abspath(root)
+    registry_name = runtime.registry_basename()
+    results: list[tuple[str, str]] = []
+
+    def write_new(rel: str, content: str) -> None:
+        path = os.path.join(root, rel)
+        if os.path.exists(path):
+            results.append((rel, "kept"))
+            return
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(content)
+        results.append((rel, "created"))
+
+    os.makedirs(os.path.join(root, "scripts"), exist_ok=True)
+
+    registry_path = os.path.join(root, registry_name)
+    if example:
+        write_new(EXAMPLE_ENTRY, EXAMPLE_SCRIPT)
+        write_new("scripts/example/hello.yml", EXAMPLE_SIDECAR)
+    if not os.path.exists(registry_path):
+        write_new(registry_name, (EXAMPLE_ENTRY + "\n") if example else "")
+    else:
+        existing = runtime.read_registry(_context(root))
+        if example and EXAMPLE_ENTRY not in existing and os.path.isfile(os.path.join(root, EXAMPLE_ENTRY)):
+            with open(registry_path, "a", encoding="utf-8", newline="\n") as handle:
+                handle.write(EXAMPLE_ENTRY + "\n")
+            results.append((registry_name, "updated"))
+        else:
+            results.append((registry_name, "kept"))
+
+    gitignore = os.path.join(root, ".gitignore")
+    if os.path.exists(gitignore):
+        with open(gitignore, encoding="utf-8") as handle:
+            text = handle.read()
+        if CACHE_IGNORE_LINE not in text.splitlines():
+            with open(gitignore, "a", encoding="utf-8", newline="\n") as handle:
+                handle.write(("" if text.endswith("\n") or not text else "\n") + CACHE_IGNORE_LINE + "\n")
+            results.append((".gitignore", "updated"))
+        else:
+            results.append((".gitignore", "kept"))
+    else:
+        write_new(".gitignore", CACHE_IGNORE_LINE + "\n")
+    return results
+
+
+def _context(root: str) -> runtime.RepositoryContext:
+    registry = os.path.join(root, runtime.registry_basename())
+    return runtime.RepositoryContext(
+        repo_root=root,
+        scripts_root=os.path.join(root, "scripts"),
+        registry_file=registry,
+        cache_file=registry + ".cache.json",
+        aliases_file=os.path.join(root, "aliases.cfg"),
+    )
+
+
+def repository_context(root: str) -> runtime.RepositoryContext:
+    return _context(os.path.abspath(root))

toolrack_cli-0.3.0/src/toolrack/shells.py

@@ -0,0 +1,73 @@
+"""Windows / Git Bash / Cygwin path and interpreter handling."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+
+
+def is_windows() -> bool:
+    return os.name == "nt"
+
+
+def to_bash_path(windows_path: str, bash_exe: str = "") -> str:
+    # TODO(#5): Isolate shell/path translation behind a shell adapter layer.
+    # Windows, Git Bash, and Cygwin compatibility logic is mixed into the core
+    # dispatcher, which makes the module harder to reason about than it should be.
+    if not is_windows():
+        return windows_path
+
+    cygpath_candidates: list[str] = []
+    if bash_exe:
+        bash_dir = os.path.dirname(os.path.abspath(bash_exe))
+        same_dir = os.path.join(bash_dir, "cygpath.exe")
+        parent_usr_bin = os.path.join(os.path.dirname(bash_dir), "usr", "bin", "cygpath.exe")
+        for candidate in (same_dir, parent_usr_bin):
+            if os.path.isfile(candidate):
+                cygpath_candidates.append(candidate)
+    cygpath_candidates.append("cygpath")
+
+    for cygpath_exe in cygpath_candidates:
+        try:
+            result = subprocess.run(
+                [cygpath_exe, "-u", windows_path],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode == 0:
+                return result.stdout.strip()
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            continue
+
+    path = windows_path.replace("\\", "/")
+    if len(path) >= 2 and path[1] == ":":
+        path = "/" + path[0].lower() + path[2:]
+    return path
+
+
+def resolve_bash_exe() -> str:
+    if not is_windows():
+        return "bash"
+
+    cygwin_bash = r"C:\cygwin64\bin\bash.exe"
+    git_bash = r"C:\Program Files\Git\bin\bash.exe"
+
+    if not os.environ.get("MSYSTEM"):
+        path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+        cygwin_bin = r"C:\cygwin64\bin"
+        gitbash_bin = r"C:\Program Files\Git\bin"
+
+        def _norm(value: str) -> str:
+            return os.path.normcase(os.path.normpath(value))
+
+        normed = [_norm(entry) for entry in path_dirs]
+        cygwin_idx = next((idx for idx, entry in enumerate(normed) if entry == _norm(cygwin_bin)), 999)
+        gitbash_idx = next((idx for idx, entry in enumerate(normed) if entry == _norm(gitbash_bin)), 999)
+        if cygwin_idx < gitbash_idx and os.path.isfile(cygwin_bash):
+            return cygwin_bash
+
+    if os.environ.get("MSYSTEM") and os.path.isfile(git_bash):
+        return git_bash
+
+    return "bash"

toolrack_cli-0.3.0/src/toolrack/sidecar.py

@@ -0,0 +1,75 @@
+"""Sidecar (.yml) loading, generation and validation.
+
+Click-free; PyYAML is imported lazily so importing this module stays cheap.
+"""
+
+from __future__ import annotations
+
+import os
+
+from toolrack import runtime
+
+
+def generate_sidecar(script_path: str, cli_name: str) -> dict:
+    import yaml
+
+    name = os.path.basename(script_path)
+    sidecar = {
+        "# autogenerated": (
+            f"This sidecar was created automatically by `{cli_name} core register`.\n"
+            "Arguments are passed through verbatim. Replace it with a typed sidecar."
+        ),
+        "description": f"Run {name} (autogenerated; edit to add proper description).",
+        "args": [
+            {
+                "name": "args",
+                "positional": True,
+                "variadic": True,
+                "required": False,
+                "help": "All arguments passed through verbatim to the script.",
+            }
+        ],
+    }
+    with open(runtime.sidecar_path(script_path), "w", encoding="utf-8") as handle:
+        yaml.dump(sidecar, handle, default_flow_style=False, allow_unicode=True, sort_keys=False)
+    return sidecar
+
+
+def load_sidecar(script_path: str) -> dict | None:
+    yml_path = runtime.sidecar_path(script_path)
+    if not os.path.isfile(yml_path):
+        return None
+    import yaml
+
+    with open(yml_path, encoding="utf-8") as handle:
+        data = yaml.safe_load(handle) or {}
+    if not isinstance(data, dict):
+        raise RuntimeError(f"{yml_path}: sidecar must be a YAML mapping, got {type(data).__name__}")
+    return data
+
+
+def validate_sidecar(sidecar: dict, script_path: str) -> None:
+    ext = os.path.splitext(script_path)[1].lower()
+    args = sidecar.get("args") or []
+    name = os.path.basename(script_path)
+
+    if ext == ".sql" and args:
+        raise RuntimeError(f"{name}: SQL scripts must not declare 'args'.")
+
+    seen_names: set[str] = set()
+    variadic_seen = False
+    for arg in args:
+        arg_name = arg.get("name", "")
+        if arg_name in seen_names:
+            raise RuntimeError(f"{name}: duplicate arg name '{arg_name}'.")
+        seen_names.add(arg_name)
+        if variadic_seen:
+            raise RuntimeError(f"{name}: '{arg_name}' appears after variadic; variadic must be last.")
+        if arg.get("variadic"):
+            if not arg.get("positional"):
+                raise RuntimeError(f"{name}: '{arg_name}' is variadic but not positional.")
+            variadic_seen = True
+        if arg.get("multiple") and arg.get("positional"):
+            raise RuntimeError(f"{name}: '{arg_name}' cannot be both multiple and positional.")
+        if arg.get("flag") and arg.get("type") not in (None, "bool"):
+            raise RuntimeError(f"{name}: '{arg_name}' is a flag but declares type '{arg['type']}'.")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolrack-cli
-Version: 0.2.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
@@ -222,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
 
@@ -254,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.2.0 → toolrack_cli-0.3.0}/src/toolrack_cli.egg-info/SOURCES.txt

@@ -5,9 +5,13 @@ src/toolrack/__init__.py
 src/toolrack/__main__.py
 src/toolrack/cli.py
 src/toolrack/completion.py
+src/toolrack/doctor.py
 src/toolrack/entrypoint.py
 src/toolrack/pytest_plugin.py
 src/toolrack/runtime.py
+src/toolrack/scaffold.py
+src/toolrack/shells.py
+src/toolrack/sidecar.py
 src/toolrack/testing.py
 src/toolrack_cli.egg-info/PKG-INFO
 src/toolrack_cli.egg-info/SOURCES.txt
@@ -18,5 +22,6 @@ src/toolrack_cli.egg-info/top_level.txt
 tests/test_cli.py
 tests/test_completion.py
 tests/test_cross_shell.py
+tests/test_init_doctor.py
 tests/test_testing.py
 tests/test_validate.py

{toolrack_cli-0.2.0 → toolrack_cli-0.3.0}/tests/test_cli.py

@@ -1060,6 +1060,83 @@ class TestDeploymentConfig:
 
         assert result.stdout.strip() == "used-wrapper"
 
+    def _completion_source(self, shell, runner, monkeypatch, python="/venv/python"):
+        monkeypatch.setattr(cli, "CLI_NAME", "my-tools")
+        monkeypatch.setattr(cli, "COMPLETION_VAR", "_MY_TOOLS_COMPLETE")
+        monkeypatch.setattr(cli, "_resolve_bash_exe", lambda: "bash")
+        monkeypatch.setattr(cli, "_to_bash_path", lambda path, _bash: python)
+        result = runner.invoke(cli.cli, ["core", "install-completion", shell])
+        assert result.exit_code == 0
+        return result.output
+
+    def test_install_completion_zsh_calls_interpreter_directly(self, repo, runner, monkeypatch):
+        source = self._completion_source("zsh", runner, monkeypatch)
+
+        assert source.startswith("#compdef my-tools\n")
+        assert "env COMP_WORDS" not in source.split("_my_tools_completion_direct() {", 1)[0]
+        assert 'response=("${(@f)$(_my_tools_completion_direct "${words[*]}" $((CURRENT-1)))}")' in source
+        assert "/venv/python -m toolrack" in source
+        assert "TOOLRACK_CLI_NAME=my-tools" in source
+
+    def test_install_completion_fish_calls_interpreter_directly(self, repo, runner, monkeypatch):
+        source = self._completion_source("fish", runner, monkeypatch)
+
+        assert "set -l response (_my_tools_completion_direct (commandline -cp) (commandline -t));" in source
+        assert "function _my_tools_completion_direct" in source
+        assert "test -x '/venv/python'" in source
+        assert "'/venv/python' -m toolrack" in source
+        assert "TOOLRACK_CLI_NAME='my-tools'" in source
+
+    def test_install_completion_fish_skips_bypass_for_apostrophe_paths(self, repo, runner, monkeypatch):
+        source = self._completion_source("fish", runner, monkeypatch, python="/it's/python")
+        assert "_completion_direct" not in source
+        assert "env _MY_TOOLS_COMPLETE=fish_complete" in source
+
+    def test_zsh_bypass_leaves_unrecognised_scripts_alone(self):
+        assert cli._bypass_wrapper_in_zsh_completion("something else\n") == "something else\n"
+        assert cli._bypass_wrapper_in_fish_completion("something else\n") == "something else\n"
+
+    @pytest.mark.parametrize("use_python", [True, False])
+    def test_zsh_helper_runs_python_or_falls_back_to_wrapper(
+        self, repo, runner, monkeypatch, tmp_path, use_python
+    ):
+        import shutil
+        import subprocess
+
+        from toolrack.testing import bash_available
+
+        if shutil.which("bash") is None or not bash_available():
+            pytest.skip("bash not available")
+        fake_python = tmp_path / "python"
+        fake_python.write_text(
+            "#!/bin/sh\necho direct:$COMP_WORDS:$COMP_CWORD:$TOOLRACK_CLI_NAME\n", encoding="utf-8", newline="\n"
+        )
+        fake_python.chmod(0o755)
+        wrapper_dir = tmp_path / "wrapper"
+        wrapper_dir.mkdir()
+        wrapper = wrapper_dir / "my-tools"
+        wrapper.write_text(
+            "#!/bin/sh\necho wrapper:$COMP_WORDS:$COMP_CWORD:$_MY_TOOLS_COMPLETE\n", encoding="utf-8", newline="\n"
+        )
+        wrapper.chmod(0o755)
+        python = fake_python.as_posix() if use_python else (tmp_path / "missing").as_posix()
+        source = self._completion_source("zsh", runner, monkeypatch, python=python)
+        start = source.index("_my_tools_completion_direct() {")
+        helper = source[start : source.index("\n}\n", start) + 3]
+        script = tmp_path / "helper.sh"
+        script.write_text(helper, encoding="utf-8", newline="\n")
+
+        done = subprocess.run(
+            # cygpath: on Windows Git Bash a "C:/..." entry would be split at the colon.
+            [shutil.which("bash"), "-c",
+             f'd="{wrapper_dir.as_posix()}"; PATH="$(cygpath -u "$d" 2>/dev/null || echo "$d"):$PATH"; '
+             f'. "{script.as_posix()}"; _my_tools_completion_direct "my-tools co" 1'],
+            capture_output=True, text=True, check=False,
+        )
+
+        expected = "direct:my-tools co:1:my-tools" if use_python else "wrapper:my-tools co:1:zsh_complete"
+        assert done.stdout.strip() == expected, done.stderr
+
     def test_completion_returns_choice_values_for_typed_option(
             self, repo, make_script, make_sidecar, monkeypatch):
         from click.shell_completion import BashComplete

toolrack_cli-0.3.0/tests/test_init_doctor.py

@@ -0,0 +1,109 @@
+"""`core init` (scaffolding) and `core doctor` (installation diagnostics)."""
+
+from toolrack import cli, doctor, scaffold
+from toolrack.testing import ToolrackRepo
+
+
+def test_init_creates_a_working_repository(tmp_path):
+    root = tmp_path / "fresh"
+    repo = ToolrackRepo(root)
+    root.mkdir()
+
+    result = repo.run("core", "init", str(root)).check()
+
+    assert (root / "scripts" / "example" / "hello.py").is_file()
+    assert (root / "scripts" / "example" / "hello.yml").is_file()
+    assert repo.registered() == ["scripts/example/hello.py"]
+    assert ".toolrack.cache.json" in (root / ".gitignore").read_text()
+    assert "CREATED" in result.stdout
+    assert repo.run("example", "hello", "--name", "Ada").check().stdout.strip() == "hello, Ada"
+    repo.validate()
+
+
+def test_init_is_idempotent_and_never_overwrites(tmp_path):
+    root = tmp_path / "again"
+    root.mkdir()
+    repo = ToolrackRepo(root)
+    repo.run("core", "init", str(root)).check()
+    hello = root / "scripts" / "example" / "hello.py"
+    hello.write_text("print('mine')\n", encoding="utf-8")
+
+    second = repo.run("core", "init", str(root)).check()
+
+    assert hello.read_text() == "print('mine')\n"
+    assert "CREATED" not in second.stdout
+    assert repo.registered() == ["scripts/example/hello.py"]
+    assert (root / ".gitignore").read_text().count(".toolrack.cache.json") == 1
+
+
+def test_init_appends_to_existing_gitignore_and_registry(tmp_path):
+    (tmp_path / ".gitignore").write_text("dist/", encoding="utf-8")
+    (tmp_path / ".toolrack").write_text("scripts/mine.py\n", encoding="utf-8")
+
+    scaffold.scaffold_repository(str(tmp_path))
+
+    assert (tmp_path / ".gitignore").read_text() == "dist/\n.toolrack.cache.json\n"
+    assert (tmp_path / ".toolrack").read_text() == "scripts/mine.py\nscripts/example/hello.py\n"
+
+
+def test_init_no_example(tmp_path):
+    scaffold.scaffold_repository(str(tmp_path), example=False)
+    assert (tmp_path / "scripts").is_dir()
+    assert (tmp_path / ".toolrack").read_text() == ""
+    assert not (tmp_path / "scripts" / "example").exists()
+
+
+def _checks(repo, monkeypatch, legacy=None):
+    monkeypatch.setattr(doctor, "legacy_distribution", lambda: legacy)
+    return {c.name: c for c in doctor.run_checks(cli._current_repo(), "toolrack", cli._check_repository)}
+
+
+def test_doctor_reports_missing_repository(repo, monkeypatch):
+    checks = _checks(repo, monkeypatch)
+    assert checks["repository"].level == doctor.FAIL
+    assert "init" in checks["repository"].detail
+
+
+def test_doctor_healthy_repository(repo, make_script, make_sidecar, monkeypatch):
+    make_script("t/a.py")
+    make_sidecar("t/a.py", {"description": "a"})
+    repo["registry"].write_text("scripts/t/a.py\n", encoding="utf-8")
+    cli._refresh_cache()
+
+    checks = _checks(repo, monkeypatch)
+
+    assert checks["repository"].level == doctor.OK
+    assert checks["registered"].detail == "1 script(s)"
+    assert checks["validate"].level == doctor.OK
+    assert "legacy install" not in checks
+
+
+def test_doctor_flags_validation_errors(repo, monkeypatch):
+    repo["registry"].write_text("scripts/gone.py\n", encoding="utf-8")
+    assert _checks(repo, monkeypatch)["validate"].level == doctor.FAIL
+
+
+def test_doctor_warns_about_legacy_distribution(repo, monkeypatch):
+    repo["registry"].write_text("", encoding="utf-8")
+    check = _checks(repo, monkeypatch, legacy="0.0.1")["legacy install"]
+    assert check.level == doctor.WARN
+    assert "pip uninstall toolrack" in check.detail
+
+
+def test_doctor_requires_psql_for_sql_scripts(repo, make_script, make_sidecar, monkeypatch):
+    make_script("db/q.sql")
+    make_sidecar("db/q.sql", {"description": "q"})
+    repo["registry"].write_text("scripts/db/q.sql\n", encoding="utf-8")
+    monkeypatch.setattr(doctor.shutil, "which", lambda name: None)
+    assert _checks(repo, monkeypatch)["psql"].level == doctor.FAIL
+
+
+def test_doctor_command_exit_code(tmp_path):
+    root = tmp_path / "r"
+    root.mkdir()
+    repo = ToolrackRepo(root)
+    assert repo.run("core", "doctor").returncode == 1
+    repo.run("core", "init", str(root)).check()
+    result = repo.run("core", "doctor")
+    assert "[ok  ] repository" in result.stdout
+    assert "failures" in result.stdout