fmind 2.0.4__tar.gz → 2.0.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fmind
3
- Version: 2.0.4
3
+ Version: 2.0.5
4
4
  Summary: Read Médéric Hurier's (Fmind) portfolio from the terminal.
5
5
  Keywords: portfolio,cli,fmind,resume,articles
6
6
  Author: Médéric Hurier
@@ -33,22 +33,22 @@ uvx fmind whoami
33
33
 
34
34
  ## Commands
35
35
 
36
- | Command | Shows |
37
- | ------------------------------------------- | ------------------------------------------------- |
38
- | `fmind` | The `whoami` card and a pointer to `--help` |
39
- | `fmind whoami` | Name, featured experience, availability, contact |
40
- | `fmind about` | The biography |
41
- | `fmind skills` | Core expertise, as published on the site |
42
- | `fmind experiences` | Engagements in website order |
43
- | `fmind community` | Ambassador and advisory roles |
44
- | `fmind certifications` | Certifications, the PhD, specializations |
45
- | `fmind papers` | The doctorate and the peer-reviewed publications |
46
- | `fmind projects [--limit 6]` | Open-source repositories and video series |
47
- | `fmind sites` | Interactive tools published alongside the writing |
48
- | `fmind articles [--limit 6]` | The most recent writing |
49
- | `fmind search [query] [--tag] [--limit 10]` | Articles matching every term, newest first |
50
- | `fmind read <slug> [--raw]` | One article, rendered in the terminal |
51
- | `fmind hire` | What can be booked right now |
36
+ | Command | Shows |
37
+ | ---------------------------------------------- | ------------------------------------------------- |
38
+ | `fmind` | The `whoami` card and a pointer to `--help` |
39
+ | `fmind whoami` | Name, featured experience, availability, contact |
40
+ | `fmind about` | The biography |
41
+ | `fmind skills` | Core expertise, as published on the site |
42
+ | `fmind experiences` | Engagements in website order |
43
+ | `fmind community` | Ambassador and advisory roles |
44
+ | `fmind certifications` | Certifications, the PhD, specializations |
45
+ | `fmind papers` | The doctorate and the peer-reviewed publications |
46
+ | `fmind projects [--limit 6]` | Open-source repositories and video series |
47
+ | `fmind sites` | Interactive tools published alongside the writing |
48
+ | `fmind articles [--limit 6]` | The most recent writing |
49
+ | `fmind search [query...] [--tag] [--limit 10]` | Articles matching every term, newest first |
50
+ | `fmind read <slug> [--raw]` | One article, rendered in the terminal |
51
+ | `fmind hire` | What can be booked right now |
52
52
 
53
53
  The commands group sections of the website's profile API. Their names stay stable when the website's navigation or visual design changes.
54
54
 
@@ -60,14 +60,14 @@ Output uses your terminal's default text colour and blue accent. Community roles
60
60
 
61
61
  ### Reading
62
62
 
63
- `fmind search` matches titles, summaries, tags and slugs; terms are ANDed, so each extra word narrows the result. `--tag` restricts to one of the site's own tags, case-insensitively; an unknown tag fails and lists the published ones.
63
+ `fmind search` matches titles, summaries, tags and slugs; terms are ANDed, so each extra word narrows the result, with or without quotes. `--tag` restricts to one of the site's own tags, case-insensitively; an unknown tag fails and lists the published ones.
64
64
 
65
65
  ```bash
66
- fmind search "agent security"
66
+ fmind search agent security
67
67
  fmind search --tag MLOps --limit 3
68
68
  ```
69
69
 
70
- `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.
70
+ `fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. In an interactive terminal whose `TERM` your system's terminfo database knows (not `dumb`), it pages through `$PAGER` (default `less`, with `LESS=FRX` unless you set `LESS`), so short articles print directly; `PAGER=cat` disables paging. A missing or unparsable `PAGER` is skipped and the article prints directly; if the pager fails to launch or exits unsuccessfully, the command reports an error; retry with `PAGER=cat`. Use `--raw` for the Markdown source.
71
71
 
