xmemcli 0.0.11__tar.gz → 0.0.12__tar.gz

xmemcli-0.0.11/README.md → xmemcli-0.0.12/PKG-INFO

@@ -1,3 +1,11 @@
+Metadata-Version: 2.5
+Name: xmemcli
+Version: 0.0.12
+Summary: Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools.
+Keywords: api,cli,llm,memory,xmemory
+Requires-Python: <4,>=3.12
+Description-Content-Type: text/markdown
+
 # `xmemcli` — xmemory command-line client
 
 Single-command CLI for reading from, writing to, and managing xmemory instances over the HTTP API at `$XMEM_API_URL` (default `https://api.xmemory.ai`), using an API key from the Console UI or `xmemcli auth login`.
@@ -89,7 +97,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.11**.
+Version: **0.0.12**.
 
 
 ---
@@ -153,6 +161,8 @@ A credential that already resolves (via `/whoami`) to the requested address at t
 
 Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking up from `--rc-dir` / CWD, ceiling `$HOME`.
 
+Those three keys are required and must be strings. Anything else in the file is **ignored, not rejected** (since 0.0.12): the rc is the only durable credential store, so a file this CLI cannot load is a CLI that cannot run any command at all — which would make adding a field to the file a breaking change far wider than the feature that added it.
+
 Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin.
 
 ## Identity — `/whoami`
@@ -183,7 +193,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.11` (see `xmemcli version`)
+**Version:** `0.0.12` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
@@ -505,7 +515,9 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, …)
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 
-See also [`ACCOUNTS_AUTH.md`](../ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
+**Compatibility change in 0.0.12:** an `.xmemrc.json` carrying a key this release does not recognise is now **accepted**, and the unknown key ignored; `email`, `api_url`, and `api_key` are still required and still have to be strings. Until 0.0.12 the key set was closed, which made adding a field to the file a breaking change for **every** command rather than for the one that would read it — a CLI that cannot load the rc cannot resolve a credential for anything. Nothing writes an extra key yet; this release exists so that a later one can.
+
+See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 
 ---
 
@@ -594,6 +606,8 @@ These apply **before** any subcommand (`xmemcli help options`).
 
 **Credential resolution:** `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` → *Not logged in — run `xmemcli auth login` first.*
 
+**`.xmemrc.json` shape:** `{email, api_url, api_key}`, all three required and all three strings. Keys beyond those are ignored rather than rejected (see the 0.0.12 note above), so a file written by a newer CLI still loads here.
+
 **`context` is the one exception, and it is a security boundary.** Every other command walks up
 from the current directory for the nearest `.xmemrc.json`, which is deliberate: a person chose
 that directory and ran the command in it. `context` has neither — a session-start hook runs it

xmemcli-0.0.11/PKG-INFO → xmemcli-0.0.12/README.md

@@ -1,11 +1,3 @@
-Metadata-Version: 2.5
-Name: xmemcli
-Version: 0.0.11
-Summary: Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools.
-Keywords: api,cli,llm,memory,xmemory
-Requires-Python: <4,>=3.12
-Description-Content-Type: text/markdown
-
 # `xmemcli` — xmemory command-line client
 
 Single-command CLI for reading from, writing to, and managing xmemory instances over the HTTP API at `$XMEM_API_URL` (default `https://api.xmemory.ai`), using an API key from the Console UI or `xmemcli auth login`.
@@ -97,7 +89,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.11**.
+Version: **0.0.12**.
 
 
 ---
@@ -161,6 +153,8 @@ A credential that already resolves (via `/whoami`) to the requested address at t
 
 Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking up from `--rc-dir` / CWD, ceiling `$HOME`.
 
+Those three keys are required and must be strings. Anything else in the file is **ignored, not rejected** (since 0.0.12): the rc is the only durable credential store, so a file this CLI cannot load is a CLI that cannot run any command at all — which would make adding a field to the file a breaking change far wider than the feature that added it.
+
 Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin.
 
 ## Identity — `/whoami`
