memorysync-cli 1.0.2__py3-none-any.whl

memorysync_cli/main.py

@@ -0,0 +1,325 @@
+"""Entry point and dispatch.
+
+Mirrors ``sdk/cli/src/main.mjs`` step for step, because the order of these
+decisions is observable. Resolving the format before validating flags, for
+instance, is what lets a bad flag still come back as a JSON envelope when the
+caller asked for agent mode - an agent that sent a malformed command line still
+needs a parseable answer rather than prose on stderr.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from typing import Any, Callable
+
+from . import config as config_module
+from . import registry
+from .args import parse_args, suggest
+from .commands import admin, init as init_command, memory, source as source_command, tooling
+from .credentials import read_key
+from .errors import CliError, Exit, auth_error, usage_error
+from .http import ApiClient
+from .output import (
+    emit,
+    error_envelope,
+    set_colour_enabled,
+    style,
+    success_envelope,
+    write,
+)
+
+Handler = Callable[[dict], dict]
+
+# command name -> handler. Kept beside the registry so a gap is obvious in review,
+# which is the same reason the Node CLI keeps its HANDLERS map next to its own. A
+# name in the registry with no entry here fails as "not available" rather than
+# "unknown command", so `help --json` stays honest about what exists.
+_HANDLERS: dict[str, Handler] = {
+    "init": init_command.init,
+    "add": memory.add,
+    "search": memory.search,
+    "list": memory.list_memories,
+    "get": memory.get,
+    "update": memory.update,
+    "delete": memory.delete_memories,
+    "import": memory.import_memories,
+    "export": memory.export_memories,
+    "quota": admin.quota,
+    "status": admin.status,
+    "doctor": admin.doctor,
+    "whoami": admin.whoami,
+    "project": admin.project,
+    "source": source_command.source,
+    "event": admin.event,
+    "config": admin.config_command,
+    "mcp": tooling.mcp,
+    "completion": tooling.completion,
+    "help": tooling.help_command,
+    "version": tooling.version,
+}
+
+
+def _not_implemented(name: str) -> Handler:
+    """A declared command with no implementation yet fails as itself.
+
+    Deliberately not an unknown-command error: the registry is shared, so the
+    command genuinely exists and `help --json` advertises it. Saying "not
+    available" is honest, where "unknown command" would read as a typo and send
+    someone looking for the wrong problem.
+    """
+
+    def handler(_ctx: dict) -> dict:
+        raise CliError(
+            f'"{name}" is not available in this build yet.',
+            exit_code=Exit.USAGE,
+            code="not_implemented",
+            hint="Run `memorysync help` to see what is.",
+        )
+
+    return handler
+
+
+def _resolve_format(flags: dict, agent_mode: bool) -> str:
+    """Pick the format, returning an invalid one unchanged.
+
+    An unknown format is not rejected here on purpose. The caller validates it
+    inside the try block, so the resulting error is still wrapped in an envelope
+    when agent mode was requested.
+    """
+    if agent_mode:
+        return "json"
+    requested = flags.get("output") or os.environ.get("MEMORYSYNC_OUTPUT")
+    if not requested:
+        return "quiet" if flags.get("quiet") else "text"
+    return requested
+
+
+def _resolve_settings(flags: dict) -> dict:
+    """Settings for this invocation: flag, then environment, then config, then default."""
+    return config_module.resolve(flags)
+
+
+def _scope_of(settings: dict) -> dict:
+    scope = {}
+    if settings.get("user"):
+        scope["user"] = settings["user"]
+    if settings.get("project"):
+        scope["project"] = settings["project"]
+    if settings.get("profile_name"):
+        scope["profile"] = settings["profile_name"]
+    return scope
+
+
+def _allowed_flags(name: str, sub: str | None = None) -> set[str]:
+    """Every flag this command accepts: its own, its subcommand's, and globals."""
+    allowed = {"help"}
+    for flag in registry.global_flags():
+        allowed.add(flag["name"].lstrip("-").replace("-", "_"))
+    for flag in registry.flags_for(name, sub):
+        allowed.add(flag["name"].lstrip("-").replace("-", "_"))
+    # `--no-x` parses to key `x`; both spellings map to the same key already.
+    allowed.add("agent")
+    allowed.add("color")
+    allowed.add("dedupe")
+    allowed.add("rerank")
+    return allowed
+
+
+def _reject_unknown_flags(flags: dict, allowed: set[str]) -> None:
+    """Refuse a flag this command does not take.
+
+    Ignoring it would be worse than failing: a misspelled ``--user`` would scope
+    memory to the wrong person and nobody would be told.
+    """
+    unknown = sorted(key for key in flags if key not in allowed)
+    if unknown:
+        spelled = ", ".join(f"--{key.replace('_', '-')}" for key in unknown)
+        raise usage_error(
+            f"Unknown flag {spelled} for this command.",
+            "Run `memorysync help <command>` to see what it accepts.",
+        )
+
+
+def _fail(*, command: str, error: CliError, agent_mode: bool, started: float, settings: dict | None = None) -> int:
+    duration_ms = int((time.monotonic() - started) * 1000)
+    if agent_mode:
+        write(
+            json.dumps(
+                error_envelope(
+                    command=command,
+                    error=error,
+                    duration_ms=duration_ms,
+                    scope=_scope_of(settings) if settings else None,
+                ),
+                indent=2,
+            )
+        )
+    else:
+        print(style.red(f"error: {error.message}"), file=sys.stderr)
+        if error.hint:
+            print(style.dim(f"  {error.hint}"), file=sys.stderr)
+    return error.exit_code
+
+
+def dispatch(argv: list[str]) -> int:
+    """Run one invocation and return its exit code.
+
+    Returns rather than exits so tests can assert on codes without spawning a
+    process or trapping SystemExit.
+    """
+    started = time.monotonic()
+
+    try:
+        positionals, flags = parse_args(argv)
+    except CliError as error:
+        # Agent mode cannot be read from flags that failed to parse, so fall back
+        # to scanning raw argv. An agent asked for JSON and should get JSON even
+        # when its own command line was wrong.
+        agent_mode = "--json" in argv or "--agent" in argv
+        return _fail(command="memorysync", error=error, agent_mode=agent_mode, started=started)
+
+    agent_mode = bool(flags.get("json") or flags.get("agent"))
+    if flags.get("color") is False or agent_mode:
+        set_colour_enabled(False)
+
+    if flags.get("version") and not positionals:
+        write(tooling.VERSION)
+        return Exit.OK
+
+    command_name: str | None = positionals[0] if positionals else None
+    rest = positionals[1:]
+
+    if command_name is None:
+        command_name, rest = "help", []
+    elif flags.get("help"):
+        rest = [command_name]
+        command_name = "help"
+
+    known = registry.commands()
+    if command_name not in known:
+        hint = suggest(command_name, list(known))
+        error = usage_error(
+            f'Unknown command "{command_name}".',
+            f"Did you mean `{hint}`?" if hint else "Run `memorysync help` for the list.",
+        )
+        return _fail(command=command_name, error=error, agent_mode=agent_mode, started=started)
+
+    spec = known[command_name]
+    fmt = _resolve_format(flags, agent_mode)
+    settings = _resolve_settings(flags)
+
+    try:
+        if fmt not in registry.formats():
+            raise usage_error(
+                f'Unknown output format "{fmt}".',
+                f"One of: {', '.join(registry.formats())}.",
+            )
+
+        sub = rest[0] if rest and rest[0] in registry.subcommands(command_name) else None
+        _reject_unknown_flags(flags, _allowed_flags(command_name, sub))
+
+        api_key = flags.get("api_key") or read_key(settings["profile_name"])
+        if spec.get("requires_auth") and not api_key:
+            raise auth_error("No API key found.")
+
+        # Built even for commands that do not require auth, because `init` and
+        # `doctor` both want to probe with a key when one happens to exist.
+        api = (
+            ApiClient(
+                base_url=settings["base_url"],
+                api_key=api_key,
+                user=settings.get("user"),
+                project=settings.get("project"),
+                timeout=settings["timeout"],
+                verbose=bool(flags.get("verbose")),
+            )
+            if api_key
+            else None
+        )
+
+        ctx = {
+            "positionals": rest,
+            "flags": flags,
+            "settings": settings,
+            "api": api,
+            "api_key": api_key,
+            "format": fmt,
+            "agent_mode": agent_mode,
+        }
+
+        handler = _HANDLERS.get(command_name) or _not_implemented(command_name)
+        result = handler(ctx)
+        duration_ms = int((time.monotonic() - started) * 1000)
+
+        # `help` is a discovery contract, not a data result, so its JSON is the
+        # tree itself rather than an envelope around it. An agent bootstrapping
+        # from `help --json` should not have to reach into `.data[0]` for the
+        # command list.
+        if command_name == "help" and (agent_mode or fmt == "json"):
+            write(json.dumps(result["data"], indent=2))
+            return Exit.OK
+
+        if agent_mode:
+            write(
+                json.dumps(
+                    success_envelope(
+                        command=command_name,
+                        data=result["data"],
+                        duration_ms=duration_ms,
+                        scope=_scope_of(settings),
+                    ),
+                    indent=2,
+                )
+            )
+            return result.get("exit_code", Exit.OK)
+
+        # `completion` and `mcp` emit text that must not be decorated or reshaped.
+        if result.get("raw") and fmt not in {"json", "yaml"}:
+            text = result["text"]()
+            if text:
+                write(text)
+            return result.get("exit_code", Exit.OK)
+
+        emit(fmt=fmt, data=result["data"], text=result["text"])
+        return result.get("exit_code", Exit.OK)
+
+    except CliError as error:
+        return _fail(
+            command=command_name,
+            error=error,
+            agent_mode=agent_mode,
+            started=started,
+            settings=settings,
+        )
+    except Exception as error:  # noqa: BLE001 - last resort, still needs an envelope
+        wrapped = CliError(str(error) or error.__class__.__name__, exit_code=Exit.FAILURE)
+        return _fail(
+            command=command_name,
+            error=wrapped,
+            agent_mode=agent_mode,
+            started=started,
+            settings=settings,
+        )
+
+
+def run(argv: list[str] | None = None) -> None:
+    """Console-script entry point."""
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        raise SystemExit(dispatch(args))
+    except KeyboardInterrupt:
+        print(style.dim("\ninterrupted"), file=sys.stderr)
+        raise SystemExit(Exit.INTERRUPTED)
+    except BrokenPipeError:
+        # `memorysync list | head` closes the pipe early. Not a failure.
+        try:
+            sys.stdout.close()
+        finally:
+            raise SystemExit(Exit.OK)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    run()