72
72
  ```bash
73
73
  slug="$(fmind articles --limit 1 --json | jq -r '.[0].slug')"
@@ -129,7 +129,7 @@ For a host that accepts JSON configuration:
129
129
  }
130
130
  ```
131
131
 
132
- `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.
132
+ `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. A request that exceeds these bounds or loses its connection fails on its own, and the bridge keeps serving.
133
133
 
134
134
  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.
135
135
 
@@ -141,15 +141,16 @@ From this checkout, run `uv run --extra mcp fmind mcp`. The optional extra uses
141
141
  mise install # install the pinned toolchain
142
142
  mise run install # sync the locked environment and install hooks
143
143
  mise run format # ruff imports and format, dprint
144
- mise run check # ruff, ty, actionlint, zizmor, gitleaks, dependency audit
144
+ mise run check # lockfile, ruff, ty, dprint, jactionlint, betterleaks, dependency audit
145
145
  mise run test # offline pytest with branch coverage
146
146
  mise run smoke # exercise every command against the live site
147
+ mise run build # build the wheel and source distribution
147
148
  mise run all # format, check, test, build — the gate CI runs
148
149
  ```
149
150
 
150
- The pre-commit hook runs checks without changing or staging files; run `mise run format` before committing. The pre-push hook runs the offline tests. CI runs the full gate on the pinned Python, tests Python 3.11–3.14 for compatibility, and tests the declared dependency floors with `--resolution lowest-direct` on Python 3.11.
151
+ The pre-commit hook formats staged files and runs the offline checks (`mise run check:local`). The pre-push hook runs the dependency audit (`mise run check:network`) and the offline tests. CI runs the full gate on the pinned Python, tests Python 3.11–3.15 for compatibility, and tests the declared dependency floors with `--resolution lowest-direct` on Python 3.11.
151
152
 
152
- 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.
153
+ A release tag must match the version in `pyproject.toml` (for example, `v0.1.0`). CD reruns every CI job for that tag (the gate, the Python versions, and the dependency floors) and checks the live commands before publishing through PyPI Trusted Publishing. The live smoke check is a release check, not a pull-request gate.
153
154
 
154
155
  ## License
155
156
 
@@ -8,22 +8,22 @@ uvx fmind whoami
8
8
 
9
9
  ## Commands
10
10
 
11
- | Command | Shows |
12
- | ------------------------------------------- | ------------------------------------------------- |
13
- | `fmind` | The `whoami` card and a pointer to `--help` |
14
- | `fmind whoami` | Name, featured experience, availability, contact |
15
- | `fmind about` | The biography |
16
- | `fmind skills` | Core expertise, as published on the site |
17
- | `fmind experiences` | Engagements in website order |
18
- | `fmind community` | Ambassador and advisory roles |
19
- | `fmind certifications` | Certifications, the PhD, specializations |
20
- | `fmind papers` | The doctorate and the peer-reviewed publications |
21
- | `fmind projects [--limit 6]` | Open-source repositories and video series |
22
- | `fmind sites` | Interactive tools published alongside the writing |
23
- | `fmind articles [--limit 6]` | The most recent writing |
24
- | `fmind search [query] [--tag] [--limit 10]` | Articles matching every term, newest first |
25
- | `fmind read <slug> [--raw]` | One article, rendered in the terminal |
26
- | `fmind hire` | What can be booked right now |
11
+ | Command | Shows |
12
+ | ---------------------------------------------- | ------------------------------------------------- |
13
+ | `fmind` | The `whoami` card and a pointer to `--help` |
14
+ | `fmind whoami` | Name, featured experience, availability, contact |
15
+ | `fmind about` | The biography |
16
+ | `fmind skills` | Core expertise, as published on the site |
17
+ | `fmind experiences` | Engagements in website order |
18
+ | `fmind community` | Ambassador and advisory roles |
19
+ | `fmind certifications` | Certifications, the PhD, specializations |
20
+ | `fmind papers` | The doctorate and the peer-reviewed publications |
21
+ | `fmind projects [--limit 6]` | Open-source repositories and video series |
22
+ | `fmind sites` | Interactive tools published alongside the writing |
23
+ | `fmind articles [--limit 6]` | The most recent writing |
24
+ | `fmind search [query...] [--tag] [--limit 10]` | Articles matching every term, newest first |
25
+ | `fmind read <slug> [--raw]` | One article, rendered in the terminal |
26
+ | `fmind hire` | What can be booked right now |
27
27
 
28
28
  The commands group sections of the website's profile API. Their names stay stable when the website's navigation or visual design changes.
29
29
 
@@ -35,14 +35,14 @@ Output uses your terminal's default text colour and blue accent. Community roles
35
35
 
36
36
  ### Reading
37
37
 
38
- `fmind search` matches titles, summaries, tags and slugs; terms are ANDed, so each extra word narrows the result. `--tag` restricts to one of the site's own tags, case-insensitively; an unknown tag fails and lists the published ones.
38
+ `fmind search` matches titles, summaries, tags and slugs; terms are ANDed, so each extra word narrows the result, with or without quotes. `--tag` restricts to one of the site's own tags, case-insensitively; an unknown tag fails and lists the published ones.
39
39
 
40
40
  ```bash