@@ -191,7 +185,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.11` (see `xmemcli version`)
+**Version:** `0.0.12` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
@@ -513,7 +507,9 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, …)
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 
-See also [`ACCOUNTS_AUTH.md`](../ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
+**Compatibility change in 0.0.12:** an `.xmemrc.json` carrying a key this release does not recognise is now **accepted**, and the unknown key ignored; `email`, `api_url`, and `api_key` are still required and still have to be strings. Until 0.0.12 the key set was closed, which made adding a field to the file a breaking change for **every** command rather than for the one that would read it — a CLI that cannot load the rc cannot resolve a credential for anything. Nothing writes an extra key yet; this release exists so that a later one can.
+
+See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 
 ---
 
@@ -602,6 +598,8 @@ These apply **before** any subcommand (`xmemcli help options`).
 
 **Credential resolution:** `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` → *Not logged in — run `xmemcli auth login` first.*
 
+**`.xmemrc.json` shape:** `{email, api_url, api_key}`, all three required and all three strings. Keys beyond those are ignored rather than rejected (see the 0.0.12 note above), so a file written by a newer CLI still loads here.
+
 **`context` is the one exception, and it is a security boundary.** Every other command walks up
 from the current directory for the nearest `.xmemrc.json`, which is deliberate: a person chose
 that directory and ran the command in it. `context` has neither — a session-start hook runs it

{xmemcli-0.0.11 → xmemcli-0.0.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "0.0.11"
+version = "0.0.12"
 description = "Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools."
 readme = "README.md"
 requires-python = ">=3.12,<4"

{xmemcli-0.0.11 → xmemcli-0.0.12}/uv.lock

@@ -4,5 +4,5 @@ requires-python = ">=3.12, <4"
 
 [[package]]
 name = "xmemcli"
-version = "0.0.11"
+version = "0.0.12"
 source = { editable = "." }

{xmemcli-0.0.11 → xmemcli-0.0.12}/xmemcli/__init__.py

@@ -1,3 +1,3 @@
 """Standalone xmemcli package (``xmemcli`` console script)."""
 
-__version__ = "0.0.11"
+__version__ = "0.0.12"

{xmemcli-0.0.11 → xmemcli-0.0.12}/xmemcli/_output.py

@@ -84,9 +84,12 @@ class OutputKind(StrEnum):
     #: payload: ``write_id``; the caller must poll.
     WRITE_ASYNC = "write_async"
 
-    #: Terminal result of an ``async_write_status`` poll. Curated payload:
-    #: ``write_id`` + ``write_status`` in {``completed``, ``failed``,
-    #: ``not_found``} (+ ``error_detail`` / ``timed_out`` when applicable).
+    #: Result of an ``async_write_status`` poll. Curated payload: ``write_id`` + ``write_status``
+    #: — any ``WriteQueueStatus`` value, not only the terminal ones, plus the CLI's own
+    #: ``"error"`` / ``"unknown"`` fallbacks — whichever of ``submitted_at`` / ``started_at`` /
+    #: ``completed_at`` is set, ``restart_count`` once non-zero (``--verbose`` keeps a zero count and
+    #: drops only the null an unknown ``write_id`` reports), and ``error_detail`` / ``error``
+    #: / ``http_status`` / ``timed_out`` when applicable.
     WRITE_STATUS = "write_status"
 
     #: Read in ``mode=single-answer``. Curated payload: ``answer`` (falls

{xmemcli-0.0.11 → xmemcli-0.0.12}/xmemcli/_pretty.py

@@ -78,7 +78,7 @@ def _render_write_async(payload: Any, stream: IO[str]) -> None:
 
 
 def _render_write_status(payload: Any, stream: IO[str]) -> None:
-    """Terminal poll result — short status line, no body."""
+    """Poll result — short status line, no body; the timing fields stay JSON-only."""
     if not isinstance(payload, dict):
         _default_handler(payload, stream)
         return

{xmemcli-0.0.11 → xmemcli-0.0.12}/xmemcli/_rc.py

@@ -5,9 +5,11 @@ The CLI resolves its API key and API origin from a **project-local**
 (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``.
+The file is stdlib JSON, one identity per file: ``{email, api_url, api_key}``.
+Those three are required and must be strings; a key this release does not know is
+ignored rather than rejected, so a later release can record something new in the
+file without every older CLI refusing to run. 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
@@ -26,9 +28,10 @@ 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.
+# The keys an `.xmemrc.json` must contain. Required, not exhaustive: anything else in the file is ignored.
+# The set was closed until 0.0.12, on the grounds that a typo'd or extended file should fail loudly.
+# It made adding a field a breaking change for every command rather than for the one that would read it,
+# because a CLI that cannot load the rc cannot resolve a credential for anything.
 _RC_KEYS = ("email", "api_url", "api_key")
 
 
@@ -90,27 +93,22 @@ def find_rc(start_dir: Path) -> Path | None:
 
 
 def load_rc(path: Path) -> RcRecord:
-    """Parse and validate an ``.xmemrc.json``; raise ``RcError`` if malformed."""
+    """Parse and validate an ``.xmemrc.json``; raise ``RcError`` if malformed.
+
+    "Required keys present", not "exactly these keys": an unrecognised key is ignored
+    whatever its type. Type-checking a field nothing here reads is how a later release's
+    richer value becomes this release's hard failure — having no opinion about it is the
+    whole point of ignoring it.
+    """
     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})")
+    missing = sorted(set(_RC_KEYS) - set(raw.keys()))
+    if missing:
+        raise RcError(f"{path}: must contain {list(_RC_KEYS)} (missing {missing})")
     for key in _RC_KEYS:
         if not isinstance(raw[key], str):
             raise RcError(f"{path}: '{key}' must be a string")

{xmemcli-0.0.11 → xmemcli-0.0.12}/xmemcli/_version.py

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

{xmemcli-0.0.11 → xmemcli-0.0.12}/xmemcli/cli.py

@@ -30,13 +30,16 @@ Curated output
 The CLI does NOT echo the raw API payload. Every subcommand reduces the
 server response to the fields the user actually asked for (see the
 ``_curate_*`` helpers): a read returns the answer / rows, a write returns
-its ``write_id``, a status poll returns ``write_id`` + ``write_status``.
+its ``write_id``, a status poll returns ``write_id`` + ``write_status``
+plus whichever timing fields the server set (and the restart count once
+it is non-zero).
 Server internals — ``sql``, ``diff_plan``, the raw ``cleaned_objects``
 tree — are never emitted, in either output mode. ``pending_suggestions``
 (a count of schema-evolution proposals waiting for review) is kept on
 read responses so agents know when to run ``schema suggestions review``.
 ``--verbose`` adds *extra* (still non-internal) context: ``trace_id`` and
-``console_url``, when the server provided them.
+``console_url``, when the server provided them, and keeps a zero
+``restart_count`` a status poll would otherwise curate away.
 
 Sync vs async writes
 --------------------
@@ -749,10 +752,26 @@ def _curate_write_status(item: dict[str, Any], verbose: bool) -> dict[str, Any]:
         "write_status": item.get("write_status", "unknown"),
     }
     # Carry the failure / bookkeeping fields only when they say something.
-    for key in ("error_detail", "completed_at", "error", "http_status", "timed_out"):
+    for key in (
+        "error_detail",
+        "submitted_at",
+        "started_at",
+        "completed_at",
+        "error",
+        "http_status",
+        "timed_out",
+    ):
         value = item.get(key)
         if value is not None:
             curated[key] = value
+    # Never-restarted is the norm, so a zero count is noise on the default output; show it there only when
+    # the write was restarted. Under --verbose the 0 is kept and only the null is dropped: the server sends
+    # null exactly for an unknown write_id, and printing that as 0 would let a caller aggregating polls count
+    # a row that does not exist as a write that ran clean.
+    restart_count = item.get("restart_count")
+    show_restart_count = restart_count is not None if verbose else bool(restart_count)
+    if show_restart_count:
+        curated["restart_count"] = restart_count
     return _add_verbose_extras(curated, item, verbose)
 
 
@@ -1122,6 +1141,9 @@ def cmd_write_status(args: argparse.Namespace) -> tuple[CliOutput, int]:
                 }
             last_status = item.get("write_status", "unknown")
             last_body = item
+            # Mirrors the terminal tail of WriteQueueStatus (completed, failed, not_found). Hand-written
+            # rather than derived: this CLI is stdlib-only by design and imports nothing from the server
+            # packages, so the enum is out of reach here.
             if last_status in ("completed", "failed", "not_found"):
                 return item
             if time.monotonic() >= deadline:
@@ -1444,6 +1466,7 @@ def _cmd_auth_login_email(args: argparse.Namespace) -> tuple[CliOutput, int]:
             ),
             EXIT_HTTP_ERROR,
         )
+
     explicit_api = _explicit_api_url(args)
     rc_origin = rc.api_url.strip() if rc is not None and rc.api_url.strip() else None
     api_origin = explicit_api or rc_origin or DEFAULT_API_URL
@@ -1641,7 +1664,7 @@ def _cmd_auth_login_email(args: argparse.Namespace) -> tuple[CliOutput, int]:
         detail = getattr(exc, "strerror", None) or type(exc).__name__
         return (
             make_error(
-                f"could not write {RC_FILENAME} ({detail}). The minted key \"{result.key_name}\" "
+                f'could not write {RC_FILENAME} ({detail}). The minted key "{result.key_name}" '
                 f"(prefix {result.key_prefix}…) is active — revoke it in the Console if it should not stay.",
                 stage="login",
             ),