memorysync-cli 1.0.2__py3-none-any.whl

memorysync_cli/commands/source.py

@@ -0,0 +1,132 @@
+"""source: inspect and control connectors.
+
+No competitor's CLI touches connectors at all, which is the reason this exists: a
+connector that silently stopped syncing is invisible until someone notices missing
+memory, and the dashboard is a poor place to check it from a deployment script.
+
+Only sync, pause and resume. There is no disconnect: removing a connector purges
+everything derived from it, which is not a thing to make one keystroke away in a
+tool that also runs in CI. That stays in the dashboard.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import Any
+
+from ..errors import not_found_error, usage_error
+from ..output import render_table, style
+
+_ACTIONS = {"sync", "pause", "resume"}
+
+
+def _fetch(api: Any) -> list[dict]:
+    raw = api.request("GET", "/api/v1/integrations")
+    entries = raw if isinstance(raw, list) else (raw or {}).get("integrations") or []
+    return [entry for entry in entries if isinstance(entry, dict)]
+
+
+def _colour_status(value: Any) -> str:
+    text = str(value or "unknown")
+    if text in {"error", "failed", "disconnected"}:
+        return style.red(text)
+    if text in {"syncing", "pending"}:
+        return style.yellow(text)
+    if text in {"connected", "active", "ok"}:
+        return style.green(text)
+    return text
+
+
+def _resolve(api: Any, needle: str) -> dict:
+    """Find a connector by id or by provider name.
+
+    Accepting the provider name matters for usability: nobody remembers
+    `int_9f3a2c`, everybody remembers `github`.
+    """
+    entries = _fetch(api)
+    lowered = needle.lower()
+    for entry in entries:
+        if str(entry.get("id", "")).lower() == lowered:
+            return entry
+    matches = [e for e in entries if str(e.get("provider", "")).lower() == lowered]
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        raise usage_error(
+            f'Several connectors match "{needle}".',
+            "Use the id instead: " + ", ".join(str(m.get("id")) for m in matches),
+        )
+    raise not_found_error(
+        f'No connector matching "{needle}".',
+        "Run `memorysync source list` to see what is connected.",
+    )
+
+
+def source(ctx: dict) -> dict:
+    positionals, flags, api = ctx["positionals"], ctx["flags"], ctx["api"]
+    sub = positionals[0] if positionals else "list"
+    argument = positionals[1] if len(positionals) > 1 else None
+
+    if sub == "list":
+        entries = _fetch(api)
+        rows = [
+            {
+                "id": entry.get("id"),
+                "provider": entry.get("provider"),
+                "status": entry.get("status"),
+                "last_sync": entry.get("last_sync_at") or entry.get("last_synced_at"),
+            }
+            for entry in entries
+        ]
+
+        def render() -> str:
+            if not rows:
+                return style.dim("No connectors are configured.")
+            return render_table(
+                ["id", "provider", "status", "last sync"],
+                [
+                    [r["id"], r["provider"], _colour_status(r["status"]), (r["last_sync"] or "-")[:19]]
+                    for r in rows
+                ],
+            )
+
+        return {"data": rows, "text": render}
+
+    if sub == "status":
+        if not argument:
+            raise usage_error("Which source?", "memorysync source status github")
+        match = _resolve(api, argument)
+        return {
+            "data": match,
+            "text": lambda: "\n".join(
+                f"{style.dim(str(key).ljust(22))} "
+                f"{_colour_status(value) if key == 'status' else ('-' if value is None else value)}"
+                for key, value in match.items()
+            ),
+        }
+
+    if sub in _ACTIONS:
+        if not argument:
+            raise usage_error("Which source?", f"memorysync source {sub} github")
+        match = _resolve(api, argument)
+
+        if flags.get("dry_run"):
+            return {
+                "data": {"action": sub, "source": match.get("id"), "applied": False},
+                "text": lambda: style.yellow(
+                    f"Dry run. Would {sub} {match.get('provider') or match.get('id')}."
+                ),
+            }
+
+        identifier = urllib.parse.quote(str(match.get("id")), safe="")
+        result = api.request("POST", f"/api/v1/integrations/{identifier}/{sub}", body={})
+        label = "Sync triggered for" if sub == "sync" else f"{sub.capitalize()}d"
+        return {
+            "data": {"action": sub, "source": match.get("id"), "result": result},
+            "text": lambda: f"{style.green(label)} {match.get('provider') or match.get('id')}",
+        }
+
+    raise usage_error(
+        f'Unknown subcommand "{sub}".',
+        "Try list, status, sync, pause or resume.",
+    )

memorysync_cli/commands/tooling.py

@@ -0,0 +1,238 @@
+"""help, version, completion.
+
+``help --json`` is the agent-discovery contract, and for a closed-source tool it
+is the documentation of record: nobody can read our source to find out what a
+command really takes, so a stale answer here is worse than none.
+
+It is emitted straight from the shared registry, so it cannot describe a flag the
+parser rejects, and it is byte-identical to the Node CLI's because both read the
+same generated tree.
+
+Worth stating plainly why that matters. Mem0 is the only competitor shipping two
+CLIs and documents them as identical. Their Python CLI answers ``help --json``
+with twelve commands and full options; their Node CLI answers with a name, a
+version and a description, so an agent asking the Node one what it can do learns
+nothing. Sharing the declaration is what stops that happening here.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .. import registry
+from .._version import __version__
+from ..errors import CliError, Exit, usage_error
+from ..output import style
+
+VERSION = __version__
+
+
+def version(ctx: dict) -> dict:
+    # An object, not a list. The envelope wraps non-lists into `data: [...]`
+    # itself, so returning a list here would produce `[[{...}]]` in agent mode.
+    return {"data": {"version": VERSION}, "text": lambda: VERSION}
+
+
+def _flag_line(flag: dict) -> str:
+    """One flag row, padded exactly as the Node CLI pads it.
+
+    Four leading spaces when there is no short form, so the long names line up
+    under each other rather than under the short ones. The 28-column label field is
+    copied deliberately: `--help` output is compared between the two CLIs
+    byte-for-byte, so the padding is part of the contract.
+    """
+    label = f"{flag['short']}, {flag['name']}" if flag.get("short") else f"    {flag['name']}"
+    value = f" <{flag['value']}>" if flag.get("value") else ""
+    return f"  {(label + value).ljust(28)}{flag['description']}"
+
+
+def _wrap(text: str, width: int) -> str:
+    """Greedy wrap, matching the Node implementation's boundary behaviour.
+
+    Note the condition tests the candidate *including* the space before deciding,
+    which is what makes the two produce identical break points.
+    """
+    words = text.split()
+    lines: list[str] = []
+    current = ""
+    for word in words:
+        if len(f"{current} {word}".strip()) > width:
+            lines.append(current.strip())
+            current = word
+        else:
+            current += f" {word}"
+    if current.strip():
+        lines.append(current.strip())
+    return "\n".join(lines)
+
+
+def _command_help(name: str) -> str:
+    spec = registry.commands().get(name)
+    if spec is None:
+        raise usage_error(f'Unknown command "{name}".', "Run `memorysync help` for the list.")
+
+    lines = [style.bold(f"memorysync {spec['name']}") + style.dim(f" - {spec['summary']}"), ""]
+
+    if spec.get("description"):
+        lines += [_wrap(spec["description"], 78), ""]
+    if spec.get("usage"):
+        lines += [style.bold("Usage"), f"  {spec['usage']}", ""]
+
+    subcommands = spec.get("subcommands") or []
+    if subcommands:
+        lines.append(style.bold("Subcommands"))
+        width = max(len(s["name"]) for s in subcommands)
+        lines += [f"  {s['name'].ljust(width + 2)}{s['summary']}" for s in subcommands]
+        lines.append("")
+
+    if spec.get("flags"):
+        lines.append(style.bold("Flags"))
+        lines += [_flag_line(flag) for flag in spec["flags"]]
+        lines.append("")
+
+    if spec.get("examples"):
+        lines.append(style.bold("Examples"))
+        lines += [f"  {style.dim(example)}" for example in spec["examples"]]
+        lines.append("")
+
+    if spec.get("consumes_quota"):
+        lines.append(
+            style.dim(f"Consumes plan quota: {spec['consumes_quota']}. See `memorysync quota`.")
+        )
+
+    return "\n".join(lines).rstrip()
+
+
+def _overview() -> str:
+    tree = registry.command_tree()
+    entries = tree["commands"]
+    width = max(len(entry["name"]) for entry in entries)
+
+    lines = [
+        style.bold("memorysync") + style.dim(" - agent memory from your terminal"),
+        "",
+        style.bold("Usage"),
+        "  memorysync [global flags] <command> [args] [flags]",
+        "",
+        style.bold("Commands"),
+    ]
+    lines += [f"  {entry['name'].ljust(width + 2)}{entry['summary']}" for entry in entries]
+    lines += ["", style.bold("Global flags")]
+    lines += [_flag_line(flag) for flag in tree["global_flags"]]
+    lines += [
+        "",
+        style.dim(f"Output formats: {', '.join(tree['output_formats'])}"),
+        style.dim("Agent mode: memorysync --json <command>   (one JSON envelope, no colour)"),
+        style.dim("Full tree as JSON: memorysync help --json"),
+        style.dim("Docs: https://docs.memorysync.io/cli"),
+    ]
+    return "\n".join(lines)
+
+
+def help_command(ctx: dict) -> dict:
+    """`help`, `help <command>`, and `help --json`.
+
+    The JSON form ignores a command argument and always returns the whole tree: an
+    agent asking for machine-readable help wants the full surface, and a partial
+    tree would be indistinguishable from a CLI that only has one command.
+    """
+    positionals = ctx.get("positionals") or []
+
+    if positionals:
+        target = positionals[0]
+        if target not in registry.commands():
+            raise usage_error(f'Unknown command "{target}".')
+        # The command's own entry from the tree, so `help add --json` returns the
+        # same object that appears inside `help --json`.
+        detail = registry.commands()[target]
+        return {"data": detail, "text": lambda: _command_help(target)}
+
+    # The tree itself, not wrapped. The dispatcher prints this raw for `--json`,
+    # so an agent bootstrapping from it reads `.commands` rather than `.data[0]`.
+    return {"data": registry.command_tree(), "text": _overview}
+
+
+
+def completion(ctx: dict) -> dict:
+    """Emit a completion script for one shell.
+
+    Generated from the registry for the same reason as the help text: a static
+    script would quietly start offering commands that no longer exist. zepctl gets
+    completions free from Cobra; ours are built here, from the declaration the
+    dispatcher reads.
+    """
+    from ..completions import SCRIPTS
+
+    positionals = ctx.get("positionals") or []
+    shell = positionals[0] if positionals else None
+
+    if not shell or shell not in SCRIPTS:
+        raise usage_error(
+            f'No completion script for "{shell}".' if shell else "Which shell?",
+            "Supported: bash, zsh, fish, powershell.",
+        )
+
+    script = SCRIPTS[shell]()
+    # `raw` keeps the dispatcher from decorating a shell script that is about to be
+    # redirected into a completion directory.
+    return {"data": {"shell": shell, "script": script}, "raw": True, "text": lambda: script}
+
+
+def mcp(ctx: dict) -> dict:
+    """Configure MCP clients, by delegating to the installer.
+
+    Deliberately a delegation rather than a reimplementation. The MCP config
+    formats differ per client and change as clients ship new versions; keeping that
+    knowledge in one published package means the two CLIs cannot disagree about
+    where Claude Desktop's config lives, and a fix reaches both without either
+    being republished.
+
+    ``npx`` is required here, which is the one place this CLI is not pure Python.
+    Said plainly in the error rather than failing obscurely, because a Python user
+    has no reason to expect a Node tool.
+    """
+    import shutil
+    import subprocess
+
+    positionals = ctx.get("positionals") or []
+    sub = positionals[0] if positionals else "install"
+
+    extra = {"install": [], "list": ["--list"], "remove": ["--remove"]}
+    if sub not in extra:
+        raise usage_error(f'Unknown subcommand "{sub}".', "Try install, list or remove.")
+
+    if shutil.which("npx") is None:
+        raise CliError(
+            "`memorysync mcp` needs npx, which is part of Node.js.",
+            exit_code=Exit.USAGE,
+            code="npx_missing",
+            hint=(
+                "Install Node.js 18 or newer, or configure your MCP client by hand: "
+                "https://docs.memorysync.io/mcp/install"
+            ),
+        )
+
+    args = ["npx", "-y", "memorysync-mcp-install", *extra[sub]]
+    if ctx.get("flags", {}).get("dry_run") and sub == "install":
+        args.append("--dry-run")
+
+    capture = ctx.get("format") == "json" or ctx.get("agent_mode")
+    completed = subprocess.run(
+        args,
+        capture_output=bool(capture),
+        text=True,
+    )
+
+    payload = {
+        "subcommand": sub,
+        "exit_code": completed.returncode,
+        **({"output": (completed.stdout or "").strip()} if capture else {}),
+    }
+
+    return {
+        "data": payload,
+        "raw": True,
+        "text": lambda: (completed.stdout or "").strip() if capture else "",
+        "exit_code": completed.returncode,
+    }

