fmind 2.0.0__tar.gz → 2.0.2__tar.gz

{fmind-2.0.0 → fmind-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fmind
-Version: 2.0.0
+Version: 2.0.2
 Summary: Read Médéric Hurier's (Fmind) portfolio from the terminal.
 Keywords: portfolio,cli,fmind,resume,articles
 Author: Médéric Hurier
@@ -36,7 +36,7 @@ Every command renders a document the website already publishes — the portfolio
 
 This package carries no copy of the portfolio and needs **no release for content updates**: new articles, a renewed certification or a new engagement appear on the next run. Removing or changing fields that the CLI renders can require a client update; the live compatibility workflow detects those breaks.
 
-Every command fetches from the website and asks HTTP caches to revalidate. There is no local cache and no `--refresh` option. An internet connection is required: if the website cannot be read, the command reports an error instead of showing stale information.
+Every command fetches from the website and asks HTTP caches to revalidate. There is no local cache and no `--refresh` option. Each portfolio download has a 15-second total deadline, including connection setup and response reading, and an 8 MiB response limit. An internet connection is required: if the website cannot be read, the command reports an error instead of showing stale information.
 
 ## Commands
 
@@ -74,7 +74,7 @@ fmind search "agent security"
 fmind search --tag MLOps --limit 3
 ```
 
-`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. In an interactive terminal it pages through `$PAGER` (default `less`, with `LESS=FRX` unless you set `LESS`), so short articles print directly; `PAGER=cat` disables paging. Use `--raw` for the Markdown source.
+`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. In an interactive terminal it pages through `$PAGER` (default `less`, with `LESS=FRX` unless you set `LESS`), so short articles print directly; `PAGER=cat` disables paging. If the selected pager cannot start or exits unsuccessfully, the command reports an error; retry with `PAGER=cat`. Use `--raw` for the Markdown source.
 
 ```bash
 slug="$(fmind articles --limit 1 --json | jq -r '.[0].slug')"
@@ -136,7 +136,7 @@ For a host that accepts JSON configuration:
 }
 ```
 
-`fmind mcp` connects to `https://www.fmind.dev/mcp` using Streamable HTTP and forwards the website's tools, resources, and prompts over stdio. The website owns their names, schemas, and content. Set `FMIND_PROFILE_URL` in the host's environment to use `/mcp` on another website origin. No local data or response cache is used. Requests have a 15-second deadline and remote HTTP responses are limited to 8 MiB.
+`fmind mcp` connects to `https://www.fmind.dev/mcp` using Streamable HTTP and forwards the website's tools, resources, and prompts over stdio. The website owns their names, schemas, and content. Set `FMIND_PROFILE_URL` in the host's environment to use `/mcp` on another website origin. No local data or response cache is used. The website answers MCP POST requests with JSON; GET/HEAD return `405` with `Allow: POST` because notification streams are not offered. Use `/health` for uptime probes. Requests have a 15-second deadline and remote HTTP responses are limited to 8 MiB.
 
 Stdout carries only MCP messages; startup errors go to stderr. Portfolio output flags such as `--json` do not apply to `mcp`. The bridge forwards read-only request/response operations; subscriptions and server-initiated sampling or elicitation are not advertised.
 

{fmind-2.0.0 → fmind-2.0.2}/README.md

@@ -12,7 +12,7 @@ Every command renders a document the website already publishes — the portfolio
 
 This package carries no copy of the portfolio and needs **no release for content updates**: new articles, a renewed certification or a new engagement appear on the next run. Removing or changing fields that the CLI renders can require a client update; the live compatibility workflow detects those breaks.
 
-Every command fetches from the website and asks HTTP caches to revalidate. There is no local cache and no `--refresh` option. An internet connection is required: if the website cannot be read, the command reports an error instead of showing stale information.
+Every command fetches from the website and asks HTTP caches to revalidate. There is no local cache and no `--refresh` option. Each portfolio download has a 15-second total deadline, including connection setup and response reading, and an 8 MiB response limit. An internet connection is required: if the website cannot be read, the command reports an error instead of showing stale information.
 
 ## Commands
 
