fmind 2.0.1__tar.gz → 2.0.3__tar.gz

{fmind-2.0.1 → fmind-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fmind
-Version: 2.0.1
+Version: 2.0.3
 Summary: Read Médéric Hurier's (Fmind) portfolio from the terminal.
 Keywords: portfolio,cli,fmind,resume,articles
 Author: Médéric Hurier
@@ -30,14 +30,6 @@ Read [Médéric Hurier's (Fmind)](https://www.fmind.dev/) portfolio from the ter
 uvx fmind whoami
 ```
 
-## Why it stays small
-
-Every command renders a document the website already publishes — the portfolio at [`/api/profile`](https://www.fmind.dev/api/profile) and, for `fmind read`, the Markdown source of an article at `/articles/<slug>.md`. Those are the same sources behind the site, the Atom feed, `llms.txt` and the MCP server.
-
-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.
-
 ## Commands
 
 | Command                                     | Shows                                             |
@@ -74,7 +66,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')"
@@ -158,22 +150,6 @@ The pre-commit hook runs checks without changing or staging files; run `mise run
 
 A release tag must match the version in `pyproject.toml` (for example, `v0.1.0`). CD runs the same full gate for that tag and checks the live commands before publishing through PyPI Trusted Publishing. The live smoke check is a release check, not a pull-request gate.
 
-### Website compatibility
-
-The **Website compatibility** GitHub Actions workflow runs `mise run smoke` daily at 06:23 UTC, on pushes to `main`, and on manual dispatch. Failed runs use normal GitHub Actions notifications; no issue bot or extra service is needed. The offline CI gate stays independent of website availability.
-
-The same check exercises every portfolio command in text and both JSON option positions, reads the newest article as Markdown, and launches the real MCP stdio bridge. It discovers the remote tools, resources, templates, and prompts; calls every advertised read-only tool, including article reading with a live slug and the hosting calculator with its defaults; reads resources; and retrieves prompts. The SDK validates tool results against the website's current schemas, and the profile resource is checked against the CLI's rendering contract. API and MCP failures are reported independently. Checks use live data, not snapshots of portfolio facts.
-
-After a website deployment, run `mise run smoke` locally or dispatch the workflow:
-
-```bash
-gh workflow run compatibility.yml --repo fmind/cli
-```
-
-A failure indicates either an outage or a contract change; inspect the failing operation in the run log. Keep `PROFILE_SHAPE` limited to consumed fields and update synthetic fixtures alongside rendering changes. New MCP tools with required inputs may need a sample argument in the smoke check. No release is needed merely to add content or an unused API field.
-
-Commands exit with 0 on success, 1 for website or article-resolution failures, and 2 for invalid CLI usage.
-
 ## License
 
 [MIT](LICENSE) — © 2026 Médéric Hurier (Fmind).

{fmind-2.0.1 → fmind-2.0.3}/README.md

@@ -6,14 +6,6 @@ Read [Médéric Hurier's (Fmind)](https://www.fmind.dev/) portfolio from the ter
 uvx fmind whoami
 ```
 
-## Why it stays small
-
-Every command renders a document the website already publishes — the portfolio at [`/api/profile`](https://www.fmind.dev/api/profile) and, for `fmind read`, the Markdown source of an article at `/articles/<slug>.md`. Those are the same sources behind the site, the Atom feed, `llms.txt` and the MCP server.
-
-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.
-
 ## Commands
 
 | Command                                     | Shows                                             |
@@ -50,7 +42,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')"
@@ -134,22 +126,6 @@ The pre-commit hook runs checks without changing or staging files; run `mise run
 
 A release tag must match the version in `pyproject.toml` (for example, `v0.1.0`). CD runs the same full gate for that tag and checks the live commands before publishing through PyPI Trusted Publishing. The live smoke check is a release check, not a pull-request gate.
 
-### Website compatibility
-
-The **Website compatibility** GitHub Actions workflow runs `mise run smoke` daily at 06:23 UTC, on pushes to `main`, and on manual dispatch. Failed runs use normal GitHub Actions notifications; no issue bot or extra service is needed. The offline CI gate stays independent of website availability.
-
-The same check exercises every portfolio command in text and both JSON option positions, reads the newest article as Markdown, and launches the real MCP stdio bridge. It discovers the remote tools, resources, templates, and prompts; calls every advertised read-only tool, including article reading with a live slug and the hosting calculator with its defaults; reads resources; and retrieves prompts. The SDK validates tool results against the website's current schemas, and the profile resource is checked against the CLI's rendering contract. API and MCP failures are reported independently. Checks use live data, not snapshots of portfolio facts.
-
-After a website deployment, run `mise run smoke` locally or dispatch the workflow:
-
-```bash
-gh workflow run compatibility.yml --repo fmind/cli
-```
-
-A failure indicates either an outage or a contract change; inspect the failing operation in the run log. Keep `PROFILE_SHAPE` limited to consumed fields and update synthetic fixtures alongside rendering changes. New MCP tools with required inputs may need a sample argument in the smoke check. No release is needed merely to add content or an unused API field.
-
-Commands exit with 0 on success, 1 for website or article-resolution failures, and 2 for invalid CLI usage.
-
 ## License
 
 [MIT](LICENSE) — © 2026 Médéric Hurier (Fmind).

{fmind-2.0.1 → fmind-2.0.3}/pyproject.toml

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

{fmind-2.0.1 → fmind-2.0.3}/pyproject.toml.orig

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

{fmind-2.0.1 → fmind-2.0.3}/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:
@@ -119,12 +158,32 @@ def _validate(value: object, shape: object, path: str) -> None:
         raise FmindError(f"the profile endpoint returned an invalid portfolio document at {path}")
 
 
+def _reject_constant(name: str) -> None:
+    """Refuse NaN and Infinity: they are not JSON, so `--json` could not forward them."""
+    raise ValueError(name)
+
+
 def _parse_profile(payload: bytes) -> dict[str, Any]:
     """Decode the portfolio document, rejecting anything that is not one."""
     try:
-        document = json.loads(payload)
+        document = json.loads(payload, parse_constant=_reject_constant)
     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.1 → fmind-2.0.3}/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:
@@ -109,7 +116,10 @@ def _write(text: str) -> None:
 def _emit(ctx: typer.Context, body: RenderableType, payload: Any, *, as_json: bool, page: bool = False) -> None:
     """Print either the rendered section or its JSON data."""
     if as_json or ctx.find_root().params["as_json"]:
-        _write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+        # json.dumps escapes C0 controls but not DEL or C1 (such as CSI); fields the
+        # renderer does not validate still reach the terminal, so escape those too.
+        text = json.dumps(payload, ensure_ascii=False, indent=2)
+        _write(CONTROL_PATTERN.sub(lambda match: f"\\u{ord(match.group()):04x}", text) + "\n")
         return
     out = _console(ctx)
     if not out.is_terminal:
@@ -119,8 +129,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()