caurad 0.10.1__tar.gz

caurad-0.10.1/.gitignore

@@ -0,0 +1,36 @@
+# Go build artifacts
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+vendor/
+
+# Coverage and profiling
+*.coverprofile
+coverage.txt
+*.prof
+cover.out
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS metadata
+.DS_Store
+Thumbs.db
+
+# Secrets and local config (no secrets in repo per Constitution)
+.env
+.env.*
+*.local
+/bin/
+
+# Python bytecode (uvx wrapper py_compile)
+__pycache__/
+*.pyc
+dist/

caurad-0.10.1/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: caurad
+Version: 0.10.1
+Summary: uvx/pip wrapper for the Caura broker: downloads the platform binary from the public release mirror, SHA-256-verifies it, and execs it.
+Project-URL: Homepage, https://caura.ai
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# `caurad` — uvx / pip wrapper
+
+Run the Caura broker from the Python ecosystem:
+
+```bash
+uvx caurad --help                        # run without installing
+pipx install caurad && caurad --help     # or install the canonical entry point
+```
+
+## How it works
+
+This package is a thin dispatcher — the broker itself is a single Go binary.
+
+On first canonical or compatibility entry-point invocation,
+`wrappers/uvx/caurad/cli.py` detects your
+platform, downloads the matching signed archive from the public release mirror,
+verifies its SHA-256 against the published `checksums.txt`, caches the binary
+under `~/.cache/memclawd/<version>/`, and `os.execv`s it with your arguments —
+so `uvx caurad <args>` behaves like the native `memclaw <args>`. Subsequent <!-- legacy-name-floor: installed entry point -->
+invocations reuse the cached binary.
+
+The install itself does NOT prefetch the binary — the download happens on first
+invocation. That keeps the package tiny and works under pipx / sandboxed
+installs where postinstall hooks don't fire.
+
+The binary is downloaded from the public release mirror
+(`https://memclaw.net/memclaw/<tag>/`) — the same source the
+`wrappers/curl/install.sh` installer uses, not this repo's GitHub Releases
+(which are private). SHA-256 verification is the integrity gate.
+
+## Environment overrides
+
+Both are also read under their historical `MEMCLAW_*` spellings<!-- legacy-name-ok: rule 3 dual-read alias -->, which keep
+working indefinitely; the `CAURA_*` name wins when it holds a non-empty value.
+
+- `CAURA_BINARY_BASE` — base URL of a release mirror (default
+  `https://memclaw.net/memclaw`). Point it at an on-prem gateway's
+  `<origin>/memclaw` to install from a private deployment.
+- `CAURA_VERSION` — pin a specific release tag instead of the installed
+  package's version.
+
+The published package version is set from the release tag by the PyPI-publish
+workflow; the `0.0.0` in `pyproject.toml` is a placeholder for local checkouts.
+
+## Compatibility name
+
+Existing `pip install memclawd` and `uvx --from memclawd memclaw` commands keep working through <!-- legacy-name-ok: permanent PyPI compatibility alias -->
+the separate compatibility package, which depends on `caurad`. New installation
+instructions should use the canonical name above.
+
+Licensed under Apache-2.0, matching the `LICENSE` at the repository root.

caurad-0.10.1/README.md

