memorysync-cli 1.1.0__tar.gz → 1.1.2__tar.gz

{memorysync_cli-1.1.0 → memorysync_cli-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memorysync-cli
-Version: 1.1.0
+Version: 1.1.2
 Summary: MemorySync from your terminal. Zero dependencies.
 Project-URL: Documentation, https://docs.memorysync.io/cli
 Project-URL: Homepage, https://memorysync.io/cli

memorysync_cli-1.1.2/src/memorysync_cli/_version.py

@@ -0,0 +1 @@
+__version__ = "1.1.2"

{memorysync_cli-1.1.0 → memorysync_cli-1.1.2}/src/memorysync_cli/args.py

@@ -27,29 +27,40 @@ from __future__ import annotations
 
 from typing import Any
 
+from . import registry
 from .errors import usage_error
 
-# Flags that take a value. Everything else is boolean. Kept in step with the
-# Node CLI's VALUED set; the parity test asserts every registry flag is known
-# here, so a flag added there cannot go unhandled.
-VALUED = {
-    "profile",
-    "api-key",
-    "base-url",
-    "user",
-    "project",
-    "output",
-    "timeout",
-    "metadata",
-    "file",
-    "source",
-    "limit",
-    "importance",
-    "batch-size",
-    "out",
-    "format",
-    "query",
-}
+
+def _collect_valued() -> set[str]:
+    """Flags that take a value. Everything else is boolean.
+
+    Derived from the shared registry rather than hand-listed, matching
+    ``sdk/cli/src/args.mjs``. The registry already marks a value-taking flag with
+    ``value``, and keeping a second copy of that fact here meant the two could
+    disagree - which they did: ``--email``, ``--code``, ``--password`` and
+    ``--agent-caller`` were declared with a ``value`` but missing from the set, so
+    ``--email you@example.com`` parsed as ``{"email": True}`` and sent the string
+    "true" to the API. ``--password`` was worse: the account password became
+    "true" and the real one was left in shell history as a positional.
+
+    A flag is valued if any declaration of it says so, including on a subcommand.
+    """
+    valued: set[str] = set()
+
+    def visit(flags: list[dict[str, Any]] | None) -> None:
+        for flag in flags or []:
+            if flag.get("value"):
+                valued.add(flag["name"].lstrip("-"))
+
+    visit(registry.global_flags())
+    for spec in registry.commands().values():
+        visit(spec.get("flags"))
+        for sub in spec.get("subcommands", []):
+            visit(sub.get("flags"))
+    return valued
+
+
+VALUED = _collect_valued()
 
 SHORT = {
     "p": "profile",

memorysync_cli-1.1.2/src/memorysync_cli/commands/admin.py

@@ -0,0 +1,586 @@
+"""quota, status, doctor, whoami, project, event, config.
+
+``quota`` and ``doctor`` are the two none of the competitors have. Both exist
+because of one API behaviour: over a plan limit the API returns success with an
+empty result rather than an error, so that an assistant never narrates billing
+state to an end user. That is right for the API and unhelpful in a terminal, where
+"nothing came back" and "you are out of quota" need to be distinguishable before
+someone spends an afternoon debugging an empty search.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import platform
+import sys
+import time
+from datetime import datetime, timezone
+from typing import Any, Mapping
+
+from .. import config as config_module
+from .. import credentials
+from .._version import __version__
+from ..errors import usage_error
+from ..evaluation import is_evaluation_key
+from ..output import render_table, style
+
+#: Keys ``config set`` / ``config unset`` accept. Identical to the Node CLI's
+#: ``SETTABLE``; ``output`` was previously missing here, so `config set output table`
+#: worked under one CLI and was refused by the other.
+#:
+#: ``api_key`` is deliberately absent. Keys go to the keychain through ``init``, and
+#: accepting one here would write a credential into a file people paste into bug
+#: reports.
+#: Declaration order, for the error message. A frozenset has no order, and
+#: sorting it put the keys in a different order from the Node CLI's message.
+_SETTABLE_ORDER = ("user", "project", "base_url", "output", "timeout")
+_SETTABLE = frozenset(_SETTABLE_ORDER)
+
+
+def _quota_rows(usage: Mapping[str, Any]) -> list[dict[str, Any]]:
+    """Per-metric usage with a percentage. Mirrors the Node CLI's ``quotaRows``.
+
+    ``percent`` is a number rounded to one decimal, not a preformatted string. It
+    used to be ``"1%"`` here and ``0.5`` in the Node CLI, so an agent reading
+    ``--json`` from the two got different types for the same field.
+    """
+    rows = []
+    for entry in usage.get("metrics") or []:
+        if not isinstance(entry, dict):
+            continue
+        limit = entry.get("limit")
+        used = entry.get("used")
+        if isinstance(limit, (int, float)) and limit and isinstance(used, (int, float)):
+            percent = min(100, round(used / limit * 1000) / 10)
+            # Match JavaScript, where 0.5 prints as "0.5" and 12.0 prints as "12".
+            if percent == int(percent):
+                percent = int(percent)
+        else:
+            limit = None
+            percent = 0
+        rows.append(
+            {
+                "metric": entry.get("metric"),
+                "label": entry.get("label"),
+                "used": used,
+                "limit": limit,
+                "percent": percent,
+            }
+        )
+    return rows
+
+
+def _bar(percent: float, width: int = 24) -> str:
+    """The usage bar, identical to the Node CLI's ``bar``.
+
+    Green under 80%, yellow from 80, red at 100. The filled portion is coloured and
+    the remainder dimmed, so the shape reads the same without colour.
+    """
+    filled = max(0, min(width, round(percent / 100 * width)))
+    if percent >= 100:
+        painter = style.red
+    elif percent >= 80:
+        painter = style.yellow
+    else:
+        painter = style.green
+    return painter("\u2588" * filled) + style.dim("\u2591" * (width - filled))
+
+
+def _days_until(iso: Any) -> int | None:
+    """Whole days from now until *iso*, or ``None`` when it cannot be read."""
+    if not iso:
+        return None
+    try:
+        text = str(iso).replace("Z", "+00:00")
+        end = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if end.tzinfo is None:
+        end = end.replace(tzinfo=timezone.utc)
+    seconds = (end - datetime.now(timezone.utc)).total_seconds()
+    return max(0, math.ceil(seconds / 86400))
+
+
+def _evaluation_usage_summary(api: Any) -> tuple[dict, dict]:
+    """Reshape ``/evaluation/usage`` into what ``quota`` already renders.
+
+    Same keys the billing summary returns, so the renderer and ``--json`` consumers
+    do not have to care which kind of key they are looking at. Mirrors the Node
+    CLI's ``evaluationQuota``, including the cycle fields this used to drop - so
+    ``days_until_reset`` and ``resets_at`` came back null under this CLI and
+    populated under the Node one.
+    """
+    usage = api.evaluation_usage() or {}
+    add = usage.get("add_requests") or {}
+    retrieval = usage.get("retrieval_requests") or {}
+    cycle_start = usage.get("cycle_start")
+    summary = {
+        "plan_id": usage.get("plan"),
+        "billing_period": str(cycle_start)[:7] if cycle_start else None,
+        "current_period_end": usage.get("cycle_end"),
+        "days_until_reset": _days_until(usage.get("cycle_end")),
+        "metrics": [
+            {
+                "metric": "add_requests",
+                "label": "Memories added",
+                "used": add.get("used"),
+                "limit": add.get("limit"),
+            },
+            {
+                "metric": "retrieval_requests",
+                "label": "Retrievals",
+                "used": retrieval.get("used"),
+                "limit": retrieval.get("limit"),
+            },
+        ],
+    }
+    extra = {
+        "claimed": usage.get("claimed") is True,
+        "expires_at": usage.get("expires_at"),
+        "claim_command": usage.get("claim_command"),
+    }
+    return summary, extra
+
+
+def quota(ctx: dict) -> dict:
+    """Plan usage, with headroom made explicit.
+
+    The one command that turns the API's deliberate silence into a number. None of
+    Mem0, Supermemory or Zep expose this from their CLI.
+    """
+    api = ctx["api"]
+
+    extra: dict[str, Any] = {}
+    if is_evaluation_key(ctx.get("api_key")):
+        # ``/org/billing/usage-summary`` needs the ``billing.view`` capability and
+        # the ``billing:read`` scope, and an evaluation key is granted neither on
+        # purpose: ``billing:read`` also opens ``GET /org/billing/profit``, which
+        # returns cost and margin from our internal pricing model. The server
+        # exposes the same counters without the priced fields, so route there.
+        summary, extra = _evaluation_usage_summary(api)
+    else:
+        summary = api.usage_summary() or {}
+
+    rows = _quota_rows(summary)
+    data = {
+        "billing_period": summary.get("billing_period"),
+        "plan_id": summary.get("plan_id"),
+        "days_until_reset": summary.get("days_until_reset"),
+        "resets_at": summary.get("current_period_end"),
+        "metrics": rows,
+        **extra,
+    }
+
+    def render() -> str:
+        lines = [
+            f"{style.bold('Plan')} {summary.get('plan_id')}   "
+            f"{style.dim('period ' + str(summary.get('billing_period')))}",
+            "",
+        ]
+        for row in rows:
+            limit = "unlimited" if row["limit"] is None else f"{row['limit']:,}"
+            suffix = "" if row["limit"] is None else f"  {row['percent']}%"
+            label = str(row["label"] or "").ljust(20)
+            lines.append(
+                f"{label} {_bar(row['percent'])}  {str(row['used']).rjust(7)} / {limit}{suffix}"
+            )
+
+        exhausted = [
+            r for r in rows if r["limit"] is not None and (r["used"] or 0) >= r["limit"]
+        ]
+        near = [
+            r
+            for r in rows
+            if r["limit"] is not None and r["percent"] >= 80 and (r["used"] or 0) < r["limit"]
+        ]
+        lines.append("")
+        if exhausted:
+            lines.append(
+                style.red(
+                    " and ".join(str(r["label"]) for r in exhausted)
+                    + " exhausted. Calls now return empty results instead of errors, "
+                    "so nothing is being stored or retrieved."
+                )
+            )
+        elif near:
+            lines.append(
+                style.yellow(" and ".join(str(r["label"]) for r in near) + " above 80%.")
+            )
+        if summary.get("days_until_reset") is not None:
+            lines.append(style.dim(f"Resets in {summary['days_until_reset']} day(s)."))
+        if extra and not extra.get("claimed") and extra.get("expires_at"):
+            # An evaluation allowance does not reset on the cycle: the key stops
+            # working at expiry, so the date that matters is that one.
+            lines.append(
+                style.yellow(
+                    f"Unclaimed evaluation key, expires {str(extra['expires_at'])[:10]}."
+                )
+            )
+        return "\n".join(lines)
+
+    return {"data": data, "text": render}
+
+
+def status(ctx: dict) -> dict:
+    """Reachability and identity in one call."""
+    api = ctx["api"]
+    started = time.monotonic()
+    plan = api.current_plan() or {}
+    latency = int((time.monotonic() - started) * 1000)
+
+    payload = {
+        "api": ctx["settings"]["base_url"],
+        "reachable": True,
+        "latency_ms": latency,
+        "plan": plan.get("plan") or plan.get("name"),
+        "cycle_ends": plan.get("current_period_end") or plan.get("cycle_ends"),
+    }
+
+    def render() -> str:
+        return "\n".join(
+            [
+                f"{style.dim('api        ')} {payload['api']}",
+                f"{style.dim('reachable  ')} {style.green('yes')} ({latency}ms)",
+                f"{style.dim('plan       ')} {payload['plan'] or '-'}",
+                f"{style.dim('cycle ends ')} {payload['cycle_ends'] or '-'}",
+            ]
+        )
+
+    return {"data": payload, "text": render}
+
+
+def whoami(ctx: dict) -> dict:
+    """Who this credential is, without printing the credential."""
+    settings = ctx["settings"]
+    api = ctx["api"]
+    plan = api.current_plan() or {}
+
+    payload = {
+        "profile": settings["profile_name"],
+        "base_url": settings["base_url"],
+        "user": settings.get("user"),
+        "project": settings.get("project"),
+        "plan": plan.get("plan") or plan.get("name"),
+        "credential_source": credentials.describe_storage(settings["profile_name"]),
+    }
+
+    def render() -> str:
+        return "\n".join(
+            f"{style.dim(key.ljust(18))} {value if value not in (None, '') else '-'}"
+            for key, value in payload.items()
+        )
+
+    return {"data": payload, "text": render}
+
+
+def doctor(ctx: dict) -> dict:
+    """Diagnose a broken setup and exit 0 either way.
+
+    Exiting 0 even when checks fail is deliberate: this is a diagnostic, and a
+    non-zero exit would make it useless inside `set -e` scripts, which is exactly
+    where someone reaches for it.
+    """
+    settings = ctx["settings"]
+    api = ctx.get("api")
+    checks: list[dict[str, Any]] = []
+
+    def add(name: str, ok: bool | None, detail: str, hint: str | None = None) -> None:
+        checks.append(
+            {
+                "check": name,
+                "status": "pass" if ok else ("warn" if ok is None else "fail"),
+                "detail": detail,
+                **({"hint": hint} if hint else {}),
+            }
+        )
+
+    version_ok = sys.version_info >= (3, 9)
+    add(
+        "python",
+        version_ok,
+        platform.python_version(),
+        None if version_ok else "MemorySync needs Python 3.9 or newer.",
+    )
+    add("cli", True, f"memorysync-cli {__version__}")
+    add("config", True, str(config_module.config_path()))
+    add("credential store", True, credentials.describe_storage(settings["profile_name"]))
+
+    key = credentials.read_key(settings["profile_name"])
+    add(
+        "api key",
+        bool(key),
+        f"found ({key[:8]}...)" if key else "not found",
+        # Names the cross-CLI case explicitly. Someone who ran `init` moments ago
+        # and is told "not found" will otherwise reasonably conclude the CLI is
+        # broken, when on Windows the key is simply in the other CLI's store.
+        None
+        if key
+        else (
+            "Run `memorysync init`, or set MEMORYSYNC_API_KEY. If you stored a key "
+            "with the Node CLI on Windows, it is not shared: the two use different "
+            "ciphers, so run init here as well."
+        ),
+    )
+    add(
+        "end user",
+        bool(settings.get("user")) or None,
+        settings.get("user") or "not set",
+        None if settings.get("user") else "Memory calls need --user or a stored default.",
+    )
+
+    if api is not None:
+        started = time.monotonic()
+        try:
+            api.current_plan()
+            add("api reachable", True, f"{settings['base_url']} in {int((time.monotonic() - started) * 1000)}ms")
+        except Exception as error:  # noqa: BLE001 - a diagnostic reports, never raises
+            add("api reachable", False, str(error), "Check the network, the base URL and the key.")
+    else:
+        add("api reachable", None, "skipped, no credential", "Store a key first.")
+
+    def render() -> str:
+        marks = {"pass": style.green("ok  "), "warn": style.yellow("warn"), "fail": style.red("fail")}
+        lines = []
+        for entry in checks:
+            lines.append(f"{marks[entry['status']]} {entry['check'].ljust(18)} {entry['detail']}")
+            if entry.get("hint"):
+                lines.append(f"     {style.dim(entry['hint'])}")
+        failures = sum(1 for entry in checks if entry["status"] == "fail")
+        summary = (
+            style.green("Everything checks out.")
+            if failures == 0
+            else style.yellow(f"{failures} check(s) need attention.")
+        )
+        return "\n".join([*lines, "", summary])
+
+    return {"data": checks, "text": render}
+
+
+def project(ctx: dict) -> dict:
+    """List projects, or show the one in scope."""
+    positionals, api = ctx["positionals"], ctx["api"]
+    sub = positionals[0] if positionals else "list"
+
+    if sub not in {"list", "show"}:
+        raise usage_error(f'Unknown subcommand "{sub}".', "Try list or show.")
+
+    raw = api.projects()
+    entries = raw if isinstance(raw, list) else (raw or {}).get("projects") or []
+    projects = [
+        {
+            "id": entry.get("id") or entry.get("project_id"),
+            "name": entry.get("name"),
+            "tenant_id": entry.get("tenant_id"),
+            "is_default": entry.get("is_default"),
+        }
+        for entry in entries
+        if isinstance(entry, dict)
+    ]
+
+    if sub == "show":
+        current = ctx["settings"].get("project")
+        match = next((p for p in projects if p["id"] == current), None) or (
+            projects[0] if projects else None
+        )
+        return {
+            "data": match,
+            "text": lambda: (
+                "\n".join(f"{style.dim(k.ljust(12))} {v}" for k, v in (match or {}).items())
+                if match
+                else style.dim("No projects found.")
+            ),
+        }
+
+    def render() -> str:
+        if not projects:
+            return style.dim("No projects found.")
+        return render_table(
+            ["id", "name", "tenant", "default"],
+            [[p["id"], p["name"], p["tenant_id"], "yes" if p["is_default"] else ""] for p in projects],
+        )
+
+    return {"data": projects, "text": render}
+
+
+def event(ctx: dict) -> dict:
+    """Ingestion state for one memory.
+
+    Named `event` to match the Node CLI and Mem0, both of which use it for
+    background processing state.
+    """
+    from .memory import _numeric_id
+
+    positionals, api = ctx["positionals"], ctx["api"]
+    sub = positionals[0] if positionals else None
+
+    if sub != "status":
+        raise usage_error(
+            "Which event?",
+            "memorysync event status m_60632",
+        )
+    if len(positionals) < 2:
+        raise usage_error("Which memory?", "memorysync event status m_60632")
+
+    payload = api.memory_status(_numeric_id(positionals[1])) or {}
+
+    def render() -> str:
+        return "\n".join(
+            f"{style.dim(key.ljust(24))} {'-' if value is None else value}"
+            for key, value in payload.items()
+        )
+
+    return {"data": payload, "text": render}
+
+
+def config_command(ctx: dict) -> dict:
+    """Read and write the local config file.
+
+    ``set`` never accepts an api_key: keys go to the keychain through `init`, and
+    accepting one here would write a credential into a file people paste into bug
+    reports.
+    """
+    positionals = ctx["positionals"]
+    sub = positionals[0] if positionals else "show"
+
+    if sub == "show":
+        data = config_module.redacted()
+        return {
+            "data": data,
+            # Three labelled lines then the profiles as JSON, matching the Node CLI.
+            # This used to print a `path` line and a one-line-per-profile summary,
+            # which told the user less and matched nothing.
+            "text": lambda: "\n".join(
+                [
+                    f"{style.dim('file           ')} {config_module.config_path()}",
+                    f"{style.dim('active profile ')} {data.get('current_profile')}",
+                    f"{style.dim('key storage    ')} {credentials.describe_storage()}",
+                    "",
+                    json.dumps(data.get("profiles", {}), indent=2),
+                ]
+            ),
+        }
+
+    if sub == "profiles":
+        cfg = config_module.load()
+        current = cfg.get("current_profile", "default")
+        profiles = cfg.get("profiles", {})
+        rows = [
+            [
+                style.green("*") if name == current else " ",
+                name,
+                entry.get("user") or "-",
+                entry.get("project") or "-",
+                entry.get("base_url") or "(default)",
+            ]
+            for name, entry in profiles.items()
+        ]
+
+        def render_profiles() -> str:
+            if not rows:
+                return style.dim("No profiles. Run `memorysync init`.")
+            return render_table([" ", "profile", "user", "project", "base url"], rows)
+
+        return {
+            "data": {"current": current, "profiles": profiles},
+            "text": render_profiles,
+        }
+
+    if sub == "use-profile":
+        if len(positionals) < 2:
+            raise usage_error("Which profile?")
+        name = positionals[1]
+        cfg = config_module.load()
+        if name not in cfg.get("profiles", {}):
+            raise usage_error(
+                f'No profile named "{name}".',
+                "Run `memorysync config profiles` to see what exists, or "
+                f"`memorysync init --profile {name}` to create it.",
+            )
+        cfg["current_profile"] = name
+        config_module.save(cfg)
+        return {
+            "data": {"current_profile": name},
+            "text": lambda: f"{style.green('Switched to')} {name}",
+        }
+
+    if sub == "delete-profile":
+        if len(positionals) < 2:
+            raise usage_error("Which profile?")
+        name = positionals[1]
+        cfg = config_module.load()
+        if name not in cfg.get("profiles", {}):
+            raise usage_error(f'No profile named "{name}".')
+        del cfg["profiles"][name]
+        if cfg.get("current_profile") == name:
+            remaining = list(cfg.get("profiles", {}))
+            cfg["current_profile"] = remaining[0] if remaining else "default"
+        config_module.save(cfg)
+        # The stored credential goes with the profile. Leaving it behind would keep
+        # a usable key in the keychain for a profile the user just removed.
+        credentials.delete_key(name)
+        return {
+            "data": {"deleted": name},
+            "text": lambda: f"{style.green('Deleted profile')} {name}",
+        }
+
+    if sub == "get":
+        if len(positionals) < 2:
+            raise usage_error("Which key?", "memorysync config get user")
+        key = positionals[1]
+        # Reads the stored profile, not the resolved value. Matches the Node CLI:
+        # `config get` answers "what is written down", so an environment variable
+        # does not make it look as though something was saved.
+        cfg = config_module.load()
+        entry = cfg.get("profiles", {}).get(cfg.get("current_profile", "default"), {})
+        value = entry.get(key)
+        return {"data": {key: value}, "text": lambda: "" if value is None else str(value)}
+
+    if sub in {"set", "unset"}:
+        if len(positionals) < 2:
+            raise usage_error(
+                "Which key?", f"Settable: {', '.join(sorted(_SETTABLE))}"
+            )
+        key = positionals[1]
+        if key in {"api_key", "apikey", "key"}:
+            raise usage_error(
+                "Keys are not stored in the config file.",
+                "Run `memorysync init --api-key <key>`; it goes to the OS keychain.",
+            )
+        if key not in _SETTABLE:
+            raise usage_error(
+                f'"{key}" is not settable.',
+                # Declaration order, not sorted: the Node CLI lists them in the
+                # order they are declared and the two messages have to match.
+                f"Settable keys: {', '.join(_SETTABLE_ORDER)}. The API key is "
+                "never stored here; use `memorysync init`.",
+            )
+        if sub == "set" and len(positionals) < 3:
+            raise usage_error(f"config set {key} <value>")
+        value = positionals[2] if sub == "set" else None
+
+        cfg = config_module.load()
+        name = cfg.get("current_profile", "default")
+        entry = dict(cfg.get("profiles", {}).get(name, {}))
+        if sub == "set":
+            entry[key] = value
+        else:
+            entry.pop(key, None)
+        cfg.setdefault("profiles", {})[name] = entry
+        config_module.save(cfg)
+        return {
+            "data": {"profile": name, key: value},
+            "text": lambda: (
+                f"{style.green('Set' if sub == 'set' else 'Unset')} {key} "
+                f"on profile {name}"
+            ),
+        }
+
+    if sub == "path":
+        path = str(config_module.config_path())
+        return {"data": {"path": path}, "text": lambda: path}
+
+    raise usage_error(
+        f'Unknown subcommand "{sub}".', "Try `memorysync config show`."
+    )