@@ -50,7 +50,7 @@ fmind search "agent security"
 fmind search --tag MLOps --limit 3
 ```
 
-`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. In an interactive terminal it pages through `$PAGER` (default `less`, with `LESS=FRX` unless you set `LESS`), so short articles print directly; `PAGER=cat` disables paging. Use `--raw` for the Markdown source.
+`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. In an interactive terminal it pages through `$PAGER` (default `less`, with `LESS=FRX` unless you set `LESS`), so short articles print directly; `PAGER=cat` disables paging. If the selected pager cannot start or exits unsuccessfully, the command reports an error; retry with `PAGER=cat`. Use `--raw` for the Markdown source.
 
 ```bash
 slug="$(fmind articles --limit 1 --json | jq -r '.[0].slug')"
@@ -112,7 +112,7 @@ For a host that accepts JSON configuration:
 }
 ```
 
-`fmind mcp` connects to `https://www.fmind.dev/mcp` using Streamable HTTP and forwards the website's tools, resources, and prompts over stdio. The website owns their names, schemas, and content. Set `FMIND_PROFILE_URL` in the host's environment to use `/mcp` on another website origin. No local data or response cache is used. Requests have a 15-second deadline and remote HTTP responses are limited to 8 MiB.
+`fmind mcp` connects to `https://www.fmind.dev/mcp` using Streamable HTTP and forwards the website's tools, resources, and prompts over stdio. The website owns their names, schemas, and content. Set `FMIND_PROFILE_URL` in the host's environment to use `/mcp` on another website origin. No local data or response cache is used. The website answers MCP POST requests with JSON; GET/HEAD return `405` with `Allow: POST` because notification streams are not offered. Use `/health` for uptime probes. Requests have a 15-second deadline and remote HTTP responses are limited to 8 MiB.
 
 Stdout carries only MCP messages; startup errors go to stderr. Portfolio output flags such as `--json` do not apply to `mcp`. The bridge forwards read-only request/response operations; subscriptions and server-initiated sampling or elicitation are not advertised.
 

