xmemcli 0.0.12__tar.gz → 1.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xmemcli
-Version: 0.0.12
+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.12**.
+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 refuses to guess the Console (pass `--console-url` or set `$XMEM_CONSOLE_URL`), 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.
+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.12` (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,6 +517,14 @@ 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 `--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. 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.12 → xmemcli-1.0.0}/README.md

@@ -89,7 +89,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.12**.
+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 refuses to guess the Console (pass `--console-url` or set `$XMEM_CONSOLE_URL`), 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.
+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.12` (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,6 +509,14 @@ 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 `--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. 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.12 → xmemcli-1.0.0}/pyproject.toml

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

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

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

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

{xmemcli-0.0.12 → 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
@@ -77,6 +78,62 @@ CLI_LOGIN_PATH = "/xmemcli"
 CLI_TOKEN_PROXY_PATH = "/api/cli/token"
 CLI_WHOAMI_PROXY_PATH = "/api/cli/whoami"
 
+#: Mount paths of a single-origin deployment, where one hostname serves every surface under
+#: fixed path prefixes. An API base ending in ``/xmem`` therefore names its Console and MCP
+#: siblings by construction — the grammar ``single_origin_sibling_url`` implements.
+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
@@ -130,8 +187,43 @@ def challenge_for(verifier: str) -> str:
     return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
 
 
+def single_origin_sibling_url(api_url: str, *, sibling_path: str) -> str | None:
+    """``https://host/xmem`` → ``https://host<sibling_path>``, or None when the shape says nothing.
+
+    Exact on purpose: only an API base whose path is exactly ``/xmem`` sits on a single-origin
+    deployment, where the siblings are fixed by the routing grammar. A bare origin (a five-host
+    deployment) infers nothing, and extra path segments, query, fragment, or credentials make it
+    someone else's URL. Hostname surgery (``api.stg`` → ``mcp.stg``) is deliberately not done
+    here — deriving one *hostname* from another is what the pairing table in ``_mcp_bridge``
+    exists to avoid guessing.
+    """
+    try:
+        parsed = urlsplit(api_url.strip())
+        _ = parsed.port  # the port is parsed lazily; force it — a malformed URL must refuse, not raise
+    except ValueError:
+        # `urlsplit` itself raises on an unbracketed-IPv6 shape, and this helper sees origins
+        # read from an rc file the user may have edited by hand (see `_host_of` in _mcp_bridge).
+        return None
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        return None
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        return None
+    if parsed.path.rstrip("/") != SINGLE_ORIGIN_API_PATH:
+        return None
+    return f"{parsed.scheme}://{parsed.netloc}{sibling_path}"
+
+
 def console_url_from_api_url(api_url: str) -> str | None:
-    """Local dev convention: API on :8000, Console on :8002 (same host)."""
+    """Infer the Console base from an API base, where the deployment layout determines it.
+
+    Two shapes qualify: a single-origin ``/xmem`` base names its ``/console`` sibling on the
+    same host, and the local dev convention pairs API :8000 with Console :8002 on the same
+    loopback host. A bare non-loopback origin infers nothing — five-host deployments name
+    their Console explicitly.
+    """
+    sibling = single_origin_sibling_url(api_url, sibling_path=SINGLE_ORIGIN_CONSOLE_PATH)
+    if sibling is not None:
+        return sibling
     parsed = urlparse(api_url.rstrip("/"))
     if parsed.hostname not in LOOPBACK_HOSTS:
         return None
@@ -147,16 +239,31 @@ def console_url_from_api_url(api_url: str) -> str | None:
     return None
 
 
-def console_url_for_api(*, console_url: str | None = None) -> str:
-    """Resolve the Console origin for PKCE login and token/whoami proxies."""
+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 ``--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("/")
-    api_from_env = os.environ.get(_ENV_API_URL, "").strip()
-    if api_from_env:
-        inferred = console_url_from_api_url(api_from_env)
+    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
@@ -226,22 +333,35 @@ def write_login_handoff_prompt(
     out.flush()
 
 
+def _api_candidates(api_url: str, *, path: str, legacy_path: str) -> list[str]:
+    """The API's own route for something, plus the ``/api``-prefixed spelling where it can exist.
+
+    The second candidate is compatibility only: it answers a deployment served at the origin
+    root, which replies under ``/api`` as well. A base that carries a mount cannot serve it —
+    on a single-origin deployment the API is at ``https://host/xmem`` and
+    ``https://host/xmem/api/whoami`` is a path no layout produces — so it is left out there
+    rather than spending a request, and a 404, on a URL known in advance to be wrong.
+    """
+    base = api_url.rstrip("/")
+    if urlsplit(base).path:
+        return [f"{base}{path}"]
+    return [f"{base}{path}", f"{base}{legacy_path}"]
+
+
 def token_redeem_urls(*, api_url: str, console_url: str | None) -> list[str]:
     """Candidate ``POST /cli/token`` URLs, most likely first."""
-    console = console_url_for_api(console_url=console_url)
     if console_url or os.environ.get(_ENV_CONSOLE_URL, "").strip():
+        console = console_url_for_api(console_url=console_url)
         return [f"{console.rstrip('/')}{CLI_TOKEN_PROXY_PATH}"]
-    base = api_url.rstrip("/")
-    return [f"{base}/cli/token", f"{base}/api/cli/token"]
+    return _api_candidates(api_url, path="/cli/token", legacy_path="/api/cli/token")
 
 
 def whoami_urls(*, api_url: str, console_url: str | None) -> list[str]:
     """Candidate ``GET /whoami`` URLs for bearer API-key lookup, most likely first."""
-    console = console_url_for_api(console_url=console_url)
     if console_url or os.environ.get(_ENV_CONSOLE_URL, "").strip():
+        console = console_url_for_api(console_url=console_url)
         return [f"{console.rstrip('/')}{CLI_WHOAMI_PROXY_PATH}"]
-    base = api_url.rstrip("/")
-    return [f"{base}/whoami", f"{base}/api/whoami"]
+    return _api_candidates(api_url, path="/whoami", legacy_path="/api/whoami")
 
 
 def origin_of(url: str) -> tuple[str, str, int]:
@@ -516,6 +636,7 @@ def wait_for_callback(
     callback_port: int = EPHEMERAL_CALLBACK_PORT,
     stop: threading.Event | None = None,
     console_url: str | None = None,
+    api_url: str | None = None,
 ) -> dict[str, str]:
     """Listen for the browser's local callback carrying the signed code.
 
@@ -548,7 +669,7 @@ def wait_for_callback(
     bound_port = server.server_address[1]
     server.timeout = 0.5
     try:
-        server.console_origin = serialized_origin(console_url_for_api(console_url=console_url))
+        server.console_origin = serialized_origin(console_url_for_api(console_url=console_url, api_url=api_url))
         on_url(build_url(redirect_uri_for_port(bound_port)))
         deadline = time.monotonic() + timeout_s
         while server.captured is None and not (stop and stop.is_set()):
@@ -798,6 +919,7 @@ def wait_for_handoff(
                 callback_port=callback_port,
                 stop=stop,
                 console_url=console_url,
+                api_url=api_url,
             )
             code = params.get("code")
             if not code:
@@ -895,7 +1017,7 @@ def run_pkce_login(
     notify: Callable[[str], None] | None = None,
 ) -> HandoffResult:
     """Open the Console login page and wait for loopback callback and/or hidden stdin paste."""
-    console = console_url_for_api(console_url=console_url)
+    console = console_url_for_api(console_url=console_url, api_url=api_url)
     challenge = challenge_for(verifier)
     return wait_for_handoff(
         api_url,

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

@@ -29,12 +29,14 @@ import argparse
 import io
 import ipaddress
 import json
+import os
 import sys
 import urllib.parse
 import urllib.error
 import urllib.request
 from typing import IO, Any, override
 
+from . import _login
 from ._xmem_bridge import xmem_module
 
 #: JSON-RPC's reserved range ends at -32000; everything at or below it is free for an
@@ -534,7 +536,34 @@ def _unusable_origin(origin: str) -> str | None:
     return None
 
 
-def _refuse_foreign_origin(api_origin: str | None, mcp_origin: str, m: Any) -> str | None:
+def _is_single_origin_pair(api_origin: str, mcp_origin: str, m: Any) -> bool:
+    """One host serving the API at ``/xmem`` and MCP at ``/mcp`` — one deployment.
+
+    On such a deployment the mounts are path siblings of the same origin, so a key bound to
+    the ``/xmem`` base stays home when sent to the ``/mcp`` sibling. Path-aware on purpose:
+    the canonical forms used by the table strip paths and cannot tell ``/mcp`` from any
+    other path on that host, so the MCP side's path is pinned here before origins are
+    compared.
+    """
+    expected = _login.single_origin_sibling_url(api_origin, sibling_path=_login.SINGLE_ORIGIN_MCP_PATH)
+    if expected is None:
+        return False
+    try:
+        parsed = urllib.parse.urlsplit(mcp_origin.strip())
+    except ValueError:
+        return False
+    if parsed.path.rstrip("/") != _login.SINGLE_ORIGIN_MCP_PATH or parsed.query or parsed.fragment:
+        return False
+    return _canonical_origin(expected, m) == _canonical_origin(mcp_origin, m)
+
+
+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
@@ -544,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
@@ -554,6 +586,15 @@ def _refuse_foreign_origin(api_origin: str | None, mcp_origin: str, m: Any) -> s
     mcp = _canonical_origin(mcp_origin, m)
     if _deployments(m).get(api) == mcp:
         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
@@ -609,11 +650,23 @@ def cmd_mcp(args: argparse.Namespace) -> int:
         )
         _eprint(unavailable)
 
+    # 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
     # ever got, so a malformed one reached `urllib` and raised out of the loop.
     if unavailable is None:
-        unavailable = _unusable_origin(m._mcp_url(args))
+        unavailable = _unusable_origin(mcp_origin)
         if unavailable is not None:
             _eprint(unavailable)
 
@@ -624,11 +677,13 @@ 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, m._mcp_url(args), m)
+        unavailable = _refuse_foreign_origin(
+            api_origin, mcp_origin, m, effective_api_base=effective_api_base
+        )
         if unavailable is not None:
             _eprint(unavailable)
 
-    url = f"{m._mcp_url(args).rstrip('/')}/instance/{instance_id}"
+    url = f"{mcp_origin.rstrip('/')}/instance/{instance_id}"
     return _pump(*_utf8_stdio(), url, api_key, unavailable)
 
 

{xmemcli-0.0.12 → 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.12 → 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.12"
+__version__ = "1.0.0"

{xmemcli-0.0.12 → 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
 
 
@@ -882,6 +943,29 @@ def _normalize_api_origin(url: str) -> str | None:
     return f"{scheme}://{host}:{port}"
 
 
+def _normalize_api_base_url(url: str) -> str | None:
+    """Canonical *request* base: the normalized origin plus the URL's own path, sans trailing slash.
+
+    ``_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, 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.
+    """
+    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 = parsed.path.rstrip("/")
+    return f"{origin}{path}" if path else origin
+
+
 def _origins_match(a: str, b: str) -> bool:
     norm_a = _normalize_api_origin(a)
     norm_b = _normalize_api_origin(b)
@@ -955,7 +1039,7 @@ def _api_url(args: argparse.Namespace) -> str:
     # explicit --api-key / $XMEM_API_KEY skips rc api_url (see AUTH-FLOW.md).
     explicit_url = args.api_url or os.environ.get(ENV_API_URL)
     if explicit_url:
-        return _normalize_api_origin(explicit_url) or explicit_url.rstrip("/")
+        return _normalize_api_base_url(explicit_url) or explicit_url.rstrip("/")
     # No explicit origin. The rc supplies the default origin ONLY when the rc is also the
     # credential source — i.e. when no explicit key was given. With an explicit --api-key /
     # $XMEM_API_KEY the rc is irrelevant (its api_url binds only the rc's own key), and a
@@ -963,23 +1047,36 @@ def _api_url(args: argparse.Namespace) -> str:
     # default WITHOUT reading the rc. This mirrors the same explicit-key escape hatch in
     # _require(), so `--api-key` + a broken rc + no --api-url resolves cleanly end to end.
     if args.api_key or os.environ.get(ENV_API_KEY):
-        return _normalize_api_origin(DEFAULT_API_URL) or DEFAULT_API_URL.rstrip("/")
+        return _normalize_api_base_url(DEFAULT_API_URL) or DEFAULT_API_URL.rstrip("/")
     rc = _rc_record(args)
     fallback = (rc.api_url if rc else None) or DEFAULT_API_URL
-    return _normalize_api_origin(fallback) or fallback.rstrip("/")
+    return _normalize_api_base_url(fallback) or fallback.rstrip("/")
 
 
 def _explicit_api_url(args: argparse.Namespace) -> str | None:
-    """Origin from flags/env only — never from ``.xmemrc.json``."""
+    """API base from flags/env only — never from ``.xmemrc.json``."""
     explicit = args.api_url or os.environ.get(ENV_API_URL)
     if not explicit:
         return None
-    return _normalize_api_origin(explicit) or explicit.rstrip("/")
+    return _normalize_api_base_url(explicit) or explicit.rstrip("/")
 
 
-def _mcp_url(args: argparse.Namespace) -> str:
-    """The MCP origin: flag, then environment, then the default."""
-    return (getattr(args, "mcp_url", None) or os.environ.get(ENV_MCP_URL) or DEFAULT_MCP_URL).strip()
+def _mcp_url(args: argparse.Namespace, *, api_url: str | None = None) -> str:
+    """The MCP base: flag, then environment, then the API base's single-origin sibling, then the default.
+
+    The sibling step is what lets an rc minted against ``https://host/xmem`` reach
+    ``https://host/mcp`` with no extra flags — on a single-origin deployment the two are one
+    host by construction. It fires only on that exact shape; every other API base leaves the
+    default in place.
+    """
+    explicit = (getattr(args, "mcp_url", None) or os.environ.get(ENV_MCP_URL) or "").strip()
+    if explicit:
+        return explicit
+    if api_url:
+        inferred = _login.single_origin_sibling_url(api_url, sibling_path=_login.SINGLE_ORIGIN_MCP_PATH)
+        if inferred:
+            return inferred
+    return DEFAULT_MCP_URL
 
 
 def _rc_dir(args: argparse.Namespace) -> Path:
@@ -1467,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_origin(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:
@@ -1683,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)
 
 
@@ -1703,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_origin(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()
@@ -1752,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)
 
 
@@ -2643,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)