memorysync_cli/completions.py

@@ -0,0 +1,150 @@
+"""Shell completion scripts, generated from the shared registry.
+
+Ported from ``sdk/cli/src/commands/tooling.mjs`` and asserted byte-for-byte against
+it. A shell function that differed between the two CLIs would mean tab completion
+behaves differently depending on which one a developer happened to install, which
+is precisely the surprise this whole arrangement exists to prevent.
+
+Kept in its own module because the templates are long enough to bury the rest of
+the tooling commands, and because the parity test points straight here when a
+template drifts.
+"""
+
+from __future__ import annotations
+
+from . import registry
+
+
+def _commands() -> dict[str, dict]:
+    return registry.commands()
+
+
+def _with_subcommands() -> list[tuple[str, list[str]]]:
+    out = []
+    for name, spec in _commands().items():
+        subs = [s["name"] for s in spec.get("subcommands", [])]
+        if subs:
+            out.append((name, subs))
+    return out
+
+
+def _bash_subcommand_case() -> str:
+    entries = _with_subcommands()
+    if not entries:
+        return ""
+    cases = "\n".join(
+        f'      {name}) COMPREPLY=( $(compgen -W "{" ".join(subs)}" -- "$cur") ) ;;'
+        for name, subs in entries
+    )
+    return '  case "${COMP_WORDS[1]}" in\n' + cases + "\n  esac"
+
+
+def bash() -> str:
+    names = " ".join(_commands())
+    globals_ = " ".join(flag["name"] for flag in registry.global_flags())
+    formats = " ".join(registry.formats())
+    return f"""# memorysync bash completion
+# Install: memorysync completion bash > /etc/bash_completion.d/memorysync
+_memorysync_complete() {{
+  local cur prev
+  cur="${{COMP_WORDS[COMP_CWORD]}}"
+  prev="${{COMP_WORDS[COMP_CWORD-1]}}"
+  local commands="{names}"
+  local globals="{globals_}"
+
+  if [[ "$prev" == "-o" || "$prev" == "--output" ]]; then
+    COMPREPLY=( $(compgen -W "{formats}" -- "$cur") )
+    return
+  fi
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=( $(compgen -W "$globals" -- "$cur") )
+    return
+  fi
+  if [[ $COMP_CWORD -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+    return
+  fi
+{_bash_subcommand_case()}
+}}
+complete -F _memorysync_complete memorysync msync
+"""
+
+
+def zsh() -> str:
+    described = "\n".join(
+        f"    '{spec['name']}:{spec['summary'].replace(chr(39), chr(39) + chr(92) + chr(39) + chr(39))}'"
+        for spec in _commands().values()
+    )
+    cases = "\n".join(
+        f"    {name}) _values 'subcommand' " + " ".join(f"'{s}'" for s in subs) + " ;;"
+        for name, subs in _with_subcommands()
+    )
+    formats = " ".join(registry.formats())
+    return f"""#compdef memorysync msync
+# Install: memorysync completion zsh > "${{fpath[1]}}/_memorysync"
+_memorysync() {{
+  local -a commands
+  commands=(
+{described}
+  )
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+  case "${{words[2]}}" in
+{cases}
+  esac
+  _arguments '-o[output format]:format:({formats})' '--json[agent mode]' '--user[end user]:id:'
+}}
+_memorysync "$@"
+"""
+
+
+def fish() -> str:
+    def escape(text: str) -> str:
+        return text.replace("'", "\\'")
+
+    top = "\n".join(
+        f"complete -c memorysync -n __fish_use_subcommand -a {spec['name']} "
+        f"-d '{escape(spec['summary'])}'"
+        for spec in _commands().values()
+    )
+    nested = "\n".join(
+        f"complete -c memorysync -n '__fish_seen_subcommand_from {name}' -a {sub['name']} "
+        f"-d '{escape(sub['summary'])}'"
+        for name, spec in _commands().items()
+        for sub in spec.get("subcommands", [])
+    )
+    formats = " ".join(registry.formats())
+    return f"""# memorysync fish completion
+# Install: memorysync completion fish > ~/.config/fish/completions/memorysync.fish
+{top}
+{nested}
+complete -c memorysync -s o -l output -x -a '{formats}' -d 'Output format'
+complete -c memorysync -l json -d 'Agent mode'
+complete -c memorysync -s u -l user -x -d 'End user id'
+"""
+
+
+def powershell() -> str:
+    names = ", ".join(f"'{name}'" for name in _commands())
+    formats = ", ".join(f"'{fmt}'" for fmt in registry.formats())
+    return f"""# memorysync PowerShell completion
+# Install: add the following to your profile, or dot-source a file containing it.
+Register-ArgumentCompleter -Native -CommandName memorysync, msync -ScriptBlock {{
+    param($wordToComplete, $commandAst, $cursorPosition)
+    $commands = @({names})
+    $formats = @({formats})
+    $tokens = $commandAst.CommandElements | ForEach-Object {{ $_.ToString() }}
+
+    if ($tokens.Count -ge 2 -and ($tokens[-1] -eq '-o' -or $tokens[-1] -eq '--output')) {{
+        return $formats | Where-Object {{ $_ -like "$wordToComplete*" }} |
+            ForEach-Object {{ [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }}
+    }}
+    $commands | Where-Object {{ $_ -like "$wordToComplete*" }} |
+        ForEach-Object {{ [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }}
+}}
+"""
+
+
+SCRIPTS = {"bash": bash, "zsh": zsh, "fish": fish, "powershell": powershell}