41
- fmind search "agent security"
41
+ fmind search agent security
42
42
  fmind search --tag MLOps --limit 3
43
43
  ```
44
44
 
45
- `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.
45
+ `fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. In an interactive terminal whose `TERM` your system's terminfo database knows (not `dumb`), it pages through `$PAGER` (default `less`, with `LESS=FRX` unless you set `LESS`), so short articles print directly; `PAGER=cat` disables paging. A missing or unparsable `PAGER` is skipped and the article prints directly; if the pager fails to launch or exits unsuccessfully, the command reports an error; retry with `PAGER=cat`. Use `--raw` for the Markdown source.
46
46
 
47
47
  ```bash
48
48
  slug="$(fmind articles --limit 1 --json | jq -r '.[0].slug')"
@@ -104,7 +104,7 @@ For a host that accepts JSON configuration:
104
104
  }
105
105
  ```
106
106
 
107
- `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.
107
+ `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. A request that exceeds these bounds or loses its connection fails on its own, and the bridge keeps serving.
108
108
 
109
109
  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.
110
110
 
@@ -116,15 +116,16 @@ From this checkout, run `uv run --extra mcp fmind mcp`. The optional extra uses
116
116
  mise install # install the pinned toolchain
117
117
  mise run install # sync the locked environment and install hooks
118
118
  mise run format # ruff imports and format, dprint
119
- mise run check # ruff, ty, actionlint, zizmor, gitleaks, dependency audit
119
+ mise run check # lockfile, ruff, ty, dprint, jactionlint, betterleaks, dependency audit
120
120
  mise run test # offline pytest with branch coverage
121
121
  mise run smoke # exercise every command against the live site
122
+ mise run build # build the wheel and source distribution
122
123
  mise run all # format, check, test, build — the gate CI runs
123
124
  ```
124
125
 
125
- The pre-commit hook runs checks without changing or staging files; run `mise run format` before committing. The pre-push hook runs the offline tests. CI runs the full gate on the pinned Python, tests Python 3.11–3.14 for compatibility, and tests the declared dependency floors with `--resolution lowest-direct` on Python 3.11.
126
+ The pre-commit hook formats staged files and runs the offline checks (`mise run check:local`). The pre-push hook runs the dependency audit (`mise run check:network`) and the offline tests. CI runs the full gate on the pinned Python, tests Python 3.11–3.15 for compatibility, and tests the declared dependency floors with `--resolution lowest-direct` on Python 3.11.
126
127
 
127
- 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.
128
+ A release tag must match the version in `pyproject.toml` (for example, `v0.1.0`). CD reruns every CI job for that tag (the gate, the Python versions, and the dependency floors) and checks the live commands before publishing through PyPI Trusted Publishing. The live smoke check is a release check, not a pull-request gate.
128
129
 
129
130
  ## License
130
131
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "fmind"
3
- version = "2.0.4"
3
+ version = "2.0.5"
4
4
  description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -74,10 +74,23 @@ select = [
74
74
  "S",
75
75
  "SIM",
76
76
  "RUF",
77
+ "TID",
78
+ ]
79
+
80
+ [tool.ruff.lint.flake8-tidy-imports]
81
+ banned-module-level-imports = [
82
+ "fmind.mcp",
83
+ "httpx2",
84
+ "mcp",
85
+ "mcp_types",
77
86
  ]