@@ -0,0 +1,51 @@
+# `caurad` — uvx / pip wrapper
+
+Run the Caura broker from the Python ecosystem:
+
+```bash
+uvx caurad --help                        # run without installing
+pipx install caurad && caurad --help     # or install the canonical entry point
+```
+
+## How it works
+
+This package is a thin dispatcher — the broker itself is a single Go binary.
+
+On first canonical or compatibility entry-point invocation,
+`wrappers/uvx/caurad/cli.py` detects your
+platform, downloads the matching signed archive from the public release mirror,
+verifies its SHA-256 against the published `checksums.txt`, caches the binary
+under `~/.cache/memclawd/<version>/`, and `os.execv`s it with your arguments —
+so `uvx caurad <args>` behaves like the native `memclaw <args>`. Subsequent <!-- legacy-name-floor: installed entry point -->
+invocations reuse the cached binary.
+
+The install itself does NOT prefetch the binary — the download happens on first
+invocation. That keeps the package tiny and works under pipx / sandboxed
+installs where postinstall hooks don't fire.
+
+The binary is downloaded from the public release mirror
+(`https://memclaw.net/memclaw/<tag>/`) — the same source the
+`wrappers/curl/install.sh` installer uses, not this repo's GitHub Releases
+(which are private). SHA-256 verification is the integrity gate.
+
+## Environment overrides
+
+Both are also read under their historical `MEMCLAW_*` spellings<!-- legacy-name-ok: rule 3 dual-read alias -->, which keep
+working indefinitely; the `CAURA_*` name wins when it holds a non-empty value.
+
+- `CAURA_BINARY_BASE` — base URL of a release mirror (default
+  `https://memclaw.net/memclaw`). Point it at an on-prem gateway's
+  `<origin>/memclaw` to install from a private deployment.
+- `CAURA_VERSION` — pin a specific release tag instead of the installed
+  package's version.
+
+The published package version is set from the release tag by the PyPI-publish
+workflow; the `0.0.0` in `pyproject.toml` is a placeholder for local checkouts.
+
+## Compatibility name
+
+Existing `pip install memclawd` and `uvx --from memclawd memclaw` commands keep working through <!-- legacy-name-ok: permanent PyPI compatibility alias -->
+the separate compatibility package, which depends on `caurad`. New installation
+instructions should use the canonical name above.
+
+Licensed under Apache-2.0, matching the `LICENSE` at the repository root.

caurad-0.10.1/caurad/__init__.py

@@ -0,0 +1 @@
+"""Python wrapper for downloading and dispatching the Caura broker."""

caurad-0.10.1/caurad/cli.py

