xmemcli 0.0.1__py3-none-any.whl

xmemcli/_rc.py

@@ -0,0 +1,192 @@
+"""Project-local ``.xmemrc.json`` credential store.
+
+The CLI resolves its API key and API origin from a **project-local**
+``.xmemrc.json`` found by walking **up** from ``--rc-dir`` / ``$XMEM_RC_DIR``
+(or the current directory). The search does **not** stop at the repository root
+and is **ceilinged at ``$HOME``** — ``~/.xmemrc.json`` is the last fallback.
+
+The file is stdlib JSON, strongly typed ``{email, api_url, api_key}`` (one
+identity per file; extras / missing / non-string keys are rejected). The ``0600``
+atomic writer is used by ``xmem auth login``; see ``cli/AUTH-FLOW.md``.
+
+Resolution precedence (applied by ``cli/xmem.py``): ``--api-key`` → ``$XMEM_API_KEY`` → ``.xmemrc.json``; and
+``--api-url`` → ``$XMEM_API_URL`` → the rc's ``api_url`` → the built-in default — **with one escape hatch**: when the
+key comes from an explicit ``--api-key`` / ``$XMEM_API_KEY`` (not from the rc), the rc's ``api_url`` is **not**
+consulted and the origin falls back straight to the built-in default. That keeps an explicitly supplied key from being
+silently paired with an unrelated origin stored in a project ``.xmemrc.json``.
+"""
+
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import NamedTuple
+
+RC_FILENAME = ".xmemrc.json"
+ENV_RC_DIR = "XMEM_RC_DIR"
+
+# The exact, complete set of keys an `.xmemrc.json` must contain — no more, no
+# fewer. Keeping it closed means a typo'd or extended file fails loudly instead
+# of silently ignoring a field.
+_RC_KEYS = ("email", "api_url", "api_key")
+
+
+class RcError(Exception):
+    """An ``.xmemrc.json`` exists but is malformed (bad JSON or wrong shape)."""
+
+
+class RcRecord(NamedTuple):
+    """One identity loaded from a project-local ``.xmemrc.json``.
+
+    A ``typing.NamedTuple`` (immutable, typed, attribute-accessed) rather than a
+    ``@dataclass`` or the repo's ``TightBaseModel``: this CLI is stdlib-only and
+    standalone — it runs without a ``pip install`` of the ``xmemory`` library
+    (see ``cli/xmem.py``) — so it deliberately avoids the pydantic-based base
+    models, and ``NamedTuple`` gives a frozen record with no third-party dep.
+    """
+
+    email: str
+    api_url: str
+    api_key: str
+    path: Path
+
+
+def _home() -> Path:
+    return Path(os.path.expanduser("~")).resolve()
+
+
+def _within_home(directory: Path, home: Path) -> bool:
+    """True iff ``directory`` is ``$HOME`` itself or a descendant of it."""
+    return directory == home or home in directory.parents
+
+
+def find_rc(start_dir: Path) -> Path | None:
+    """Return the nearest ``.xmemrc.json`` at or above ``start_dir``, ceilinged at ``$HOME``.
+
+    Walk upward from ``start_dir`` checking each directory, but **never ascend
+    past ``$HOME``**: a parent is visited only while it stays within the home
+    subtree. ``start_dir`` itself is always checked — so an explicitly chosen
+    ``--rc-dir`` outside ``$HOME`` is still honoured — but from an out-of-home
+    start the walk does **not** climb into shared parents like ``/tmp`` or ``/``
+    (which is where a stray ``.xmemrc.json`` could otherwise be picked up). If
+    nothing is found, fall back to ``~/.xmemrc.json``; returns ``None`` when no
+    rc file exists.
+    """
+    home = _home()
+    directory = start_dir.resolve()
+    while True:
+        candidate = directory / RC_FILENAME
+        if candidate.is_file():
+            return candidate
+        parent = directory.parent
+        # Stop at the home ceiling, at the filesystem root, or just before
+        # stepping outside the home subtree.
+        if directory == home or parent == directory or not _within_home(parent, home):
+            break
+        directory = parent
+    home_rc = home / RC_FILENAME
+    return home_rc if home_rc.is_file() else None
+
+
+def load_rc(path: Path) -> RcRecord:
+    """Parse and validate an ``.xmemrc.json``; raise ``RcError`` if malformed."""
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RcError(f"{path}: could not read JSON ({exc})") from exc
+    if not isinstance(raw, dict):
+        raise RcError(f"{path}: expected a JSON object, got {type(raw).__name__}")
+    keys = set(raw.keys())
+    expected = set(_RC_KEYS)
+    if keys != expected:
+        missing = sorted(expected - keys)
+        extra = sorted(keys - expected)
+        detail = ", ".join(
+            part
+            for part in (
+                f"missing {missing}" if missing else "",
+                f"unexpected {extra}" if extra else "",
+            )
+            if part
+        )
+        raise RcError(f"{path}: must contain exactly {list(_RC_KEYS)} ({detail})")
+    for key in _RC_KEYS:
+        if not isinstance(raw[key], str):
+            raise RcError(f"{path}: '{key}' must be a string")
+    return RcRecord(email=raw["email"], api_url=raw["api_url"], api_key=raw["api_key"], path=path)
+
+
+def resolve_rc(rc_dir: str | None) -> RcRecord | None:
+    """Resolve the active ``.xmemrc.json`` honouring ``--rc-dir`` / ``$XMEM_RC_DIR``.
+
+    ``rc_dir`` is the ``--rc-dir`` flag value (or ``None``); it falls back to
+    ``$XMEM_RC_DIR`` and then the current working directory. Returns ``None``
+    when no rc file is found; raises ``RcError`` when one exists but is malformed.
+    """
+    start = Path(rc_dir or os.environ.get(ENV_RC_DIR) or os.getcwd())
+    found = find_rc(start)
+    return load_rc(found) if found is not None else None
+
+
+def write_rc(target_dir: Path, *, email: str, api_url: str, api_key: str) -> Path:
+    """Write ``target_dir/.xmemrc.json`` at ``0600``, atomically."""
+    target_dir.mkdir(parents=True, exist_ok=True)
+    path = target_dir / RC_FILENAME
+    fd, tmp_name = tempfile.mkstemp(dir=str(target_dir), prefix=".xmemrc.", suffix=".tmp")
+    fd_owned = True
+    success = False
+    try:
+        os.chmod(tmp_name, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fd_owned = False
+            json.dump({"email": email, "api_url": api_url, "api_key": api_key}, fh, indent=2)
+            fh.write("\n")
+        os.replace(tmp_name, path)
+        success = True
+    finally:
+        if fd_owned:
+            os.close(fd)
+        if not success:
+            try:
+                os.unlink(tmp_name)
+            except FileNotFoundError:
+                pass
+    return path
+
+
+def remove_rc(path: Path) -> bool:
+    """Delete the ``.xmemrc.json`` at ``path``. Returns ``True`` iff it existed."""
+    try:
+        path.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def gitignore_warning(rc_path: Path) -> str | None:
+    """Warn if ``rc_path`` is inside a git repo and not gitignored."""
+    parent = str(rc_path.parent)
+    try:
+        inside = subprocess.run(
+            ["git", "-C", parent, "rev-parse", "--is-inside-work-tree"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (OSError, ValueError):
+        return None
+    if inside.returncode != 0 or inside.stdout.strip() != "true":
+        return None
+    ignored = subprocess.run(
+        ["git", "-C", parent, "check-ignore", "-q", rc_path.name],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if ignored.returncode == 0:
+        return None
+    return (
+        f"{rc_path} holds a plaintext API key and is NOT gitignored. "
+        f"Add this line to .gitignore so it is never committed:\n    {RC_FILENAME}"
+    )

xmemcli/_version.py

@@ -0,0 +1,4 @@
+"""Release metadata for the xmemcli CLI (copied into standalone builds)."""
+
+CLI_NAME = "xmemcli"
+__version__ = "0.0.1"

xmemcli/_xmem_bridge.py

@@ -0,0 +1,33 @@
+"""Shared lazy binding to the active ``xmem`` command module."""
+
+import importlib
+import sys
+from typing import Any
+
+INSTANCE_FIELDS = ("id", "name", "description", "cluster_id")
+
+
+def xmem_module() -> Any:
+    main_mod = sys.modules.get("__main__")
+    if main_mod is not None and hasattr(main_mod, "_require"):
+        return main_mod
+    try:
+        return importlib.import_module("xmem")
+    except ModuleNotFoundError:
+        return importlib.import_module("xmemcli.cli")  # pyright: ignore[reportMissingImports]
+
+
+def curate_instance(item: dict[str, Any], verbose: bool) -> dict[str, Any]:
+    """Shared instance list/get curation for org and schema command modules."""
+    m = xmem_module()
+    curated = {k: item[k] for k in INSTANCE_FIELDS if k in item}
+    if verbose and "data_schema" in item:
+        curated["data_schema"] = item["data_schema"]
+    return m._add_verbose_extras(curated, item, verbose)
+
+
+def http_to_exit(status: int | None) -> int:
+    m = xmem_module()
+    if status in (401, 403):
+        return m.EXIT_AUTH_ERROR
+    return m.EXIT_HTTP_ERROR