gcli-control 0.1.0__tar.gz → 0.2.0__tar.gz

{gcli_control-0.1.0 → gcli_control-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcli-control
-Version: 0.1.0
+Version: 0.2.0
 Summary: Remote access tool via npoint.io - encrypted command relay using AES-256-GCM
 Author: gcli contributors
 License-Expression: MIT

{gcli_control-0.1.0 → gcli_control-0.2.0}/gcli/__init__.py

@@ -2,5 +2,5 @@
 gcli — remote access tool via npoint.io.
 Encrypted command relay using AES-256-GCM over npoint.io JSON bins.
 """
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __author__ = "gcli"

gcli_control-0.2.0/gcli/aliases.py

@@ -0,0 +1,512 @@
+"""
+Command aliases and scripting for the gcli remote access tool.
+
+Provides named command aliases (create, remove, list, expand), batch
+script execution, and persistent alias storage via JSON files.
+
+Usage::
+
+    from gcli.aliases import dispatch, CommandAliases
+
+    # Remote command dispatch
+    result = dispatch({"type": "alias", "name": "ll", "command": "ls -la"})
+
+    # Local expansion
+    ca = CommandAliases()
+    ca.alias("ll", "ls -la")
+    expanded = ca.expand("ll -h")  # -> "ls -la -h"
+"""
+import json
+import os
+import sys
+import platform
+import logging
+import tempfile
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+logger = logging.getLogger("gcli.aliases")
+
+MAX_EXPANSION_DEPTH = 5
+
+_WINDOWS = platform.system() == "Windows"
+
+
+def _default_aliases() -> Dict[str, str]:
+    """Return the built-in alias set appropriate for the current OS."""
+    if _WINDOWS:
+        return {
+            "ll": "dir",
+            "la": "dir /a",
+            "cls": "cls",
+            "h": "doskey /history",
+            "..": "cd ..",
+        }
+    return {
+        "ll": "ls -la",
+        "la": "ls -a",
+        "cls": "clear",
+        "h": "history 20",
+        "..": "cd ..",
+    }
+
+
+class CommandAliases:
+    """Manages command aliases, expansion, persistence, and batch execution."""
+
+    def __init__(self) -> None:
+        self._aliases: Dict[str, str] = _default_aliases()
+
+    # ------------------------------------------------------------------
+    # Core alias management
+    # ------------------------------------------------------------------
+
+    def alias(self, name: str, command: str) -> dict:
+        """Create or overwrite a named alias.
+
+        Returns ``{"ok": True, "name": ..., "command": ...}`` on success.
+        """
+        if not name or not isinstance(name, str):
+            return {"ok": False, "error": "Alias name must be a non-empty string"}
+        if not command or not isinstance(command, str):
+            return {"ok": False, "error": "Alias command must be a non-empty string"}
+        self._aliases[name] = command
+        logger.debug("Alias set: %s -> %s", name, command)
+        return {"ok": True, "name": name, "command": command}
+
+    def unalias(self, name: str) -> dict:
+        """Remove a named alias.
+
+        Returns ``{"ok": True, "removed": name}`` on success.
+        """
+        if name not in self._aliases:
+            return {"ok": False, "error": f"Alias not found: {name!r}"}
+        del self._aliases[name]
+        logger.debug("Alias removed: %s", name)
+        return {"ok": True, "removed": name}
+
+    def list_aliases(self) -> dict:
+        """Return all current aliases.
+
+        Returns ``{"ok": True, "aliases": {...}, "count": n}``.
+        """
+        snapshot = dict(self._aliases)
+        return {"ok": True, "aliases": snapshot, "count": len(snapshot)}
+
+    # ------------------------------------------------------------------
+    # Expansion
+    # ------------------------------------------------------------------
+
+    def expand(self, command: str) -> str:
+        """Expand the first word of *command* if it matches an alias.
+
+        Follows alias references up to ``MAX_EXPANSION_DEPTH`` levels to
+        prevent infinite recursion.  Non-alias leading words are returned
+        unchanged.
+
+        >>> ca = CommandAliases()
+        >>> ca.alias("ll", "ls -la")
+        >>> ca.expand("ll -h")
+        'ls -la -h'
+        """
+        if not command:
+            return command
+
+        parts = command.split(None, 1)
+        if not parts:
+            return command
+
+        word = parts[0]
+        rest = (" " + parts[1]) if len(parts) > 1 else ""
+
+        visited: set = set()
+        for _ in range(MAX_EXPANSION_DEPTH):
+            if word not in self._aliases:
+                break
+            if word in visited:
+                logger.warning("Alias recursion detected for %r, stopping", word)
+                break
+            visited.add(word)
+            expansion = self._aliases[word]
+            # Re-split: the expansion may itself have arguments baked in,
+            # but we only track the leading word for the next hop.
+            exp_parts = expansion.split(None, 1)
+            word = exp_parts[0]
+            tail = (" " + exp_parts[1]) if len(exp_parts) > 1 else ""
+            # The trailing arguments from the original call always come last
+            rest = tail + rest
+
+        return word + rest
+
+    # ------------------------------------------------------------------
+    # Batch script execution
+    # ------------------------------------------------------------------
+
+    def run_script(self, commands: List[str],
+                   stop_on_error: bool = False) -> dict:
+        """Execute a list of shell commands sequentially.
+
+        Each command is expanded for aliases before execution.  Results are
+        returned in order.  When *stop_on_error* is ``True`` the script
+        halts on the first command whose ``ok`` field is ``False``.
+
+        Returns::
+
+            {"ok": True, "results": [...], "total": n, "succeeded": m, "failed": f}
+        """
+        if not isinstance(commands, list):
+            return {"ok": False, "error": "commands must be a list"}
+
+        from .utils import run_command  # local import to avoid circular deps at module level
+
+        results: List[dict] = []
+        succeeded = 0
+        failed = 0
+
+        for raw_cmd in commands:
+            if not isinstance(raw_cmd, str) or not raw_cmd.strip():
+                entry = {"cmd": str(raw_cmd), "ok": False, "output": "", "error": "empty command"}
+                results.append(entry)
+                failed += 1
+                if stop_on_error:
+                    break
+                continue
+
+            expanded = self.expand(raw_cmd.strip())
+            rc = run_command(expanded)
+            ok = rc.get("ok", False)
+            output = rc.get("stdout", "")
+            stderr = rc.get("stderr", "")
+            if stderr:
+                output = (output + "\n" + stderr).strip() if output else stderr
+
+            entry = {"cmd": raw_cmd, "ok": ok, "output": output}
+            results.append(entry)
+
+            if ok:
+                succeeded += 1
+            else:
+                failed += 1
+                if stop_on_error:
+                    break
+
+        total = succeeded + failed
+        return {
+            "ok": True,
+            "results": results,
+            "total": total,
+            "succeeded": succeeded,
+            "failed": failed,
+        }
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def save_aliases(self, path: str) -> dict:
+        """Persist the current alias dictionary to a JSON file.
+
+        Returns ``{"ok": True, "path": ..., "count": n}``.
+        """
+        try:
+            p = Path(path)
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_text(json.dumps(self._aliases, indent=2, sort_keys=True),
+                         encoding="utf-8")
+            logger.debug("Saved %d aliases to %s", len(self._aliases), path)
+            return {"ok": True, "path": str(p.resolve()), "count": len(self._aliases)}
+        except Exception as exc:
+            return {"ok": False, "error": str(exc)}
+
+    def load_aliases(self, path: str) -> dict:
+        """Load aliases from a JSON file and merge with current set.
+
+        Existing aliases are overwritten by any conflicting keys in the file.
+
+        Returns ``{"ok": True, "loaded": n, "total": m}``.
+        """
+        try:
+            p = Path(path)
+            if not p.exists():
+                return {"ok": False, "error": f"File not found: {path}"}
+            data = json.loads(p.read_text(encoding="utf-8"))
+            if not isinstance(data, dict):
+                return {"ok": False, "error": "Alias file must contain a JSON object"}
+            loaded = 0
+            for k, v in data.items():
+                if isinstance(k, str) and isinstance(v, str) and k and v:
+                    self._aliases[k] = v
+                    loaded += 1
+            logger.debug("Loaded %d aliases from %s", loaded, path)
+            return {"ok": True, "loaded": loaded, "total": len(self._aliases)}
+        except json.JSONDecodeError as exc:
+            return {"ok": False, "error": f"Invalid JSON: {exc}"}
+        except Exception as exc:
+            return {"ok": False, "error": str(exc)}
+
+    # ------------------------------------------------------------------
+    # Direct accessors (useful for integration)
+    # ------------------------------------------------------------------
+
+    @property
+    def aliases(self) -> Dict[str, str]:
+        """Read-only snapshot of the alias dictionary."""
+        return dict(self._aliases)
+
+    def clear(self) -> None:
+        """Remove all aliases (including built-ins)."""
+        self._aliases.clear()
+
+
+# ---------------------------------------------------------------------------
+# Singleton for dispatch
+# ---------------------------------------------------------------------------
+
+_instance: Optional[CommandAliases] = None
+
+
+def _get_instance() -> CommandAliases:
+    global _instance
+    if _instance is None:
+        _instance = CommandAliases()
+    return _instance
+
+
+# ---------------------------------------------------------------------------
+# Remote command dispatcher
+# ---------------------------------------------------------------------------
+
+_HANDLERS: Dict[str, Callable[..., dict]] = {}
+
+
+def _register(name: str):
+    """Decorator that registers a handler function for a command type."""
+    def decorator(fn: Callable[..., dict]) -> Callable[..., dict]:
+        _HANDLERS[name] = fn
+        return fn
+    return decorator
+
+
+@_register("alias")
+def _handle_alias(payload: dict) -> dict:
+    name = payload.get("name", "")
+    command = payload.get("command", "")
+    return _get_instance().alias(name, command)
+
+
+@_register("unalias")
+def _handle_unalias(payload: dict) -> dict:
+    name = payload.get("name", "")
+    return _get_instance().unalias(name)
+
+
+@_register("list_aliases")
+def _handle_list(payload: dict) -> dict:
+    return _get_instance().list_aliases()
+
+
+@_register("run_script")
+def _handle_run_script(payload: dict) -> dict:
+    commands = payload.get("commands", [])
+    stop_on_error = payload.get("stop_on_error", False)
+    return _get_instance().run_script(commands, stop_on_error)
+
+
+@_register("save_aliases")
+def _handle_save(payload: dict) -> dict:
+    path = payload.get("path", "")
+    if not path:
+        return {"ok": False, "error": "No path specified"}
+    return _get_instance().save_aliases(path)
+
+
+@_register("load_aliases")
+def _handle_load(payload: dict) -> dict:
+    path = payload.get("path", "")
+    if not path:
+        return {"ok": False, "error": "No path specified"}
+    return _get_instance().load_aliases(path)
+
+
+def dispatch(payload: dict) -> dict:
+    """Route an alias-related command payload to the correct handler.
+
+    Parameters
+    ----------
+    payload:
+        A dict with at least a ``"type"`` key matching one of the supported
+        command names (alias, unalias, list_aliases, run_script,
+        save_aliases, load_aliases).
+
+    Returns
+    -------
+    dict
+        ``{"ok": True, ...}`` on success, or ``{"ok": False, "error": ...}``
+        on failure.
+    """
+    cmd_type = payload.get("type", "")
+    handler = _HANDLERS.get(cmd_type)
+    if handler is None:
+        return {"ok": False, "error": f"Unknown alias command: {cmd_type!r}"}
+    return handler(payload)
+
+
+# ---------------------------------------------------------------------------
+# Self-test
+# ---------------------------------------------------------------------------
+
+def test_aliases() -> None:
+    """Exercise every capability of the aliases module."""
+    passed = 0
+    failed = 0
+
+    def check(desc: str, condition: bool) -> None:
+        nonlocal passed, failed
+        if condition:
+            passed += 1
+        else:
+            failed += 1
+            print(f"  FAIL: {desc}")
+
+    try:
+        # -- built-in aliases loaded --
+        ca = CommandAliases()
+        r = ca.list_aliases()
+        check("list_aliases ok", r["ok"])
+        check("ll built-in present", "ll" in r["aliases"])
+        check("la built-in present", "la" in r["aliases"])
+        check("cls built-in present", "cls" in r["aliases"])
+        check("h built-in present", "h" in r["aliases"])
+        check(".. built-in present", ".." in r["aliases"])
+
+        # -- create alias --
+        r = ca.alias("greet", "echo hello")
+        check("alias create ok", r["ok"])
+        check("alias name returned", r["name"] == "greet")
+        check("alias command returned", r["command"] == "echo hello")
+
+        # -- create alias validation --
+        r = ca.alias("", "echo hi")
+        check("alias empty name fails", not r["ok"])
+        r = ca.alias("x", "")
+        check("alias empty command fails", not r["ok"])
+
+        # -- list includes new alias --
+        r = ca.list_aliases()
+        check("new alias in list", "greet" in r["aliases"])
+        check("list count correct", r["count"] == len(r["aliases"]))
+
+        # -- expand --
+        result = ca.expand("greet world")
+        check("expand greet", result == "echo hello world")
+
+        result = ca.expand("ll -la")
+        check("expand ll", result.endswith("-la"))
+        check("expand ll has ls", result.startswith("ls") or result.startswith("dir"))
+
+        result = ca.expand("unknown_cmd arg")
+        check("expand unknown unchanged", result == "unknown_cmd arg")
+
+        result = ca.expand("")
+        check("expand empty unchanged", result == "")
+
+        # -- alias chaining (one level) --
+        ca.alias("g1", "greet there")
+        result = ca.expand("g1")
+        check("chain g1 -> greet", result == "echo hello there")
+
+        # -- alias recursion prevention --
+        ca.alias("a", "b extra")
+        ca.alias("b", "a more")
+        result = ca.expand("a")
+        check("recursion stops", "a" in result or "b" in result)
+
+        # -- unalias --
+        r = ca.unalias("greet")
+        check("unalias ok", r["ok"])
+        check("unalias removed name", r["removed"] == "greet")
+
+        r = ca.unalias("greet")
+        check("unalias missing fails", not r["ok"])
+
+        # -- run_script --
+        r = ca.run_script(["echo first", "echo second", "echo third"])
+        check("run_script ok", r["ok"])
+        check("run_script total", r["total"] == 3)
+        check("run_script succeeded", r["succeeded"] == 3)
+        check("run_script failed", r["failed"] == 0)
+        check("run_script results len", len(r["results"]) == 3)
+
+        # -- run_script with alias expansion --
+        ca.alias("greet", "echo hello")
+        r = ca.run_script(["greet"])
+        check("run_script alias expand", r["ok"])
+        check("run_script alias output", "hello" in r["results"][0].get("output", ""))
+
+        # -- run_script with bad command and stop_on_error --
+        r = ca.run_script(["echo ok", "false_command_xyz_999", "echo never"],
+                          stop_on_error=True)
+        check("run_script stop_on_error ok", r["ok"])
+        check("run_script stopped early", r["total"] < 3)
+
+        # -- run_script invalid input --
+        r = ca.run_script("not a list")
+        check("run_script non-list fails", not r["ok"])
+
+        # -- save / load round-trip --
+        tmp = Path(tempfile.mkdtemp(prefix="gcli_alias_test_"))
+        save_path = str(tmp / "aliases.json")
+        r = ca.save_aliases(save_path)
+        check("save_aliases ok", r["ok"])
+        check("save_aliases count", r["count"] > 0)
+
+        # Create a fresh instance and load
+        ca2 = CommandAliases()
+        ca2.clear()
+        r = ca2.load_aliases(save_path)
+        check("load_aliases ok", r["ok"])
+        check("load_aliases loaded", r["loaded"] > 0)
+        check("load_aliases preserves greet", "greet" in ca2.aliases)
+
+        # -- load missing file --
+        r = ca2.load_aliases("/nonexistent/path/xyz.json")
+        check("load missing file fails", not r["ok"])
+
+        # -- load invalid JSON --
+        bad_path = str(tmp / "bad.json")
+        Path(bad_path).write_text("{invalid json", encoding="utf-8")
+        r = ca2.load_aliases(bad_path)
+        check("load bad json fails", not r["ok"])
+
+        # -- save to nonexistent parent --
+        r = ca.save_aliases(str(tmp / "deep" / "nest" / "aliases.json"))
+        check("save creates parents", r["ok"])
+
+        # -- dispatch routing --
+        r = dispatch({"type": "alias", "name": "test1", "command": "echo test"})
+        check("dispatch alias", r["ok"])
+        r = dispatch({"type": "unalias", "name": "test1"})
+        check("dispatch unalias", r["ok"])
+        r = dispatch({"type": "list_aliases"})
+        check("dispatch list_aliases", r["ok"])
+        r = dispatch({"type": "run_script", "commands": ["echo x"]})
+        check("dispatch run_script", r["ok"])
+        r = dispatch({"type": "bogus"})
+        check("dispatch unknown fails", not r["ok"])
+
+    except Exception as exc:
+        failed += 1
+        print(f"  EXCEPTION: {exc}")
+    finally:
+        # Cleanup temp dir
+        try:
+            import shutil
+            shutil.rmtree(tmp, ignore_errors=True)
+        except Exception:
+            pass
+
+    print(f"aliases tests: {passed} passed, {failed} failed")
+
+
+if __name__ == "__main__":
+    test_aliases()