@@ -0,0 +1,273 @@
+"""Caura broker — uvx/pip wrapper entry point.
+
+On first invocation, downloads the platform-specific signed binary
+from the public release mirror, verifies SHA-256 against the
+published checksums, caches the binary under
+``~/.cache/memclawd/<version>/``, and execs it with forwarded args.
+Subsequent invocations reuse the cached binary.
+
+The pip / uvx install does NOT prefetch the binary — fetching
+happens on first ``memclaw`` invocation. This keeps the Python
+package small (just this dispatcher) and works under pipx /
+sandboxes where postinstall hooks aren't fired.
+
+What this script does NOT do:
+- Auto-start the daemon (operator runs ``memclaw start``).
+- Modify shell rc files.
+- Verify GPG signatures (T118 is the additive layer; SHA-256 is
+  baseline).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata as md
+import os
+import platform
+import shutil
+import sys
+import tarfile
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+from urllib.parse import urlparse
+
+# Both spellings, CAURA_* first. Resolution below is first NON-EMPTY,
+# not first defined: an operator whose environment carries a blank
+# CAURA_BINARY_BASE beside a working old-spelling one would otherwise
+# silently fetch from the public mirror instead of their private
+# deployment. Same contract as wrappers/curl/install.sh and the npx
+# wrapper — one name set, every entry point honors it.
+VERSION_ENV_CAURA = "CAURA_VERSION"
+VERSION_ENV = "MEMCLAW_VERSION"  # legacy-name-ok: rule 3 dual-read alias
+BINARY_BASE_ENV_CAURA = "CAURA_BINARY_BASE"
+BINARY_BASE_ENV = "MEMCLAW_BINARY_BASE"  # legacy-name-ok: rule 3 dual-read alias
+# Binaries come from the public release mirror, NOT this repo's GitHub
+# Releases: the repo is private, so unauthenticated downloads 404. The
+# mirror layout matches wrappers/curl/install.sh — <base>/<tag>/<archive>
+# — and is owned by publish-mirror.yml. On-prem gateways serve their
+# own mirror at <origin>/memclaw  # legacy-name-floor: the served mirror path
+# — set CAURA_BINARY_BASE to install from a private deployment.
+DEFAULT_BINARY_BASE = "https://memclaw.net/memclaw"
+
+
+def die(msg: str) -> int:
+    print(f"memclaw: {msg}", file=sys.stderr)
+    return 1
+
+
+def package_version() -> str:
+    """Return the broker version this wrapper expects to dispatch.
+
+    Sourced from the installed package metadata (which the release
+    pipeline rewrites per release) unless CAURA_VERSION (or its
+    historical spelling) is set. Strips a leading 'v' so the GitHub
+    Release tag form converts cleanly to the goreleaser archive's
+    version segment.
+    """
+    if v := _resolve(VERSION_ENV_CAURA, VERSION_ENV)[0]:
+        return v.lstrip("v")
+    try:
+        v = md.version("caurad")
+        return v.lstrip("v")
+    except md.PackageNotFoundError:
+        return "0.0.0-dev"
+
+
+def detect_platform() -> tuple[str, str, bool]:
+    """Return (os, arch, exe) tuple matching the goreleaser archive
+    naming. ``exe`` is True only on Windows.
+    """
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64"):
+        arch = "x86_64"
+    elif machine in ("arm64", "aarch64"):
+        arch = "arm64"
+    else:
+        raise RuntimeError(f"unsupported arch: {machine}")
+    if system == "darwin":
+        return "darwin", arch, False
+    if system == "linux":
+        return "linux", arch, False
+    if system.startswith(("win", "msys", "cygwin")):
+        return "windows", arch, True
+    raise RuntimeError(f"unsupported OS: {system}")
+
+
+def archive_url(base: str, version: str, os_name: str, arch: str, exe: bool) -> str:
+    """Construct the mirror archive URL: ``<base>/<tag>/<archive>``.
+
+    The tag directory carries a leading "v" (``version`` is stripped of
+    it); archive names do not. Names follow the goreleaser template.
+    """
+    ext = "zip" if exe else "tar.gz"
+    return f"{base}/v{version}/memclaw_{version}_{os_name}_{arch}.{ext}"
+
+
+def checksums_url(base: str, version: str) -> str:
+    return f"{base}/v{version}/checksums.txt"
+
+
+def _resolve(caura: str, legacy: str, default: str = "") -> tuple[str, str]:
+    """The first of the two names holding a NON-EMPTY value, and its name.
+
+    Returning the name is the same reason internal/envname.Lookup does: a
+    message naming the variable the operator actually set is actionable, and
+    one naming the other spelling sends them to edit something they never
+    wrote. Falls back to `default` under `caura`'s name, which is the one to
+    teach when neither was set.
+    """
+    for name in (caura, legacy):
+        if v := os.environ.get(name):
+            return v, name
+    return default, caura
+
+
+def _validate_base_url(base: str, name: str) -> None:
+    """Require an https:// binary base.
+
+    urllib.request.urlopen honors file://, ftp://, plain http://, etc.
+    The archive and its checksums.txt are fetched from the same base, so
+    the SHA-256 check only detects tampering when TLS authenticates the
+    origin — plain http:// would let a network attacker swap both. https
+    also matches the npm wrapper (Node's https.get) and the wrapper's
+    original always-https download path.
+    """
+    scheme = urlparse(base).scheme
+    if scheme != "https":
+        raise RuntimeError(
+            f"{name} must be https, got {scheme!r} in {base!r}"
+        )
+
+
+def download(url: str, dest: Path) -> None:
+    """Stream `url` to `dest`. Raises on non-200."""
+    with urllib.request.urlopen(url) as resp:  # noqa: S310 — scheme validated (https) in ensure_binary
+        if resp.status != 200:
+            raise RuntimeError(f"HTTP {resp.status} for {url}")
+        with dest.open("wb") as f:
+            shutil.copyfileobj(resp, f)
+
+
+def fetch_text(url: str) -> str:
+    with urllib.request.urlopen(url) as resp:  # noqa: S310 — scheme validated (https) in ensure_binary
+        if resp.status != 200:
+            raise RuntimeError(f"HTTP {resp.status} for {url}")
+        return resp.read().decode("utf-8")
+
+
+def sha256_of(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def cache_dir(version: str) -> Path:
+    base = Path(os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache")))
+    return base / "memclawd" / version
+
+
+def _extract_tar_safely(tf: tarfile.TarFile, dest: Path) -> None:
+    """Extract ``tf`` into ``dest``, rejecting members that escape ``dest``.
+
+    Prefers the stdlib data filter, but the ``filter=`` keyword only exists
+    on Python 3.12+ (backported to 3.11.4, alongside ``tarfile.data_filter``
+    — so ``hasattr`` feature-detects it exactly). On older interpreters —
+    e.g. stock Debian 12 ships 3.11.2 — passing it raises ``TypeError`` and
+    the wrapper never installs its binary. There, hand-check each member:
+    allow only regular files and directories whose resolved path stays
+    inside ``dest`` (rejecting absolute paths, ``..`` traversal, and
+    symlink/device members). That is a narrower guard than ``data_filter``,
+    which is fine here — the archive is a SHA-256-verified, single-binary
+    goreleaser tarball, not arbitrary input.
+    """
+    if hasattr(tarfile, "data_filter"):
+        tf.extractall(dest, filter="data")
+        return
+    dest_resolved = dest.resolve()
+    for member in tf.getmembers():
+        if not (member.isfile() or member.isdir()):
+            raise RuntimeError(f"non-regular member in tar archive: {member.name!r}")
+        if not (dest / member.name).resolve().is_relative_to(dest_resolved):
+            raise RuntimeError(f"unsafe path in tar archive: {member.name!r}")
+    tf.extractall(dest)  # members validated above
+
+
+def ensure_binary(version: str) -> Path:
+    """Return the absolute path to the cached binary, downloading
+    if necessary. Raises on any integrity failure.
+    """
+    os_name, arch, exe = detect_platform()
+    base, base_name = _resolve(
+        BINARY_BASE_ENV_CAURA, BINARY_BASE_ENV, DEFAULT_BINARY_BASE
+    )
+    base = base.rstrip("/")
+    _validate_base_url(base, base_name)
+    bin_name = "memclaw.exe" if exe else "memclaw"
+    cache = cache_dir(version)
+    bin_path = cache / bin_name
+    if bin_path.exists():
+        return bin_path
+
+    cache.mkdir(parents=True, exist_ok=True)
+    arch_name = f"memclaw_{version}_{os_name}_{arch}.{'zip' if exe else 'tar.gz'}"
+    archive_url_full = archive_url(base, version, os_name, arch, exe)
+
+    print(f"memclaw: downloading {archive_url_full}", file=sys.stderr)
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_dir = Path(tmp)
+        archive_path = tmp_dir / arch_name
+        download(archive_url_full, archive_path)
+
+        # Verify SHA-256.
+        sums = fetch_text(checksums_url(base, version))
+        expected = None
+        for line in sums.splitlines():
+            parts = line.split()
+            if len(parts) >= 2 and parts[-1] == arch_name:
+                expected = parts[0]
+                break
+        if expected is None:
+            raise RuntimeError(f"no checksum entry for {arch_name}")
+        actual = sha256_of(archive_path)
+        if actual != expected:
+            raise RuntimeError(
+                f"checksum mismatch for {arch_name}: expected={expected} actual={actual}"
+            )
+
+        # Extract.
+        if exe:
+            with zipfile.ZipFile(archive_path) as zf:
+                zf.extractall(tmp_dir)
+        else:
+            with tarfile.open(archive_path, "r:gz") as tf:
+                # Safe extract, guarded for Pythons without the filter kwarg.
+                _extract_tar_safely(tf, tmp_dir)
+        src = tmp_dir / bin_name
+        if not src.exists():
+            raise RuntimeError(f"archive did not contain {bin_name}")
+        shutil.move(str(src), str(bin_path))
+        if not exe:
+            bin_path.chmod(0o755)
+    return bin_path
+
+
+def main() -> int:
+    try:
+        version = package_version()
+        bin_path = ensure_binary(version)
+    except (RuntimeError, OSError) as err:
+        return die(str(err))
+    # os.execv replaces the Python process with the binary, so
+    # stdout/stderr/stdin/signals all flow naturally. argv[0] is
+    # the binary's own name to match what `exec memclaw ...`
+    # would produce.
+    os.execv(str(bin_path), [str(bin_path), *sys.argv[1:]])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

caurad-0.10.1/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "caurad"
+version = "0.10.1"
+description = "uvx/pip wrapper for the Caura broker: downloads the platform binary from the public release mirror, SHA-256-verifies it, and execs it."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+
+[project.urls]
+Homepage = "https://caura.ai"
+
+[project.scripts]
+caurad = "caurad.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["caurad"]