78
87
 
79
88
  [tool.ruff.lint.per-file-ignores]
80
- "tests/**" = ["S101"]
89
+ "src/fmind/mcp.py" = ["TID253"]
90
+ "tests/**" = [
91
+ "S101",
92
+ "TID253",
93
+ ]
81
94
 
82
95
  [tool.ruff.format]
83
96
  docstring-code-format = true
@@ -1,7 +1,7 @@
1
1
  # https://packaging.python.org/en/latest/specifications/pyproject-toml/
2
2
  [project]
3
3
  name = "fmind"
4
- version = "2.0.4"
4
+ version = "2.0.5"
5
5
  description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
6
6
  readme = "README.md"
7
7
  license = "MIT"
@@ -52,9 +52,13 @@ module-root = "src"
52
52
  line-length = 120
53
53
  target-version = "py311"
54
54
  [tool.ruff.lint]
55
- select = ["E", "F", "I", "N", "UP", "B", "S", "SIM", "RUF"]
55
+ select = ["E", "F", "I", "N", "UP", "B", "S", "SIM", "RUF", "TID"]
56
+ [tool.ruff.lint.flake8-tidy-imports]
57
+ # Portfolio commands run without the optional `mcp` extra; only the bridge loads it.
58
+ banned-module-level-imports = ["fmind.mcp", "httpx2", "mcp", "mcp_types"]
56
59
  [tool.ruff.lint.per-file-ignores]
57
- "tests/**" = ["S101"] # assertions are the point of a test
60
+ "src/fmind/mcp.py" = ["TID253"] # the bridge is the extra's only importer
61
+ "tests/**" = ["S101", "TID253"] # assertions are the point of a test; tests install every extra
58
62
  [tool.ruff.format]
59
63
  docstring-code-format = true
60
64
 
@@ -21,6 +21,9 @@ PROFILE_URL = "https://www.fmind.dev/api/profile"
21
21
  TIMEOUT_SECONDS = 15.0
22
22
  # Bound memory use even when the origin serves an unexpected document.
23
23
  MAX_BYTES = 8 * 1024 * 1024
24
+ # `--json` re-indents forwarded fields, so output grows with the square of their
25
+ # nesting; the published profile nests four levels.
26
+ MAX_DEPTH = 32
24
27
  USER_AGENT = f"fmind/{__version__} (+https://github.com/fmind/cli)"
25
28
  # Slugs reach a URL, so only the shape the site actually mints is accepted.
26
29
  SLUG_PATTERN = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*\Z")
@@ -178,9 +181,11 @@ def _parse_profile(payload: bytes) -> dict[str, Any]:
178
181
  # Check keys and future fields too: JSON output forwards them even when the
179
182
  # renderer does not consume them. The decoder accepts surrogates and can turn
180
183
  # finite JSON literals such as 1e999 into infinity.
181
- pending = [document]
184
+ pending = [(document, 0)]
182
185
  while pending:
183
- value = pending.pop()
186
+ value, depth = pending.pop()
187
+ if depth > MAX_DEPTH:
188
+ raise FmindError(f"the profile endpoint returned a portfolio document nested over {MAX_DEPTH} levels")
184
189
  if isinstance(value, float) and not math.isfinite(value):
185
190
  raise FmindError("the profile endpoint returned a non-finite number")
186
191
  if isinstance(value, str):
@@ -189,10 +194,9 @@ def _parse_profile(payload: bytes) -> dict[str, Any]:
189
194
  except UnicodeEncodeError as error:
190
195
  raise FmindError("the profile endpoint returned invalid Unicode") from error
191
196
  elif isinstance(value, dict):
192
- pending.extend(value)
193
- pending.extend(value.values())
197
+ pending.extend((item, depth + 1) for item in (*value, *value.values()))
194
198
  elif isinstance(value, list):
195
- pending.extend(value)
199
+ pending.extend((item, depth + 1) for item in value)
196
200
  _validate(document, PROFILE_SHAPE, "profile")
