xmemcli 0.0.13__tar.gz → 1.0.0__tar.gz

{xmemcli-0.0.13 → xmemcli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xmemcli
-Version: 0.0.13
+Version: 1.0.0
 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
@@ -97,7 +97,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.13**.
+Version: **1.0.0**.
 
 
 ---
@@ -151,7 +151,7 @@ AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never hand
 4. With the session, the CLI runs the Console onboarding's core sequence: `GET /api/check-user`; when the address has no account, `GET /api/suggest-slug` (server-derived org name, `--org-name` overrides; ignored for an existing account) and `POST /api/public-signup` — **note that creating a new organisation requires the deployment to allow public registration, which the hosted service currently does not**: an existing account gets a key, a new address gets the server's "organisation creation is not available" refusal (the Console's admin-fallback signup arm is not implemented here); then `GET /api/accounts/users/by-email`, `GET /api/accounts/api-roles` (the seeded default role, or the org's only role — an ambiguous set is refused, never guessed), and `POST /api/accounts/api-keys` with **no cluster list** — the key attaches to every cluster the org has at mint time. Clusters created later are attached by a server-side backfill that repairs only keys already linked to every other cluster in the org; an org with no clusters at mint time gets a key attached to nothing. The key is named **`CLI email login (<hostname>, <timestamp>)`** so every mint stays individually identifiable and revocable on the Console's API Keys page.
 5. The key is written to `.xmemrc.json` (0600), stdout carries the prefix only, and the session cookie dies with the process.
 
-The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url` or set `$XMEM_CONSOLE_URL`). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
+The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and that sibling beats `$XMEM_CONSOLE_URL` on the same call — and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url` or set `$XMEM_CONSOLE_URL` when inference does not apply). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
 
 When the server offers no matching code on the request reply (cross-device hand-off disabled, no public Console origin configured, or a transient degradation), there is nothing for a headless starter to claim — the emailed link then signs in the *approving* browser — so the CLI falls back to the emailed **six-digit code typed into the terminal** (`POST /api/kingdom-signin-verify`), still a single human action. That fallback needs an interactive stdin; a non-interactive run cancels the attempt it just started (the mode is only known from the server's reply, after the email is on its way) and refuses with instructions — the typed code dies with that cancel, but on such a server the one-click link has nothing durable to revoke and stays redeemable in a browser until it expires (about five minutes), which the terminal states plainly.
 
@@ -163,7 +163,7 @@ Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking
 
 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. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of a single-origin API base → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
+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. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds; query, fragment, and userinfo on a base URL refuse normalisation rather than being stripped, so sibling inference cannot run on a shape the caller did not supply. Console resolution for login: `--console-url` → sibling inference from the call's `--api-url` when it applies → `$XMEM_CONSOLE_URL` → sibling inference from `$XMEM_API_URL` → default — when `--api-url` is present, `$XMEM_API_URL` is not consulted for Console inference. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of the effective API base (`--api-url` → `$XMEM_API_URL` → rc → default) → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
 
 ## Identity — `/whoami`
 
@@ -193,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.13` (see `xmemcli version`)
+**Version:** `1.0.0` (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.
 
@@ -517,9 +517,13 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, …)
 
 **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.
 
-**Compatibility change in 0.0.13 (single-origin deployments):** an API base URL's path is now **preserved**, never stripped — `--api-url https://host/xmem` builds requests under `/xmem` instead of reducing to the bare origin. Where the base's path is exactly `/xmem`, the CLI infers its single-origin siblings on the same host: `auth login` finds the Console at `/console` without `--console-url`, and `xmemcli mcp` reaches `/mcp` without `--mcp-url` (explicit flags and `$XMEM_CONSOLE_URL` / `$XMEM_MCP_URL` still win, and the MCP origin guard accepts the `/xmem` ↔ `/mcp` pair as one deployment). Bare origins and every other path shape behave exactly as before. See `cli/`.
+**Compatibility change in 0.0.13 (single-origin deployments):** an API base URL's path is now **preserved**, never stripped — `--api-url https://host/xmem` builds requests under `/xmem` instead of reducing to the bare origin. Where the base's path is exactly `/xmem`, the CLI infers its single-origin siblings on the same host: `auth login` finds the Console at `/console` without `--console-url`, and `xmemcli mcp` reaches `/mcp` without `--mcp-url` (explicit `--console-url` / `--mcp-url` and `$XMEM_CONSOLE_URL` / `$XMEM_MCP_URL` still win when inference does not apply; on a call that names `--api-url …/xmem`, sibling inference beats `$XMEM_CONSOLE_URL`; the MCP origin guard accepts the `/xmem` ↔ `/mcp` pair as one deployment). Bare origins and every other path shape behave exactly as before. See `cli/`.
 
-Two consequences worth knowing. A single-origin deployment's own setup instructions rely on this inference — they render `auth login --api-url https://host/xmem` with **no** `--console-url` — so **0.0.13 is the minimum on such a deployment**; an older CLI given that command signs in at the hosted Console instead. And the inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
+Two consequences worth knowing. Connect instructions from the API assume **1.0.0** or newer everywhere. On a single-origin deployment they also rely on path inference — they render `auth login --api-url https://host/xmem` with **no** `--console-url` — and an older CLI given that command signs in at the hosted Console instead. The inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
+
+**Console instance URLs (1.0.0+):** `xmemcli auth login https://host/console/instance/<uuid>` infers the API base (`/xmem`) and Console (`/console`) from that page URL on a single-origin host — no extra flags or env vars. The Connect tab paste prompt uses this form, and the CLI writes the inferred ``api_url`` into ``.xmemrc.json`` as soon as login starts.
+
+**Compatibility change in 1.0.0:** console instance page URLs for login (above), immediate ``api_url`` staging in ``.xmemrc.json``, and **1.0.0** as the minimum version named by connect setup instructions.
 
 See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 

{xmemcli-0.0.13 → xmemcli-1.0.0}/README.md

@@ -89,7 +89,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.13**.
+Version: **1.0.0**.
 
 
 ---
@@ -143,7 +143,7 @@ AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never hand
 4. With the session, the CLI runs the Console onboarding's core sequence: `GET /api/check-user`; when the address has no account, `GET /api/suggest-slug` (server-derived org name, `--org-name` overrides; ignored for an existing account) and `POST /api/public-signup` — **note that creating a new organisation requires the deployment to allow public registration, which the hosted service currently does not**: an existing account gets a key, a new address gets the server's "organisation creation is not available" refusal (the Console's admin-fallback signup arm is not implemented here); then `GET /api/accounts/users/by-email`, `GET /api/accounts/api-roles` (the seeded default role, or the org's only role — an ambiguous set is refused, never guessed), and `POST /api/accounts/api-keys` with **no cluster list** — the key attaches to every cluster the org has at mint time. Clusters created later are attached by a server-side backfill that repairs only keys already linked to every other cluster in the org; an org with no clusters at mint time gets a key attached to nothing. The key is named **`CLI email login (<hostname>, <timestamp>)`** so every mint stays individually identifiable and revocable on the Console's API Keys page.
 5. The key is written to `.xmemrc.json` (0600), stdout carries the prefix only, and the session cookie dies with the process.
 
-The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url` or set `$XMEM_CONSOLE_URL`). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
+The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and that sibling beats `$XMEM_CONSOLE_URL` on the same call — and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url` or set `$XMEM_CONSOLE_URL` when inference does not apply). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
 
 When the server offers no matching code on the request reply (cross-device hand-off disabled, no public Console origin configured, or a transient degradation), there is nothing for a headless starter to claim — the emailed link then signs in the *approving* browser — so the CLI falls back to the emailed **six-digit code typed into the terminal** (`POST /api/kingdom-signin-verify`), still a single human action. That fallback needs an interactive stdin; a non-interactive run cancels the attempt it just started (the mode is only known from the server's reply, after the email is on its way) and refuses with instructions — the typed code dies with that cancel, but on such a server the one-click link has nothing durable to revoke and stays redeemable in a browser until it expires (about five minutes), which the terminal states plainly.
 
@@ -155,7 +155,7 @@ Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking
 
 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. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of a single-origin API base → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
+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. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds; query, fragment, and userinfo on a base URL refuse normalisation rather than being stripped, so sibling inference cannot run on a shape the caller did not supply. Console resolution for login: `--console-url` → sibling inference from the call's `--api-url` when it applies → `$XMEM_CONSOLE_URL` → sibling inference from `$XMEM_API_URL` → default — when `--api-url` is present, `$XMEM_API_URL` is not consulted for Console inference. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of the effective API base (`--api-url` → `$XMEM_API_URL` → rc → default) → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
 
 ## Identity — `/whoami`
 
@@ -185,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.13` (see `xmemcli version`)
+**Version:** `1.0.0` (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.
 
@@ -509,9 +509,13 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, …)
 
 **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.
 
-**Compatibility change in 0.0.13 (single-origin deployments):** an API base URL's path is now **preserved**, never stripped — `--api-url https://host/xmem` builds requests under `/xmem` instead of reducing to the bare origin. Where the base's path is exactly `/xmem`, the CLI infers its single-origin siblings on the same host: `auth login` finds the Console at `/console` without `--console-url`, and `xmemcli mcp` reaches `/mcp` without `--mcp-url` (explicit flags and `$XMEM_CONSOLE_URL` / `$XMEM_MCP_URL` still win, and the MCP origin guard accepts the `/xmem` ↔ `/mcp` pair as one deployment). Bare origins and every other path shape behave exactly as before. See `cli/`.
+**Compatibility change in 0.0.13 (single-origin deployments):** an API base URL's path is now **preserved**, never stripped — `--api-url https://host/xmem` builds requests under `/xmem` instead of reducing to the bare origin. Where the base's path is exactly `/xmem`, the CLI infers its single-origin siblings on the same host: `auth login` finds the Console at `/console` without `--console-url`, and `xmemcli mcp` reaches `/mcp` without `--mcp-url` (explicit `--console-url` / `--mcp-url` and `$XMEM_CONSOLE_URL` / `$XMEM_MCP_URL` still win when inference does not apply; on a call that names `--api-url …/xmem`, sibling inference beats `$XMEM_CONSOLE_URL`; the MCP origin guard accepts the `/xmem` ↔ `/mcp` pair as one deployment). Bare origins and every other path shape behave exactly as before. See `cli/`.
 
-Two consequences worth knowing. A single-origin deployment's own setup instructions rely on this inference — they render `auth login --api-url https://host/xmem` with **no** `--console-url` — so **0.0.13 is the minimum on such a deployment**; an older CLI given that command signs in at the hosted Console instead. And the inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
+Two consequences worth knowing. Connect instructions from the API assume **1.0.0** or newer everywhere. On a single-origin deployment they also rely on path inference — they render `auth login --api-url https://host/xmem` with **no** `--console-url` — and an older CLI given that command signs in at the hosted Console instead. The inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
+
+**Console instance URLs (1.0.0+):** `xmemcli auth login https://host/console/instance/<uuid>` infers the API base (`/xmem`) and Console (`/console`) from that page URL on a single-origin host — no extra flags or env vars. The Connect tab paste prompt uses this form, and the CLI writes the inferred ``api_url`` into ``.xmemrc.json`` as soon as login starts.
+
+**Compatibility change in 1.0.0:** console instance page URLs for login (above), immediate ``api_url`` staging in ``.xmemrc.json``, and **1.0.0** as the minimum version named by connect setup instructions.
 
 See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 

{xmemcli-0.0.13 → xmemcli-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "0.0.13"
+version = "1.0.0"
 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.13 → xmemcli-1.0.0}/uv.lock

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

{xmemcli-0.0.13 → xmemcli-1.0.0}/xmemcli/__init__.py

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

{xmemcli-0.0.13 → xmemcli-1.0.0}/xmemcli/_login.py

@@ -22,6 +22,7 @@ import errno
 import hashlib
 import json
 import os
+import re
 import secrets
 import select
 import sys
@@ -84,6 +85,55 @@ SINGLE_ORIGIN_API_PATH = "/xmem"
 SINGLE_ORIGIN_CONSOLE_PATH = "/console"
 SINGLE_ORIGIN_MCP_PATH = "/mcp"
 
+_CONSOLE_INSTANCE_PATH_PREFIX = f"{SINGLE_ORIGIN_CONSOLE_PATH}/instance/"
+_INSTANCE_ID_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    re.IGNORECASE,
+)
+
+
+class ConsoleInstanceLink(NamedTuple):
+    """A Console instance detail page on a single-origin deployment."""
+
+    console_url: str
+    api_url: str
+    instance_id: str
+
+
+def parse_console_instance_url(url: str) -> ConsoleInstanceLink | None:
+    """Derive login targets from ``…/console/instance/<uuid>`` on one hostname.
+
+    Query and fragment are ignored. Only the conventional single-origin mount
+    ``/console/instance/<uuid>`` is recognised — a five-host Console URL must
+    still name ``--api-url`` and ``--console-url`` explicitly.
+    """
+    raw = url.strip()
+    if not raw:
+        return None
+    try:
+        parsed = urlsplit(raw)
+        _ = parsed.port
+    except ValueError:
+        return None
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        return None
+    if parsed.username or parsed.password:
+        return None
+    path = parsed.path.rstrip("/")
+    if not path.startswith(_CONSOLE_INSTANCE_PATH_PREFIX):
+        return None
+    instance_id = path[len(_CONSOLE_INSTANCE_PATH_PREFIX) :]
+    if not instance_id or "/" in instance_id:
+        return None
+    if _INSTANCE_ID_RE.fullmatch(instance_id) is None:
+        return None
+    origin = f"{parsed.scheme}://{parsed.netloc}"
+    return ConsoleInstanceLink(
+        console_url=f"{origin}{SINGLE_ORIGIN_CONSOLE_PATH}",
+        api_url=f"{origin}{SINGLE_ORIGIN_API_PATH}",
+        instance_id=instance_id,
+    )
+
 API_KEY_PREFIX = "xmem_"
 
 #: Hostnames treated as loopback wherever the CLI relaxes an https-only rule or infers the