{fmind-2.0.0 → fmind-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fmind"
-version = "2.0.0"
+version = "2.0.2"
 description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
 readme = "README.md"
 license = "MIT"

{fmind-2.0.0 → fmind-2.0.2}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 # https://packaging.python.org/en/latest/specifications/pyproject-toml/
 [project]
 name = "fmind"
-version = "2.0.0"
+version = "2.0.2"
 description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
 readme = "README.md"
 license = "MIT"

{fmind-2.0.0 → fmind-2.0.2}/src/fmind/api.py

@@ -5,7 +5,10 @@ from __future__ import annotations
 import http.client
 import json
 import os
+import queue
 import re
+import threading
+import time
 import urllib.error
 import urllib.parse
 import urllib.request
@@ -80,27 +83,63 @@ def origin_url(path: str, *, profile_url: str | None = None) -> str:
 
 
 def _download(url: str, accept: str = "application/json") -> bytes:
-    """Fetch a document over HTTP(S) with an explicit timeout and size bound."""
+    """Fetch a document within a wall-clock deadline, including DNS and headers."""
     _http_url(url)
+    deadline = time.monotonic() + TIMEOUT_SECONDS
+    result: queue.Queue[bytes | Exception] = queue.Queue(maxsize=1)
+
+    def fetch() -> None:
+        try:
+            result.put(_fetch(url, accept, deadline))
+        except Exception as error:
+            result.put(error)
+
+    # DNS and urllib's header reads cannot be cancelled portably. A daemon does
+    # not hold the CLI open after the deadline; body reads stop cooperatively.
+    threading.Thread(target=fetch, daemon=True).start()
+    try:
+        outcome = result.get(timeout=max(0.0, deadline - time.monotonic()))
+    except queue.Empty as error:
+        raise FmindError("the website request timed out; check your connection and FMIND_PROFILE_URL") from error
+    if isinstance(outcome, Exception):
+        raise outcome
+    return outcome
+
+
+def _fetch(url: str, accept: str, deadline: float) -> bytes:
+    """Perform bounded I/O; never print or mutate caller state from the worker."""
     # Ask intermediary HTTP caches to revalidate too; no local copy is kept.
     headers = {"User-Agent": USER_AGENT, "Accept": accept, "Cache-Control": "no-cache"}
     try:
+        if time.monotonic() >= deadline:
+            raise TimeoutError("website request deadline exceeded")
         request = urllib.request.Request(url, headers=headers)  # noqa: S310
         with urllib.request.urlopen(request, timeout=TIMEOUT_SECONDS) as response:  # noqa: S310
-            payload = response.read(MAX_BYTES + 1)
+            payload = bytearray()
+            while len(payload) <= MAX_BYTES:
+                if time.monotonic() >= deadline:
+                    raise TimeoutError("website request deadline exceeded")
+                # read() can wait indefinitely for a slowly progressing body.
+                # read1() returns after at most one underlying read.
+                chunk = response.read1(min(64 * 1024, MAX_BYTES + 1 - len(payload)))
+                if not chunk:
+                    break
+                payload.extend(chunk)
             length = response.headers.get("Content-Length")
             if len(payload) <= MAX_BYTES and length is not None and len(payload) != int(length):
-                raise http.client.IncompleteRead(payload)
+                raise http.client.IncompleteRead(bytes(payload))
     except urllib.error.HTTPError as error:
         msg = f"the website returned HTTP {error.code}"
         raise FmindError(msg) from error
+    except TimeoutError as error:
+        raise FmindError("the website request timed out; check your connection and FMIND_PROFILE_URL") from error
     except (urllib.error.URLError, OSError, http.client.HTTPException, ValueError) as error:
         msg = "could not read the website; check your connection and FMIND_PROFILE_URL"
         raise FmindError(msg) from error
     if len(payload) > MAX_BYTES:
         msg = f"the website returned more than {MAX_BYTES} bytes"
         raise FmindError(msg)
-    return payload
+    return bytes(payload)
 
 
 def _validate(value: object, shape: object, path: str) -> None:
@@ -125,6 +164,21 @@ def _parse_profile(payload: bytes) -> dict[str, Any]:
         document = json.loads(payload)
     except (ValueError, RecursionError) as error:
         raise FmindError("the profile endpoint did not return JSON") from error
+    # Python's JSON decoder accepts lone surrogates. Check keys and future fields
+    # too: JSON output forwards them even when the renderer does not consume them.
+    pending = [document]
+    while pending:
+        value = pending.pop()
+        if isinstance(value, str):
+            try:
+                value.encode("utf-8")
+            except UnicodeEncodeError as error:
+                raise FmindError("the profile endpoint returned invalid Unicode") from error
+        elif isinstance(value, dict):
+            pending.extend(value)
+            pending.extend(value.values())
+        elif isinstance(value, list):
+            pending.extend(value)
     _validate(document, PROFILE_SHAPE, "profile")
     links = document["thesis"].get("links")
     if links is not None:

{fmind-2.0.0 → fmind-2.0.2}/src/fmind/cli.py

@@ -16,7 +16,7 @@ from rich.console import Console, RenderableType
 from rich.pager import Pager
 
 from fmind import __version__, articles, render
-from fmind.api import FmindError, load_article, load_profile
+from fmind.api import CONTROL_PATTERN, FmindError, load_article, load_profile
 
 app = typer.Typer(
     name="fmind",
@@ -58,6 +58,8 @@ def main(
 
 def _fail(message: str) -> typer.Exit:
     """Report a clear one-line error on stderr and end the command."""
+    message = CONTROL_PATTERN.sub(lambda match: ascii(match.group())[1:-1], message)
+    message = message.encode("utf-8", errors="backslashreplace").decode("utf-8")
     typer.echo(f"fmind: {' '.join(message.split())}", err=True)
     return typer.Exit(code=1)
 
@@ -80,7 +82,12 @@ class _SystemPager(Pager):
         # Like Git: respect an explicit LESS, otherwise keep colours (-R), skip
         # paging for short output (-F), and leave the text on screen (-X).
         environment = {**os.environ, "LESS": os.environ.get("LESS", "FRX")}
-        subprocess.run(self.command, input=content.encode(), env=environment, check=False)  # noqa: S603
+        try:
+            subprocess.run(  # noqa: S603
+                self.command, input=content.encode(), env=environment, stderr=subprocess.DEVNULL, check=True
+            )
+        except (OSError, subprocess.CalledProcessError) as error:
+            raise FmindError("could not display the article with PAGER; check PAGER or use PAGER=cat") from error
 
 
 def _pager_command() -> list[str] | None:
@@ -119,8 +126,11 @@ def _emit(ctx: typer.Context, body: RenderableType, payload: Any, *, as_json: bo
     if command is None:
         out.print(body, crop=False)
         return
-    with out.pager(pager=_SystemPager(command), styles=True):
-        out.print(body, crop=False)
+    try:
+        with out.pager(pager=_SystemPager(command), styles=True):
+            out.print(body, crop=False)
+    except FmindError as error:
+        raise _fail(str(error)) from error
 
 
 @app.command()