197
201
  links = document["thesis"].get("links")
198
202
  if links is not None:
@@ -3,13 +3,14 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import asyncio
6
+ import contextlib
6
7
  import json
7
8
  import os
8
9
  import shlex
9
10
  import shutil
10
11
  import subprocess
11
12
  import sys
12
- from typing import Annotated, Any
13
+ from typing import IO, Annotated, Any, cast
13
14
 
14
15
  import typer
15
16
  from rich.console import Console, RenderableType
@@ -82,17 +83,52 @@ class _SystemPager(Pager):
82
83
  # Like Git: respect an explicit LESS, otherwise keep colours (-R), skip
83
84
  # paging for short output (-F), and leave the text on screen (-X).
84
85
  environment = {**os.environ, "LESS": os.environ.get("LESS", "FRX")}
86
+ message = "could not display the article with PAGER; check PAGER or use PAGER=cat"
85
87
  try:
86
- subprocess.run( # noqa: S603
87
- self.command, input=content.encode(), env=environment, stderr=subprocess.DEVNULL, check=True
88
- )
89
- except (OSError, subprocess.CalledProcessError) as error:
90
- raise FmindError("could not display the article with PAGER; check PAGER or use PAGER=cat") from error
88
+ process = subprocess.Popen(self.command, stdin=subprocess.PIPE, stderr=subprocess.DEVNULL, env=environment) # noqa: S603
89
+ except OSError as error:
90
+ raise FmindError(message) from error
91
+ # Like the standard library's pager: Ctrl-C belongs to the pager. subprocess.run
92
+ # would kill it, leaving the terminal in raw mode, so wait for it to quit instead.
93
+ # Ctrl-C drops the unwritten rest, and a pager that quits early closes the pipe.
94
+ with (
95
+ contextlib.suppress(OSError),
96
+ cast("IO[bytes]", process.stdin) as pipe,
97
+ contextlib.suppress(KeyboardInterrupt),
98
+ ):
99
+ pipe.write(content.encode())
100
+ while True:
101
+ try:
102
+ code = process.wait()
103
+ break
104
+ except KeyboardInterrupt:
105
+ pass
106
+ if code != 0:
107
+ raise FmindError(message)
108
+
109
+
110
+ def _full_screen_terminal() -> bool:
111
+ """Whether TERM describes a terminal that a full-screen pager can drive."""
112
+ # Otherwise less stops at a "terminal is not fully functional" prompt that the
113
+ # hidden stderr turns into a blank screen: TERM unset or dumb, or missing from
114
+ # terminfo (TERM=xterm-kitty over SSH). setupterm also rejects generic and
115
+ # hardcopy entries such as `unknown`.
116
+ if os.environ.get("TERM", "") in {"", "dumb"}:
117
+ return False
118
+ try:
119
+ import curses # only the pager needs it, and Windows lacks it
120
+ except ImportError:
121
+ return True
122
+ try:
123
+ curses.setupterm()
124
+ except curses.error:
125
+ return False
126
+ return True
91
127
 
92
128
 
93
129
  def _pager_command() -> list[str] | None:
94
130
  """Return the pager for an interactive terminal, or None to print directly."""
95
- if not (sys.stdin.isatty() and sys.stdout.isatty()) or os.environ.get("TERM") == "dumb":
131
+ if not (sys.stdin.isatty() and sys.stdout.isatty() and _full_screen_terminal()):
96
132
  return None
97
133
  try:
98
134
  command = shlex.split(os.environ.get("PAGER", "less"))