@@ -192,22 +242,30 @@ def console_url_from_api_url(api_url: str) -> str | None:
 def console_url_for_api(*, console_url: str | None = None, api_url: str | None = None) -> str:
     """Resolve the Console origin for PKCE login and token/whoami proxies.
 
-    Explicit wins (flag, then ``$XMEM_CONSOLE_URL``); then inference from the API base the
-    caller is actually signing in against, then from ``$XMEM_API_URL``; then the default.
-    ``api_url`` outranks the environment because it is the resolved target of this very call
-    — an exported ``$XMEM_API_URL`` must not steer the Console away from an explicit
-    ``--api-url``.
+    Explicit ``--console-url`` wins. When the caller names an API base for this login,
+    that base alone decides whether a Console can be inferred — ``$XMEM_CONSOLE_URL`` and
+    ``$XMEM_API_URL`` are not consulted on that path, so a copy-pasted
+    ``--api-url https://host/xmem`` cannot be steered away by the reader's shell profile.
+    With no ``api_url``, the environment and then the default apply as before.
     """
     if console_url:
         return console_url.rstrip("/")
+    if api_url:
+        inferred = console_url_from_api_url(api_url)
+        if inferred:
+            return inferred
+        from_env = os.environ.get(_ENV_CONSOLE_URL, "").strip()
+        if from_env:
+            return from_env.rstrip("/")
+        return DEFAULT_CONSOLE_URL
     from_env = os.environ.get(_ENV_CONSOLE_URL, "").strip()
     if from_env:
         return from_env.rstrip("/")