memorysync_cli/config.py

@@ -0,0 +1,147 @@
+"""Profiles and settings, resolved in one documented order.
+
+Precedence, highest first: an explicit flag, then the environment, then the config
+file, then a built-in default. That order is what people expect and, more
+importantly, it is what the Node CLI does, so a script that sets
+``MEMORYSYNC_USER`` behaves the same whichever CLI is installed.
+
+The config file never holds a credential. It holds a profile name, a default end
+user, a project and a base URL - the things that are useful to read, commit to a
+dotfiles repo, or paste into a bug report. Keys live in ``credentials.py``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+CONFIG_VERSION = 1
+DEFAULT_BASE_URL = "https://api.memorysync.io"
+DEFAULT_TIMEOUT_MS = 60000
+
+
+def config_dir() -> Path:
+    """Where settings live.
+
+    ``MEMORYSYNC_CONFIG_DIR`` is honoured first so tests and CI can point at a
+    scratch directory instead of a developer's real profile.
+    """
+    override = os.environ.get("MEMORYSYNC_CONFIG_DIR")
+    if override:
+        return Path(override)
+
+    if os.name == "nt":
+        base = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+        return Path(base) / "memorysync"
+
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg) / "memorysync"
+    return Path.home() / ".config" / "memorysync"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def _empty() -> dict[str, Any]:
+    return {"version": CONFIG_VERSION, "profiles": {}}
+
+
+def load() -> dict[str, Any]:
+    """Read the config file, tolerating absence and corruption.
+
+    A damaged file returns defaults rather than raising. Refusing to run because a
+    JSON file has a stray comma would block every command, including the ``config``
+    and ``init`` commands that could repair it.
+    """
+    path = config_path()
+    try:
+        with path.open(encoding="utf-8") as handle:
+            parsed = json.load(handle)
+    except (FileNotFoundError, ValueError, OSError):
+        return _empty()
+
+    if not isinstance(parsed, dict):
+        return _empty()
+
+    return {
+        "version": parsed.get("version", CONFIG_VERSION),
+        "profiles": parsed.get("profiles") if isinstance(parsed.get("profiles"), dict) else {},
+    }
+
+
+def save(config: dict[str, Any]) -> Path:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as handle:
+        json.dump(config, handle, indent=2)
+        handle.write("\n")
+    try:
+        # Not a secret, but not world-readable either: it names end users.
+        path.chmod(0o600)
+    except OSError:
+        pass
+    return path
+
+
+def profile(name: str = "default") -> dict[str, Any]:
+    return load()["profiles"].get(name, {})
+
+
+def resolve(flags: dict[str, Any]) -> dict[str, Any]:
+    """Settings for this invocation.
+
+    Values are read once here so every command sees the same view, rather than
+    each one reaching for the environment at a different moment.
+    """
+    profile_name = (
+        flags.get("profile") or os.environ.get("MEMORYSYNC_PROFILE") or "default"
+    )
+    stored = profile(profile_name)
+
+    def pick(flag_key: str, env_key: str, stored_key: str, fallback: Any = None) -> Any:
+        value = flags.get(flag_key)
+        if value not in (None, False):
+            return value
+        env_value = os.environ.get(env_key)
+        if env_value:
+            return env_value
+        if stored.get(stored_key) is not None:
+            return stored[stored_key]
+        return fallback
+
+    timeout = pick("timeout", "MEMORYSYNC_TIMEOUT", "timeout", DEFAULT_TIMEOUT_MS)
+    try:
+        timeout = int(timeout)
+    except (TypeError, ValueError):
+        timeout = DEFAULT_TIMEOUT_MS
+
+    return {
+        "profile_name": profile_name,
+        "base_url": str(
+            pick("base_url", "MEMORYSYNC_BASE_URL", "base_url", DEFAULT_BASE_URL)
+        ).rstrip("/"),
+        "user": pick("user", "MEMORYSYNC_USER", "user"),
+        "project": pick("project", "MEMORYSYNC_PROJECT", "project"),
+        "timeout": timeout,
+    }
+
+
+def redacted(config: dict[str, Any] | None = None) -> dict[str, Any]:
+    """The config as it is safe to print.
+
+    Nothing secret is stored here, but this goes through one function anyway so a
+    future field cannot be added and printed by accident.
+    """
+    data = config or load()
+    return {
+        "version": data.get("version", CONFIG_VERSION),
+        "path": str(config_path()),
+        "profiles": {
+            name: {key: value for key, value in entry.items() if key != "api_key"}
+            for name, entry in data.get("profiles", {}).items()
+        },
+    }