memorysync_cli/output.py

@@ -0,0 +1,311 @@
+"""Rendering: colour, tables, YAML, and the agent envelope.
+
+Mirrors ``sdk/cli/src/output.mjs`` exactly. Commands never print; they return a
+result and this module decides how it appears, which is what lets all five formats
+work for all 21 commands. Mem0 supports a different format set per command, so a
+script that works for one of theirs can fail for another.
+
+Two JSON paths, and they are not the same thing:
+
+  ``--output json``   the raw data, exactly as the command produced it
+  ``--json``/--agent  the data wrapped in an envelope, for a tool loop
+
+Conflating them was the first parity bug in this port: enveloping ``--output
+json`` would have broken any pipeline doing ``| jq '.[0]'`` against the Node CLI's
+output. ``quiet`` likewise prints nothing at all - not ids - because its job is to
+leave only the exit code.
+
+``data`` is always an array in the envelope, whatever the command. Mem0's own docs
+note their ``search`` returns a bare array while ``list`` returns an envelope, and
+agents trip over the difference.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from typing import Any, Callable, Iterable, Sequence
+
+_FORCE_COLOR = "MEMORYSYNC_FORCE_COLOR"
+_SEXAGESIMAL = re.compile(r"^\d+(:\d+)+$")
+
+
+def _colour_default() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get(_FORCE_COLOR):
+        return True
+    return bool(getattr(sys.stdout, "isatty", lambda: False)())
+
+
+class Style:
+    """ANSI helpers that degrade to plain text when colour is off."""
+
+    def __init__(self) -> None:
+        self.enabled = _colour_default()
+
+    def set_enabled(self, enabled: bool) -> None:
+        self.enabled = enabled
+
+    def _wrap(self, code: str, text: str) -> str:
+        return text if not self.enabled else f"\033[{code}m{text}\033[0m"
+
+    def dim(self, text: str) -> str:
+        return self._wrap("2", text)
+
+    def bold(self, text: str) -> str:
+        return self._wrap("1", text)
+
+    def red(self, text: str) -> str:
+        return self._wrap("31", text)
+
+    def green(self, text: str) -> str:
+        return self._wrap("32", text)
+
+    def yellow(self, text: str) -> str:
+        return self._wrap("33", text)
+
+    def cyan(self, text: str) -> str:
+        return self._wrap("36", text)
+
+
+style = Style()
+
+
+def set_colour_enabled(enabled: bool) -> None:
+    style.set_enabled(enabled)
+
+
+# ---------------------------------------------------------------------------
+# Tables
+# ---------------------------------------------------------------------------
+
+
+def _display_width(text: str) -> int:
+    """Length ignoring ANSI escapes, so coloured cells still align."""
+    out, index = 0, 0
+    while index < len(text):
+        if text[index] == "\033":
+            end = text.find("m", index)
+            if end == -1:
+                break
+            index = end + 1
+            continue
+        out += 1
+        index += 1
+    return out
+
+
+def _truncate(text: str, width: int) -> str:
+    if _display_width(text) <= width:
+        return text
+    if width <= 1:
+        return text[:width]
+    return text[: width - 1] + "\u2026"
+
+
+def render_table(
+    headers: Sequence[str],
+    rows: Iterable[Sequence[Any]],
+    max_widths: Sequence[int] | None = None,
+) -> str:
+    """A fixed-width table.
+
+    Column caps are applied before widths are measured, so one 4,000 character
+    memory body cannot push every other column off the terminal.
+    """
+    caps = list(max_widths or [])
+    materialised = [
+        [
+            _truncate("" if cell is None else str(cell), caps[i])
+            if i < len(caps) and caps[i]
+            else ("" if cell is None else str(cell))
+            for i, cell in enumerate(row)
+        ]
+        for row in rows
+    ]
+
+    if not materialised:
+        return style.dim("(no rows)")
+
+    widths = [
+        max(_display_width(headers[i]), *(_display_width(row[i]) for row in materialised))
+        for i in range(len(headers))
+    ]
+
+    def line(cells: Sequence[str], dim: bool) -> str:
+        parts = []
+        for index, cell in enumerate(cells):
+            padding = " " * max(0, widths[index] - _display_width(cell))
+            parts.append(cell + padding)
+        joined = "  ".join(parts).rstrip()
+        return style.dim(joined) if dim else joined
+
+    return "\n".join([line(list(headers), True), *(line(row, False) for row in materialised)])
+
+
+# ---------------------------------------------------------------------------
+# YAML
+# ---------------------------------------------------------------------------
+
+_YAML_NEEDS_QUOTING_PREFIX = tuple(">|*&!%@`\"'")
+
+
+def _yaml_scalar(value: Any) -> str:
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+
+    text = str(value)
+    lowered = text.lower()
+    ambiguous = (
+        text == ""
+        or text[:1].isspace()
+        or text.startswith(_YAML_NEEDS_QUOTING_PREFIX)
+        or ": " in text
+        or "\n" in text
+        or "#" in text
+        # YAML 1.1 booleans, not just 1.2's. `yes`, `no`, `on` and `off` are
+        # booleans to a 1.1 parser, and PyYAML's safe_load still is one, so a
+        # memory whose text is "yes" would come back as True. The Node CLI carries
+        # the same list; they are fixed together so `-o yaml` cannot differ.
+        or lowered.startswith(("true", "false", "yes", "no", "on", "off", "null", "~"))
+        or text[:1].isdigit()
+        or (text.startswith("-") and len(text) > 1 and text[1].isdigit())
+        # Sexagesimal: `12:30` is a number to a 1.1 parser.
+        or _SEXAGESIMAL.match(text) is not None
+    )
+    return json.dumps(text) if ambiguous else text
+
+
+def to_yaml(value: Any, indent: int = 0) -> str:
+    """A small YAML writer for the shapes this CLI emits.
+
+    Only scalars, lists and dicts appear in API responses, so a YAML library would
+    be a dependency bought for nothing.
+    """
+    pad = "  " * indent
+
+    if isinstance(value, dict):
+        if not value:
+            return f"{pad}{{}}"
+        lines = []
+        for key, item in value.items():
+            if isinstance(item, (dict, list)) and item:
+                lines.append(f"{pad}{key}:")
+                lines.append(to_yaml(item, indent + 1))
+            else:
+                lines.append(f"{pad}{key}: {_yaml_scalar(item)}")
+        return "\n".join(lines)
+
+    if isinstance(value, list):
+        if not value:
+            return f"{pad}[]"
+        lines = []
+        for item in value:
+            if isinstance(item, (dict, list)) and item:
+                nested = to_yaml(item, indent + 1)
+                first, _, rest = nested.partition("\n")
+                lines.append(f"{pad}- {first.strip()}")
+                if rest:
+                    lines.append(rest)
+            else:
+                lines.append(f"{pad}- {_yaml_scalar(item)}")
+        return "\n".join(lines)
+
+    return f"{pad}{_yaml_scalar(value)}"
+
+
+# ---------------------------------------------------------------------------
+# The agent envelope
+# ---------------------------------------------------------------------------
+
+
+def success_envelope(
+    *,
+    command: str,
+    data: Any,
+    duration_ms: int,
+    scope: dict | None = None,
+    quota: dict | None = None,
+    request_id: str | None = None,
+) -> dict:
+    """Key order matches the Node CLI's, because the tests compare parsed JSON but
+    humans compare output side by side."""
+    envelope: dict[str, Any] = {
+        "status": "success",
+        "command": command,
+        "duration_ms": duration_ms,
+    }
+    if scope:
+        envelope["scope"] = scope
+    if isinstance(data, list):
+        envelope["count"] = len(data)
+    envelope["data"] = data if isinstance(data, list) else [v for v in [data] if v is not None]
+    if quota:
+        envelope["quota"] = quota
+    if request_id:
+        envelope["request_id"] = request_id
+    return envelope
+
+
+def error_envelope(
+    *,
+    command: str,
+    error: Any,
+    duration_ms: int,
+    scope: dict | None = None,
+) -> dict:
+    envelope: dict[str, Any] = {
+        "status": "error",
+        "command": command,
+        "duration_ms": duration_ms,
+        "error": {
+            "code": getattr(error, "code", None) or "error",
+            "message": getattr(error, "message", None) or str(error),
+            "exit_code": getattr(error, "exit_code", 1),
+        },
+    }
+    hint = getattr(error, "hint", None)
+    if hint:
+        envelope["error"]["hint"] = hint
+    request_id = getattr(error, "request_id", None)
+    if request_id:
+        envelope["request_id"] = request_id
+    if scope:
+        envelope["scope"] = scope
+    envelope["data"] = []
+    return envelope
+
+
+# ---------------------------------------------------------------------------
+# Emission
+# ---------------------------------------------------------------------------
+
+
+def write(text: str) -> None:
+    sys.stdout.write(f"{text}\n")
+
+
+def emit(*, fmt: str, data: Any, text: Callable[[], str]) -> None:
+    """Render one result.
+
+    ``text`` stays lazy so a JSON caller never pays to build a table it discards.
+    """
+    if fmt == "json":
+        write(json.dumps(data, indent=2))
+        return
+    if fmt == "yaml":
+        write(to_yaml(data))
+        return
+    if fmt == "quiet":
+        # Nothing at all. The exit code is the output.
+        return
+    write(text())