-    for candidate in (api_url, os.environ.get(_ENV_API_URL, "").strip()):
-        if candidate:
-            inferred = console_url_from_api_url(candidate)
-            if inferred:
-                return inferred
+    env_api = os.environ.get(_ENV_API_URL, "").strip()
+    if env_api:
+        inferred = console_url_from_api_url(env_api)
+        if inferred:
+            return inferred
     return DEFAULT_CONSOLE_URL
 
 

{xmemcli-0.0.13 → xmemcli-1.0.0}/xmemcli/_mcp_bridge.py

@@ -29,6 +29,7 @@ import argparse
 import io
 import ipaddress
 import json
+import os
 import sys
 import urllib.parse
 import urllib.error
@@ -556,7 +557,13 @@ def _is_single_origin_pair(api_origin: str, mcp_origin: str, m: Any) -> bool:
     return _canonical_origin(expected, m) == _canonical_origin(mcp_origin, m)
 
 
-def _refuse_foreign_origin(api_origin: str | None, mcp_origin: str, m: Any) -> str | None:
+def _refuse_foreign_origin(
+    api_origin: str | None,
+    mcp_origin: str,
+    m: Any,
+    *,
+    effective_api_base: str | None = None,
+) -> str | None:
     """Why this credential may not be sent to this MCP origin, or ``None``.
 
     The key in ``.xmemrc.json`` records the API origin it belongs to, and the CLI holds
@@ -566,6 +573,9 @@ def _refuse_foreign_origin(api_origin: str | None, mcp_origin: str, m: Any) -> s
     user did not write — so the config is not allowed to vouch for itself.
 
     ``api_origin`` is ``None`` when the operator named the credential on this call.
+    ``effective_api_base`` is the flag/env/rc-resolved API base used to infer MCP when
+    no explicit MCP was named — an rc that recorded the bare host while ``--api-url
+    …/xmem`` names the mount for this call still pairs with the ``/mcp`` sibling.
     """
     if api_origin is None:
         # Named on the command line or in the environment: the operator supplied this