@@ -122,16 +158,16 @@ def _emit(ctx: typer.Context, body: RenderableType, payload: Any, *, as_json: bo
122
158
  _write(CONTROL_PATTERN.sub(lambda match: f"\\u{ord(match.group()):04x}", text) + "\n")
123
159
  return
124
160
  out = _console(ctx)
125
- if not out.is_terminal:
126
- out.print(render.Trimmed(body), crop=False)
127
- return
128
- command = _pager_command() if page else None
161
+ # Trim on terminals too: forced colour (--color, FORCE_COLOR) makes Rich treat a
162
+ # pipe or file as a terminal, and line-end padding is invisible on a real one.
163
+ trimmed = render.Trimmed(body)
164
+ command = _pager_command() if page and out.is_terminal else None
129
165
  if command is None:
130
- out.print(body, crop=False)
166
+ out.print(trimmed, crop=False)
131
167
  return
132
168
  try:
133
169
  with out.pager(pager=_SystemPager(command), styles=True):
134
- out.print(body, crop=False)
170
+ out.print(trimmed, crop=False)
135
171
  except FmindError as error:
136
172
  raise _fail(str(error)) from error
137
173
 
@@ -226,8 +262,11 @@ def list_articles(ctx: typer.Context, limit: LimitOption = 6, as_json: JsonOptio
226
262
  @app.command()
227
263
  def search(
228
264
  ctx: typer.Context,
229
- # Optional, so filtering by tag alone needs no empty positional argument.
230
- query: Annotated[str, typer.Argument(help="Terms to match against titles, summaries, tags and slugs.")] = "",
265
+ # Optional, so filtering by tag alone needs no empty positional argument; several
266
+ # words need no quotes, so the hint printed by `read` runs as written.
267
+ query: Annotated[
268
+ list[str] | None, typer.Argument(help="Terms to match against titles, summaries, tags and slugs.")
269
+ ] = None,
231
270
  tag: Annotated[str | None, typer.Option("--tag", help="Restrict to one of the site's tags, such as Agent.")] = None,
232
271
  limit: LimitOption = 10,
233
272
  as_json: JsonOption = False,
@@ -238,7 +277,7 @@ def search(
238
277
  names = [entry["name"] for entry in doc["tags"]]
239
278
  if tag.lower() not in {name.lower() for name in names}:
240
279
  raise _fail(f"unknown tag {tag!r}; choose one of: {', '.join(names)}")
241
- found = articles.search(doc["articles"], query, tag=tag, limit=limit)
280
+ found = articles.search(doc["articles"], " ".join(query or []), tag=tag, limit=limit)
242
281
  footer = f"{len(found)} shown · {len(doc['articles'])} published · fmind read <slug> opens one"
243
282
  _emit(ctx, render.articles(found, footer=footer), found, as_json=as_json)
244
283
 
@@ -254,7 +293,8 @@ def read(
254
293
  doc = _doc()
255
294
  matches = articles.candidates(doc["articles"], slug.strip().lower())
256
295
  if not matches:
257
- raise _fail(f"no article matches {slug!r} — try: fmind search {slug}")
296
+ # Quote only what the shell would split or expand, so the hint runs as printed.
297
+ raise _fail(f"no article matches {slug!r} — try: fmind {shlex.join(['search', *slug.split()])}")
258
298
  if len(matches) > 1:
259
299
  listed = ", ".join(matches[:10])
260
300
  raise _fail(f"{slug!r} matches {len(matches)} articles: {listed}")
@@ -267,7 +307,8 @@ def read(
267
307
  if raw and not (as_json or ctx.find_root().params["as_json"]):
268
308
  _write(markdown)
269
309
  return
270
- payload = {"slug": resolved, "markdown": markdown, **(post or {})}
310
+ # The fetched article wins over any same-named field in the index entry.
311
+ payload = {**(post or {}), "slug": resolved, "markdown": markdown}
271
312
  _emit(ctx, render.article_body(markdown), payload, as_json=as_json, page=True)
272
313
 
273
314
 
@@ -20,6 +20,14 @@ from fmind import __version__
20
20
  from fmind.api import MAX_BYTES, TIMEOUT_SECONDS, USER_AGENT, FmindError, origin_url
21
21
 
22
22
 
23
+ class _ResponseError(httpx2.StreamError):
24
+ """A remote response broke a bound or the connection mid-body.
25
+
26
+ The SDK turns a stream error into one JSON-RPC error for that request; any
27
+ other exception escapes its transport task group and ends the whole bridge.
28
+ """
29
+
30
+
23
31
  class _BoundedStream(httpx2.AsyncByteStream):
24
32
  def __init__(self, stream: httpx2.AsyncByteStream, deadline: float) -> None:
25
33
  self.stream = stream
@@ -32,10 +40,12 @@ class _BoundedStream(httpx2.AsyncByteStream):
32
40
  async for chunk in self.stream:
33
41
  size += len(chunk)
34
42
  if size > MAX_BYTES:
35
- raise FmindError("the remote MCP response exceeded the size limit")
43
+ raise _ResponseError("the remote MCP response exceeded the size limit")
36
44
  yield chunk
37
45
  except TimeoutError as error:
38
- raise httpx2.ReadTimeout("the remote MCP response exceeded its deadline") from error
46
+ raise _ResponseError("the remote MCP response exceeded its deadline") from error
47
+ except httpx2.TransportError as error:
48
+ raise _ResponseError("the remote MCP response was interrupted") from error
39
49
 
40
50
  async def aclose(self) -> None:
41
51
  await self.stream.aclose()
@@ -45,15 +55,20 @@ class _BoundedTransport(httpx2.AsyncHTTPTransport):
45
55
  async def handle_async_request(self, request: httpx2.Request) -> httpx2.Response:
46
56
  # HTTPX read timeouts restart for every chunk. A legacy MCP server may
47
57
  # ignore cancellation, so bound the entire HTTP exchange independently.
58
+ # Failures become gateway statuses: the SDK answers those with one
59
+ # JSON-RPC error, while a raised exception would end the whole bridge.
48
60
  deadline = asyncio.get_running_loop().time() + TIMEOUT_SECONDS
49
61
  try:
50
62
  async with asyncio.timeout_at(deadline):
51
63
  response = await super().handle_async_request(request)
52
- except TimeoutError as error:
53
- raise httpx2.ReadTimeout("the remote MCP response exceeded its deadline", request=request) from error
64
+ except TimeoutError:
65
+ return httpx2.Response(504, request=request)
66
+ except httpx2.TransportError:
67
+ return httpx2.Response(502, request=request)
54
68
  if response.headers.get("content-encoding", "identity") != "identity":
69
+ # The client asks for identity, so a compressed body is a broken upstream.
55
70
  await response.aclose()
56
- raise FmindError("the remote MCP server ignored the uncompressed response requirement")
71
+ return httpx2.Response(502, request=request)
57
72
  if not isinstance(response.stream, httpx2.AsyncByteStream):
58
73
  raise FmindError("the remote MCP transport returned an invalid stream")
59
74
  response.stream = _BoundedStream(response.stream, deadline)
@@ -103,6 +118,7 @@ async def serve() -> None:
103
118
  endpoint = origin_url("/mcp")
104
119
  # Protocol failures carry safe messages; SDK HTTP diagnostics can contain URLs.
105
120
  logging.getLogger("mcp").setLevel(logging.CRITICAL)
121
+ connected = False
106
122
  try:
107
123
  async with (
108
124
  httpx2.AsyncClient(
@@ -118,7 +134,12 @@ async def serve() -> None:
118
134
  stdio_server() as (reader, writer),
119
135
  ):
120
136
  server = create_bridge(remote)
137
+ connected = True
121
138
  await server.run(reader, writer, server.create_initialization_options())
122
139
  except Exception as error:
140
+ # After connecting, upstream failures are per-request JSON-RPC errors, so what
141
+ # remains (such as a host closing stdio) must not blame the remote server.
142
+ if connected:
143
+ raise FmindError("the MCP bridge stopped unexpectedly after connecting") from error
123
144
  message = "could not connect to the remote MCP server; check your connection and FMIND_PROFILE_URL"
124
145
  raise FmindError(message) from error
@@ -2,7 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from collections.abc import Iterable
5
+ from collections.abc import Iterable, Sequence
6
6
  from typing import Any
7
7
 
8
8
  from rich.console import Console, ConsoleOptions, Group, RenderableType, RenderResult
@@ -62,6 +62,11 @@ def _entry(*lines: RenderableType) -> Group:
62
62
  return Group(*lines, Text())
63
63
 
64
64
 
65
+ def _listing(blocks: Sequence[RenderableType], empty: str) -> RenderableType:
66
+ """The entries, or one line saying so when the website publishes none."""
67
+ return Group(*blocks) if blocks else Text(empty)
68
+
69
+
65
70
  def _rows(pairs: list[tuple[str, RenderableType]]) -> Table:
66
71
  """Lay out aligned key/value rows without visible borders."""
67
72
  table = Table.grid(padding=(0, 2))
@@ -113,37 +118,36 @@ def about(doc: dict[str, Any]) -> RenderableType:
113
118
 
114
119
  def skills(doc: dict[str, Any]) -> RenderableType:
115
120
  """Show expertise without inventing command-line options or local labels."""
116
- return Group(*(_entry(Text(card["title"], style="bold"), Text(card["description"])) for card in doc["expertise"]))
121
+ blocks = [_entry(Text(card["title"], style="bold"), Text(card["description"])) for card in doc["expertise"]]
122
+ return _listing(blocks, "no expertise published")
117
123
 
118
124
 
119
125
  def experiences(doc: dict[str, Any]) -> RenderableType:
120
126
  """Engagements in the order published by the website."""
121
- return Group(
122
- *(
123
- _entry(
124
- Text(job["company"].upper(), style=ACCENT),
125
- Text(job["title"], style="bold"),
126
- Text(job["description"]),
127
- Text(" ".join(job["tags"])),
128
- )
129
- for job in doc["experience"]
127
+ blocks = [
128
+ _entry(
129
+ Text(job["company"].upper(), style=ACCENT),
130
+ Text(job["title"], style="bold"),
131
+ Text(job["description"]),
132
+ Text(" ".join(job["tags"])),
130
133
  )
131
- )
134
+ for job in doc["experience"]
135
+ ]
136
+ return _listing(blocks, "no experience published")
132
137
 
133
138
 
134
139
  def community(doc: dict[str, Any]) -> RenderableType:
135
140
  """Ambassador and advisory roles, with their published links."""
136
- return Group(
137
- *(
138
- _entry(
139
- Text(role["organization"], style=ACCENT),
140
- Text(role["role"], style="bold"),
141
- Text(role["description"]),
142
- _link(role["url"]),
143
- )
144
- for role in doc["leadership"]
141
+ blocks = [
142
+ _entry(
143
+ Text(role["organization"], style=ACCENT),
144
+ Text(role["role"], style="bold"),
145
+ Text(role["description"]),
146
+ _link(role["url"]),
145
147
  )
146
- )
148
+ for role in doc["leadership"]
149
+ ]
150
+ return _listing(blocks, "no community role published")
147
151
 
148
152
 
149
153
  def certifications(doc: dict[str, Any]) -> RenderableType:
@@ -180,7 +184,7 @@ def projects(doc: dict[str, Any], *, limit: int = 6) -> RenderableType:
180
184
  blocks += [
181
185
  _entry(Text(video["title"], style="bold"), Text(video["description"]), _link(video["url"])) for video in series
182
186
  ]
183
- return Group(*blocks)
187
+ return _listing(blocks, "no project published")
184
188
 
185
189
 
186
190
  def articles(posts: list[dict[str, Any]], *, footer: str = "") -> RenderableType:
@@ -242,19 +246,18 @@ def sites(doc: dict[str, Any]) -> RenderableType:
242
246
  )
243
247
  for page in doc["site_pages"]
244
248
  ]
245
- return Group(*blocks) if blocks else Text("no interactive site published")
249
+ return _listing(blocks, "no interactive site published")
246
250
 
247
251
 
248
252
  def hire(doc: dict[str, Any]) -> RenderableType:
249
253
  """What can be booked right now."""
250
- return Group(
251
- *(
252
- _entry(
253
- Text(service["title"], style="bold"),
254
- Text(service["description"]),
255
- Text(service["badge"], style="bold"),
256
- _link(service["cta_url"]),
257
- )
258
- for service in doc["services"]
254
+ blocks = [
255
+ _entry(
256
+ Text(service["title"], style="bold"),
257
+ Text(service["description"]),
258
+ Text(service["badge"], style="bold"),
259
+ _link(service["cta_url"]),
259
260
  )
260
- )
261
+ for service in doc["services"]
262
+ ]
263
+ return _listing(blocks, "no service published")
File without changes
File without changes
File without changes
File without changes