cmdchain 0.1.0__py3-none-any.whl

clichain/__init__.py

@@ -0,0 +1,29 @@
+"""clichain — Fluent CLI tool chaining for Python."""
+
+from clichain.checks import CheckResult, env, file_exists
+from clichain.core import (
+    Cmd,
+    MeterStats,
+    Pipeline,
+    Result,
+    StepProfile,
+    _version,
+    set_output,
+    tool,
+)
+
+__version__ = _version
+
+__all__ = [
+    "CheckResult",
+    "Cmd",
+    "MeterStats",
+    "Pipeline",
+    "Result",
+    "StepProfile",
+    "__version__",
+    "env",
+    "file_exists",
+    "set_output",
+    "tool",
+]

clichain/checks.py

@@ -0,0 +1,177 @@
+"""Preflight checks: binary, env, file_exists, and custom checks."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+OnFail = Literal["error", "warn", "pass"]
+
+
+@dataclass
+class CheckResult:
+    ok: bool
+    name: str
+    expected: str
+    found: str
+    msg: str
+    on_fail: OnFail
+
+    @property
+    def should_stop(self) -> bool:
+        return not self.ok and self.on_fail == "error"
+
+    @property
+    def should_report(self) -> bool:
+        if self.ok:
+            return True
+        return self.on_fail != "pass"
+
+    def format(self) -> str:
+        if self.ok:
+            return f"  ok: {self.name} ({self.found})"
+        label = "error" if self.on_fail == "error" else "warn"
+        if self.msg:
+            return f"  {label}: {self.name} — {self.msg}"
+        return f"  {label}: {self.name} — expected {self.expected}, found {self.found}"
+
+
+def _detect_version(binary: str) -> str | None:
+    path = shutil.which(binary)
+    if not path:
+        return None
+    for flag in ["--version", "-version", "version", "-v"]:
+        try:
+            proc = subprocess.run(
+                [path, flag],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            text = proc.stdout + proc.stderr
+            match = re.search(r"(\d+\.\d+(?:\.\d+)?)", text)
+            if match:
+                return match.group(1)
+        except (subprocess.TimeoutExpired, OSError):
+            continue
+    return None
+
+
+def _version_satisfies(found: str, constraint: str) -> bool:
+    """Check simple version constraints like >=1.7, <3.0, >=6.0,<8.0."""
+    found_parts = [int(x) for x in found.split(".")]
+
+    for part in constraint.split(","):
+        part = part.strip()
+        if part.startswith(">="):
+            req = [int(x) for x in part[2:].split(".")]
+            if found_parts < req:
+                return False
+        elif part.startswith("<="):
+            req = [int(x) for x in part[2:].split(".")]
+            if found_parts > req:
+                return False
+        elif part.startswith(">"):
+            req = [int(x) for x in part[1:].split(".")]
+            if found_parts <= req:
+                return False
+        elif part.startswith("<"):
+            req = [int(x) for x in part[1:].split(".")]
+            if found_parts >= req:
+                return False
+        elif part.startswith("=="):
+            req = [int(x) for x in part[2:].split(".")]
+            if found_parts != req:
+                return False
+    return True
+
+
+def binary_check(
+    name: str,
+    version: str | None = None,
+    on_fail: OnFail = "error",
+    msg: str = "",
+) -> Callable[[], CheckResult]:
+    def _check() -> CheckResult:
+        path = shutil.which(name)
+        if not path:
+            return CheckResult(
+                ok=False,
+                name=name,
+                expected="on $PATH" + (f" {version}" if version else ""),
+                found="not found",
+                msg=msg or f"{name} not found on $PATH",
+                on_fail=on_fail,
+            )
+
+        if not version:
+            return CheckResult(
+                ok=True,
+                name=name,
+                expected="on $PATH",
+                found=f"{path}",
+                msg=msg,
+                on_fail=on_fail,
+            )
+
+        detected = _detect_version(name)
+        if not detected:
+            return CheckResult(
+                ok=True,
+                name=name,
+                expected=version,
+                found=f"{path} (version unknown)",
+                msg=msg,
+                on_fail=on_fail,
+            )
+
+        satisfied = _version_satisfies(detected, version)
+        return CheckResult(
+            ok=satisfied,
+            name=name,
+            expected=version,
+            found=f"{detected} at {path}",
+            msg=msg or (f"{name} {detected} does not satisfy {version}" if not satisfied else ""),
+            on_fail=on_fail,
+        )
+
+    return _check
+
+
+def env(name: str, on_fail: OnFail = "error", msg: str = "") -> Callable[[], CheckResult]:
+    def _check() -> CheckResult:
+        value = os.environ.get(name)
+        return CheckResult(
+            ok=value is not None,
+            name=f"env:{name}",
+            expected="set",
+            found="set" if value is not None else "not set",
+            msg=msg or f"environment variable {name} is not set",
+            on_fail=on_fail,
+        )
+
+    return _check
+
+
+def file_exists(path: str, on_fail: OnFail = "error", msg: str = "") -> Callable[[], CheckResult]:
+    def _check() -> CheckResult:
+        exists = os.path.exists(path)
+        return CheckResult(
+            ok=exists,
+            name=f"file:{path}",
+            expected="exists",
+            found="exists" if exists else f"not found (cwd: {os.getcwd()})",
+            msg=msg or f"file {path} not found",
+            on_fail=on_fail,
+        )
+
+    return _check
+
+
+def run_checks(checks: list[Callable[[], CheckResult]]) -> list[CheckResult]:
+    return [check() for check in checks]

clichain/cli.py

@@ -0,0 +1,151 @@
+"""clichain CLI — compile, explain, check."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    from clichain.core import _ERROR_DETAIL, _EXIT_CODES, _SIGNALS
+
+    code = args.code.upper()
+
+    if code.startswith("S"):
+        sig = int(code[1:])
+        if sig in _SIGNALS:
+            name, desc = _SIGNALS[sig]
+            print(f"error[{code}]: signal {sig} ({name})")
+            print(f"  {desc}")
+        else:
+            print(f"error[{code}]: signal {sig}")
+            print("  unknown signal")
+    elif code.startswith("X"):
+        exit_code = int(code[1:])
+        if exit_code in _EXIT_CODES:
+            print(f"error[{code}]: exit {exit_code}")
+            print(f"  {_EXIT_CODES[exit_code]}")
+        else:
+            print(f"error[{code}]: exit {exit_code}")
+            print("  unknown exit code")
+    else:
+        print(f"unknown error code: {code}")
+        return 1
+
+    detail = _ERROR_DETAIL.get(code)
+    if detail:
+        print()
+        print(f"  {detail}")
+
+    return 0
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    import importlib.util
+
+    from clichain.core import Pipeline, set_output
+
+    set_output(sys.stderr)
+
+    spec = importlib.util.spec_from_file_location("__clichain_script__", args.script)
+    if not spec or not spec.loader:
+        print(f"error: cannot load {args.script}", file=sys.stderr)
+        return 1
+
+    # Import the script — this will create tool() instances
+    # but won't run pipelines unless they call .run() at module level
+    module = importlib.util.module_from_spec(spec)
+
+    # Collect all Cmd and Pipeline objects after import
+    import contextlib
+
+    with contextlib.suppress(SystemExit):
+        spec.loader.exec_module(module)
+
+    # Find all Pipeline/Cmd objects in the module and check them
+    from clichain.core import Cmd
+
+    checked = False
+    for name in dir(module):
+        obj = getattr(module, name)
+        if isinstance(obj, Pipeline):
+            print(f"pipeline: {name}", file=sys.stderr)
+            obj.check()
+            checked = True
+        elif isinstance(obj, Cmd):
+            print(f"tool: {name} ({obj._binary})", file=sys.stderr)
+            obj.check()
+            checked = True
+
+    if not checked:
+        print("no pipelines or tools found in script", file=sys.stderr)
+
+    return 0
+
+
+def cmd_compile(args: argparse.Namespace) -> int:
+    import importlib.util
+
+    if importlib.util.find_spec("PyInstaller") is None:
+        print(
+            "error: pyinstaller not installed\n  install with: pip install cmdchain[compile]",
+            file=sys.stderr,
+        )
+        return 1
+
+    from PyInstaller import __main__ as pyinstaller_main  # type: ignore[import-not-found]
+
+    script = args.script
+    output = args.output or script.rsplit(".", 1)[0]
+
+    pyinstaller_args = [
+        script,
+        "--onefile",
+        "--name",
+        output,
+        "--noconfirm",
+    ]
+
+    if args.clean:
+        pyinstaller_args.append("--clean")
+
+    print(f"compiling {script} -> {output}")
+    pyinstaller_main.run(pyinstaller_args)
+
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="clichain",
+        description="CLI tool chaining for Python",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # explain
+    p_explain = sub.add_parser("explain", help="explain an error code")
+    p_explain.add_argument("code", help="error code (e.g. S13, X127)")
+
+    # check
+    p_check = sub.add_parser("check", help="preflight a script")
+    p_check.add_argument("script", help="path to .py script")
+
+    # compile
+    p_compile = sub.add_parser("compile", help="compile script to binary")
+    p_compile.add_argument("script", help="path to .py script")
+    p_compile.add_argument("-o", "--output", help="output binary name")
+    p_compile.add_argument("--clean", action="store_true", help="clean build artifacts")
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    handlers = {
+        "explain": cmd_explain,
+        "check": cmd_check,
+        "compile": cmd_compile,
+    }
+
+    sys.exit(handlers[args.command](args))