@@ -578,6 +588,13 @@ def _refuse_foreign_origin(api_origin: str | None, mcp_origin: str, m: Any) -> s
         return None
     if _is_single_origin_pair(api_origin, mcp_origin, m):
         return None
+    if (
+        effective_api_base
+        and effective_api_base != api_origin
+        and _is_single_origin_pair(effective_api_base, mcp_origin, m)
+        and _canonical_origin(effective_api_base, m) == api
+    ):
+        return None
     # The originals, not the canonical forms: normalising rebuilds an origin as
     # `scheme://host:port`, which for IPv6 drops the brackets that made the address
     # parseable — so `http://[::1]:8000` canonicalises to something no URL parser can
@@ -633,13 +650,17 @@ def cmd_mcp(args: argparse.Namespace) -> int:
         )
         _eprint(unavailable)
 
-    # Resolved once, with the API base as inference context: on a single-origin
-    # deployment (an rc minted against `https://host/xmem`, or that base named on the
-    # call) the MCP endpoint is the `/mcp` sibling of the same host, and no flag or
-    # variable should be needed to say so. `_explicit_api_url` is the rc-free reading
-    # on purpose — a malformed rc already produced `unavailable` above and must not
-    # take this resolution down with it.
-    mcp_origin = m._mcp_url(args, api_url=api_origin or m._explicit_api_url(args))
+    # Explicit MCP wins without parsing an API base at all — a malformed `--api-url` must
+    # not take down a valid `--mcp-url`. Otherwise the effective API base for sibling
+    # inference follows flag → env → rc precedence (`_api_url`), not the credential-bound
+    # origin alone: an rc at the bare host plus `--api-url …/xmem` must still reach `/mcp`.
+    explicit_mcp = (getattr(args, "mcp_url", None) or os.environ.get(m.ENV_MCP_URL) or "").strip()
+    if explicit_mcp:
+        mcp_origin = explicit_mcp
+        effective_api_base: str | None = None
+    else:
+        effective_api_base = m._api_url(args)
+        mcp_origin = m._mcp_url(args, api_url=effective_api_base)
 
     # Is it a URL at all — asked first, and for every caller. The guard below is skipped
     # when the operator names the key, and that used to skip the only look this origin
@@ -656,7 +677,9 @@ def cmd_mcp(args: argparse.Namespace) -> int:
     # anywhere else needs a credential the operator named on the call. `api_origin` comes
     # from the same read as `api_key`, so the two always describe one file.
     if api_key is not None and unavailable is None:
-        unavailable = _refuse_foreign_origin(api_origin, mcp_origin, m)
+        unavailable = _refuse_foreign_origin(
+            api_origin, mcp_origin, m, effective_api_base=effective_api_base
+        )
         if unavailable is not None:
             _eprint(unavailable)
 

{xmemcli-0.0.13 → xmemcli-1.0.0}/xmemcli/_rc.py

@@ -153,6 +153,24 @@ def write_rc(target_dir: Path, *, email: str, api_url: str, api_key: str) -> Pat
     return path
 
 
+def stage_login_api_url(start_dir: Path, api_url: str) -> Path:
+    """Record ``api_url`` in the project rc before PKCE or email approval finishes.
+
+    When a rc already exists, its ``api_url`` is updated in place and the credential
+    is left untouched. Otherwise a placeholder rc is written (empty email/key) so
+    ``_api_url`` names this deployment while login is still in progress.
+    """
+    start_dir.mkdir(parents=True, exist_ok=True)
+    found = find_rc(start_dir)
+    if found is not None:
+        try:
+            record = load_rc(found)
+        except RcError:
+            return write_rc(start_dir, email="", api_url=api_url, api_key="")
+        return write_rc(found.parent, email=record.email, api_url=api_url, api_key=record.api_key)
+    return write_rc(start_dir, email="", api_url=api_url, api_key="")
+
+
 def remove_rc(path: Path) -> bool:
     """Delete the ``.xmemrc.json`` at ``path``. Returns ``True`` iff it existed."""
     try:

{xmemcli-0.0.13 → xmemcli-1.0.0}/xmemcli/_version.py

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

{xmemcli-0.0.13 → xmemcli-1.0.0}/xmemcli/cli.py

@@ -141,6 +141,7 @@ from ._rc import (  # noqa: E402  (sibling-script import)
     load_rc,
     remove_rc,
     resolve_rc,
+    stage_login_api_url,
     write_rc,
 )
 from ._text import oneline
@@ -653,8 +654,68 @@ def _get(url: str, api_key: str, timeout_s: float = 30.0) -> dict[str, Any]:
     return _read_json_response(_build_request(url, "GET", api_key), timeout_s)
 
 
+def _connect_url_from_login_args(args: argparse.Namespace) -> str | None:
+    """Console instance page URL from a positional arg or a mistaken ``--api-url``."""
+    connect = getattr(args, "connect_url", None)
+    if isinstance(connect, str) and connect.strip():
+        return connect.strip()
+    flag_api = getattr(args, "api_url", None)
+    if isinstance(flag_api, str) and flag_api.strip():
+        candidate = flag_api.strip()
+        if _login.parse_console_instance_url(candidate) is not None:
+            return candidate
+    return None
+
+
+def _auth_login_api_base(
+    args: argparse.Namespace,
+    *,
+    rc_origin: str | None = None,
+) -> tuple[str, str | None, tuple[CliOutput, int] | None]:
+    """Resolve the API base (and optional instance id) for ``auth login``."""
+    connect = _connect_url_from_login_args(args)
+    if connect:
+        link = _login.parse_console_instance_url(connect)
+        if link is None:
+            return (
+                "",
+                None,
+                (
+                    make_error(
+                        f"not a single-origin Console instance URL ({connect!r}); expected "
+                        f"…{_login.SINGLE_ORIGIN_CONSOLE_PATH}/instance/<uuid>",
+                        stage="usage",
+                    ),
+                    EXIT_USAGE,
+                ),
+            )
+        return link.api_url, link.instance_id, None
+    explicit_api = _explicit_api_url(args) or os.environ.get(ENV_API_URL, "").strip()
+    api_origin = explicit_api or rc_origin or DEFAULT_API_URL
+    base = _normalize_api_base_url(api_origin) or api_origin.rstrip("/")
+    return base, None, None
+
+
+def _stage_login_api_url_if_connecting(args: argparse.Namespace, api_url: str) -> None:
+    """When login was aimed by a Console instance page URL, persist ``api_url`` immediately."""
+    if _connect_url_from_login_args(args) is None:
+        return
+    stage_login_api_url(_rc_dir(args), api_url)
+
+
+def _console_url_flag_for_args(args: argparse.Namespace) -> str | None:
+    """``--console-url`` only — not ``$XMEM_CONSOLE_URL``.
+
+    ``console_url_for_api`` applies the environment after sibling inference from
+    ``--api-url``; pre-merging the env here would defeat that ordering on a
+    copy-pasted single-origin login command.
+    """
+    explicit = getattr(args, "console_url", None)
+    return explicit.strip() if isinstance(explicit, str) and explicit.strip() else None
+
+
 def _console_url_for_args(args: argparse.Namespace) -> str | None:
-    explicit = getattr(args, "console_url", None) or os.environ.get(ENV_CONSOLE_URL)
+    explicit = _console_url_flag_for_args(args) or os.environ.get(ENV_CONSOLE_URL)
     return explicit.strip() if isinstance(explicit, str) and explicit.strip() else None
 
 
@@ -888,12 +949,20 @@ def _normalize_api_base_url(url: str) -> str | None:
     ``_normalize_api_origin`` exists for origin comparison and deliberately drops the path;
     this form exists for building requests, where a single-origin deployment's ``/xmem``
     mount is load-bearing — stripping it would aim every call at the Console's root instead
-    of the API. Query and fragment are still dropped: a base URL carries neither.
+    of the API. Query, fragment, and userinfo refuse here rather than being stripped: the
+    single-origin sibling helpers treat those components as making a URL non-inferable, and
+    normalizing them away would let inference run on a shape the caller never supplied.
     """
-    origin = _normalize_api_origin(url)
+    raw = url.strip()
+    if not raw:
+        return None
+    parsed = urlsplit(raw)
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        return None
+    origin = _normalize_api_origin(raw)
     if origin is None:
         return None
-    path = urlsplit(url.strip()).path.rstrip("/")
+    path = parsed.path.rstrip("/")
     return f"{origin}{path}" if path else origin
 
 
@@ -1495,11 +1564,12 @@ 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
-    base = _normalize_api_base_url(api_origin) or api_origin.rstrip("/")
-    console, refusal = _email_console_origin(args, api_origin=api_origin)
+    base, instance_hint, usage_error = _auth_login_api_base(args, rc_origin=rc_origin)
+    if usage_error is not None:
+        return usage_error
+    _stage_login_api_url_if_connecting(args, base)
+    console, refusal = _email_console_origin(args, api_origin=base)
     if refusal is not None:
         return refusal
     if console is None:
@@ -1711,6 +1781,8 @@ def _cmd_auth_login_email(args: argparse.Namespace) -> tuple[CliOutput, int]:
     }
     if result.org_name:
         payload["org_name"] = result.org_name
+    if instance_hint:
+        payload["instance_id"] = instance_hint
     return (CliOutput(OutputKind.LOGIN, payload), EXIT_OK)
 
 
@@ -1731,10 +1803,11 @@ def cmd_auth_login(args: argparse.Namespace) -> tuple[CliOutput, int]:
             make_error("--org-name requires --email (it names a new account's organisation)", stage="usage"),
             EXIT_USAGE,
         )
-    explicit_api = _explicit_api_url(args) or os.environ.get(ENV_API_URL, "").strip()
-    console = _console_url_for_args(args)
-    api_origin = explicit_api or DEFAULT_API_URL
-    base = _normalize_api_base_url(api_origin) or api_origin.rstrip("/")
+    base, instance_hint, usage_error = _auth_login_api_base(args)
+    if usage_error is not None:
+        return usage_error
+    _stage_login_api_url_if_connecting(args, base)
+    console = _console_url_flag_for_args(args)
     verifier = _login.new_verifier()
     interactive = stdout_is_tty()
     offer_paste = interactive and _login.paste_from_stdin_supported()
@@ -1780,6 +1853,8 @@ def cmd_auth_login(args: argparse.Namespace) -> tuple[CliOutput, int]:
         "key_prefix": result.key_prefix,
         "rc_file": str(rc_path),
     }
+    if instance_hint:
+        payload["instance_id"] = instance_hint
     return (CliOutput(OutputKind.LOGIN, payload), EXIT_OK)
 
 
@@ -2671,6 +2746,14 @@ def _build_parser() -> argparse.ArgumentParser:
         "--org-name",
         help="Organisation name when --email creates a new account (default: derived from the address)",
     )
+    pal.add_argument(
+        "connect_url",
+        nargs="?",
+        help=(
+            "Console instance page URL (…/console/instance/<uuid> on a single-origin host); "
+            "the API and Console origins are inferred from it"
+        ),
+    )
     pal.set_defaults(func=cmd_auth_login)
     palo = pa_sub.add_parser("logout", help="Remove the credential from the active .xmemrc.json", add_help=False)
     palo.set_defaults(func=cmd_auth_logout)