fmind 3.0.2__tar.gz → 3.0.3__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: 3.0.2
3
+ Version: 3.0.3
4
4
  Summary: Read Médéric Hurier's (Fmind) portfolio and daily news from the terminal.
5
5
  Keywords: portfolio,cli,fmind,resume,articles,news,mcp
6
6
  Author: Médéric Hurier
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "fmind"
3
- version = "3.0.2"
3
+ version = "3.0.3"
4
4
  description = "Read Médéric Hurier's (Fmind) portfolio and daily news from the terminal."
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -65,10 +65,6 @@ dev = [
65
65
  requires = ["uv_build>=0.13.9,<0.14"]
66
66
  build-backend = "uv_build"
67
67
 
68
- [tool.uv.build-backend]
69
- module-name = "fmind"
70
- module-root = "src"
71
-
72
68
  [tool.ruff]
73
69
  line-length = 120
74
70
  extend-exclude = ["*.md"]
@@ -137,6 +133,8 @@ known_first_party = ["fmind"]
137
133
 
138
134
  [tool.ty.rules]
139
135
  blanket-ignore-comment = "error"
136
+ unused-ignore-comment = "error"
137
+ unused-type-ignore-comment = "error"
140
138
 
141
139
  [tool.pytest]
142
140
  testpaths = ["tests"]
@@ -151,6 +149,7 @@ timeout = "60"
151
149
 
152
150
  [tool.coverage.run]
153
151
  branch = true
152
+ patch = ["subprocess"]
154
153
  source = ["fmind"]
155
154
 
156
155
  [tool.coverage.report]
@@ -1,7 +1,7 @@
1
1
  # Docs: https://packaging.python.org/en/latest/specifications/pyproject-toml/
2
2
  [project]
3
3
  name = "fmind"
4
- version = "3.0.2"
4
+ version = "3.0.3"
5
5
  description = "Read Médéric Hurier's (Fmind) portfolio and daily news from the terminal."
6
6
  readme = "README.md"
7
7
  license = "MIT"
@@ -53,10 +53,6 @@ dev = [
53
53
  requires = ["uv_build>=0.13.9,<0.14"]
54
54
  build-backend = "uv_build"
55
55
 
56
- [tool.uv.build-backend]
57
- module-name = "fmind"
58
- module-root = "src"
59
-
60
56
  [tool.ruff]
61
57
  line-length = 120
62
58
  extend-exclude = ["*.md"] # dprint owns Markdown, including its Python blocks
@@ -116,6 +112,8 @@ known_first_party = ["fmind"]
116
112
 
117
113
  [tool.ty.rules]
118
114
  blanket-ignore-comment = "error"
115
+ unused-ignore-comment = "error"
116
+ unused-type-ignore-comment = "error"
119
117
 
120
118
  [tool.pytest]
121
119
  testpaths = ["tests"]
@@ -127,6 +125,7 @@ timeout = "60"
127
125
 
128
126
  [tool.coverage.run]
129
127
  branch = true
128
+ patch = ["subprocess"]
130
129
  source = ["fmind"]
131
130
 
132
131
  [tool.coverage.report]
@@ -0,0 +1,24 @@
1
+ """Read Médéric Hurier's (Fmind) portfolio and daily news from the terminal.
2
+
3
+ Every command renders live documents published by https://www.fmind.dev, so this
4
+ package carries no copy of its own and needs no release when the content changes.
5
+ """
6
+
7
+ from typing import TYPE_CHECKING
8
+
9
+ __all__ = ["__version__"]
10
+
11
+ if TYPE_CHECKING:
12
+ __version__: str
13
+
14
+
15
+ def __getattr__(name: str) -> str:
16
+ """Resolve package version lazily so importing `fmind` skips `importlib.metadata`."""
17
+ if name == "__version__":
18
+ from importlib.metadata import version
19
+
20
+ value = version("fmind")
21
+ globals()["__version__"] = value
22
+ return value
23
+ msg = f"module {__name__!r} has no attribute {name!r}"
24
+ raise AttributeError(msg)
@@ -11,9 +11,7 @@ import time
11
11
  import urllib.error
12
12
  import urllib.parse
13
13
  import urllib.request
14
- from typing import IO, Any
15
-
16
- from fmind import __version__
14
+ from typing import IO, Any, NotRequired, TypedDict, cast
17
15
 
18
16
  PROFILE_URL = "https://www.fmind.dev/api/profile"
19
17
  NEWS_PATH = "/api/news"
@@ -23,11 +21,175 @@ MAX_BYTES = 8 * 1024 * 1024
23
21
  # `--json` re-indents forwarded fields, so output grows with the square of their
24
22
  # nesting; the published profile nests four levels.
25
23
  MAX_DEPTH = 32
26
- USER_AGENT = f"fmind/{__version__} (+https://github.com/fmind/cli)"
27
24
  # Slugs reach a URL, so only the shape the site actually mints is accepted.
28
25
  SLUG_PATTERN = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*\Z")
29
- # Keep tabs, LF, and CRLF, but never let website text issue terminal commands or bare CR overwrites.
30
- CONTROL_PATTERN = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]|\r(?!\n)")
26
+ # Keep tabs, LF, and CRLF, but never let website text issue terminal commands, bare CR overwrites, or bidi spoofing.
27
+ CONTROL_PATTERN = re.compile(
28
+ r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]|\r(?!\n)"
29
+ )
30
+ _SENSITIVE_REDIRECT_HEADERS = frozenset({"authorization", "proxy-authorization", "cookie"})
31
+
32
+
33
+ class Social(TypedDict):
34
+ name: str
35
+ url: str
36
+
37
+
38
+ class Metadata(TypedDict):
39
+ name: str
40
+ alternate_name: str
41
+ job_title: str
42
+ headline_primary: str
43
+ headline_secondary: str
44
+ work_location: str
45
+ email: str
46
+ site_url: str
47
+ socials: list[Social]
48
+
49
+
50
+ class Expertise(TypedDict):
51
+ title: str
52
+ description: str
53
+
54
+
55
+ class Experience(TypedDict):
56
+ company: str
57
+ title: str
58
+ description: str
59
+ tags: list[str]
60
+
61
+
62
+ class Leadership(TypedDict):
63
+ organization: str
64
+ role: str
65
+ description: str
66
+ url: str
67
+
68
+
69
+ class Certification(TypedDict):
70
+ title: str
71
+ issuer: str
72
+ active: bool
73
+ url: str
74
+
75
+
76
+ class Specialization(TypedDict):
77
+ title: str
78
+ issuer_details: str
79
+ url: str
80
+
81
+
82
+ class ThesisLink(TypedDict):
83
+ label: str
84
+ url: str
85
+
86
+
87
+ class Thesis(TypedDict):
88
+ title: str
89
+ institution_details: str
90
+ description: str
91
+ url: str
92
+ links: NotRequired[list[ThesisLink] | None]
93
+
94
+
95
+ class Paper(TypedDict):
96
+ title: str
97
+ venue: str
98
+ url: str
99
+ code: str
100
+ code_label: str
101
+
102
+
103
+ class OpenSourceProject(TypedDict):
104
+ title: str
105
+ description: str
106
+ href: str
107
+ repo: NotRequired[str | None]
108
+
109
+
110
+ class YoutubeSeries(TypedDict):
111
+ title: str
112
+ description: str
113
+ url: str
114
+
115
+
116
+ class SitePage(TypedDict):
117
+ title: str
118
+ description: str
119
+ audience: str
120
+ url: str
121
+
122
+
123
+ class Article(TypedDict):
124
+ title: str
125
+ description: str
126
+ slug: str
127
+ date: str
128
+ tags: list[str]
129
+ reading_minutes: int
130
+
131
+
132
+ class Service(TypedDict):
133
+ title: str
134
+ description: str
135
+ badge: str
136
+ cta_url: str
137
+
138
+
139
+ class Tag(TypedDict):
140
+ name: str
141
+ description: str
142
+
143
+
144
+ class ProjectsPayload(TypedDict):
145
+ open_source: list[OpenSourceProject]
146
+ youtube_series: list[YoutubeSeries]
147
+
148
+
149
+ class Profile(TypedDict):
150
+ metadata: Metadata
151
+ biography: list[str]
152
+ expertise: list[Expertise]
153
+ experience: list[Experience]
154
+ leadership: list[Leadership]
155
+ certifications: list[Certification]
156
+ specializations: list[Specialization]
157
+ thesis: Thesis
158
+ papers: list[Paper]
159
+ open_source: list[OpenSourceProject]
160
+ youtube_series: list[YoutubeSeries]
161
+ site_pages: list[SitePage]
162
+ articles: list[Article]
163
+ services: list[Service]
164
+ tags: list[Tag]
165
+
166
+
167
+ class NewsItem(TypedDict):
168
+ title: str
169
+ url: str
170
+ domain: str
171
+ description: str
172
+
173
+
174
+ class NewsEdition(TypedDict):
175
+ slug: str
176
+ date: str
177
+ title: str
178
+ url: str
179
+ items: list[NewsItem]
180
+
181
+
182
+ class NewsArchive(TypedDict):
183
+ url: str
184
+ editions: list[NewsEdition]
185
+
186
+
187
+ def user_agent() -> str:
188
+ """Return the HTTP User-Agent string without importing package metadata at module import time."""
189
+ from fmind import __version__
190
+
191
+ return f"fmind/{__version__} (+https://github.com/fmind/cli)"
192
+
31
193
 
32
194
  # Only fields consumed by this CLI are required; new website fields pass through.
33
195
  PROFILE_SHAPE = {
@@ -189,21 +351,29 @@ class _RedirectHandler(urllib.request.HTTPRedirectHandler):
189
351
  if source.scheme == "https" and target.scheme != "https":
190
352
  fp.close()
191
353
  raise FmindError("the website redirected from HTTPS to plain HTTP")
192
- return super().redirect_request(req, fp, code, msg, headers, newurl)
354
+ redirected = super().redirect_request(req, fp, code, msg, headers, newurl)
355
+ # Drop credentials on redirects so Proxy-Authorization/Authorization/Cookie
356
+ # never leak across origins or when a redirect bypasses an authenticated proxy.
357
+ for header_map in (getattr(redirected, "headers", {}), getattr(redirected, "unredirected_hdrs", {})):
358
+ for key in [k for k in header_map if k.lower() in _SENSITIVE_REDIRECT_HEADERS]:
359
+ del header_map[key]
360
+ return redirected
193
361
 
194
362
 
195
- _OPENER = urllib.request.build_opener(_RedirectHandler())
363
+ def _open(request: urllib.request.Request, *, timeout: float) -> Any:
364
+ """Open a request with a fresh opener so proxy environment changes apply at call time."""
365
+ return urllib.request.build_opener(_RedirectHandler()).open(request, timeout=timeout)
196
366
 
197
367
 
198
368
  def _fetch(url: str, accept: str, deadline: float) -> bytes:
199
369
  """Perform bounded I/O; never print or mutate caller state from the worker."""
200
370
  # Ask intermediary HTTP caches to revalidate too; no local copy is kept.
201
- headers = {"User-Agent": USER_AGENT, "Accept": accept, "Cache-Control": "no-cache"}
371
+ headers = {"User-Agent": user_agent(), "Accept": accept, "Cache-Control": "no-cache"}
202
372
  try:
203
373
  if time.monotonic() >= deadline:
204
374
  raise TimeoutError("website request deadline exceeded")
205
375
  request = urllib.request.Request(url, headers=headers) # noqa: S310
206
- with _OPENER.open(request, timeout=TIMEOUT_SECONDS) as response:
376
+ with _open(request, timeout=TIMEOUT_SECONDS) as response:
207
377
  length = response.headers.get("Content-Length")
208
378
  expected = int(length) if length is not None else None
209
379
  if expected is not None and expected < 0:
@@ -293,7 +463,7 @@ def _parse_json(payload: bytes, shape: object, name: str) -> dict[str, Any]:
293
463
  return document
294
464
 
295
465
 
296
- def _parse_profile(payload: bytes) -> dict[str, Any]:
466
+ def _parse_profile(payload: bytes) -> Profile:
297
467
  """Decode the portfolio document behind every section command."""
298
468
  document = _parse_json(payload, PROFILE_SHAPE, "profile")
299
469
  links = document["thesis"].get("links")
@@ -303,7 +473,7 @@ def _parse_profile(payload: bytes) -> dict[str, Any]:
303
473
  repo = project.get("repo")
304
474
  if repo is not None:
305
475
  _validate(repo, str, f"profile.open_source[{index}].repo")
306
- return document
476
+ return cast(Profile, document)
307
477
 
308
478
 
309
479
  def _parse_markdown(payload: bytes) -> str:
@@ -319,14 +489,14 @@ def _parse_markdown(payload: bytes) -> str:
319
489
  return text
320
490
 
321
491
 
322
- def load_profile() -> dict[str, Any]:
492
+ def load_profile() -> Profile:
323
493
  """Return the portfolio document behind every section command."""
324
494
  return _parse_profile(_download(_profile_url()))
325
495
 
326
496
 
327
- def load_news() -> dict[str, Any]:
497
+ def load_news() -> NewsArchive:
328
498
  """Return the daily news archive, on the same origin as the profile."""
329
- return _parse_json(_download(origin_url(NEWS_PATH)), NEWS_SHAPE, "news")
499
+ return cast(NewsArchive, _parse_json(_download(origin_url(NEWS_PATH)), NEWS_SHAPE, "news"))
330
500
 
331
501
 
332
502
  def load_article(slug: str) -> str:
@@ -1,9 +1,10 @@
1
1
  """Select articles from the profile document: newest, matching, or named."""
2
2
 
3
3
  from collections.abc import Sequence
4
- from typing import Any
4
+ from typing import TYPE_CHECKING
5
5
 
6
- type Article = dict[str, Any]
6
+ if TYPE_CHECKING:
7
+ from fmind.api import Article
7
8
 
8
9
 
9
10
  def latest(articles: Sequence[Article], *, limit: int) -> list[Article]:
@@ -1,20 +1,17 @@
1
1
  """Command surface, mirroring the sections of www.fmind.dev."""
2
2
 
3
- import contextlib
4
- import json
5
3
  import os
6
- import shlex
7
- import signal
8
4
  import sys
9
- from collections.abc import Sequence
10
- from pathlib import Path
11
- from typing import Annotated, Any
5
+ from collections.abc import Callable, Sequence
6
+ from typing import TYPE_CHECKING, Annotated
12
7
 
13
8
  import typer
14
- from rich.console import Console, RenderableType
9
+ from rich.pager import Pager
15
10
 
16
- from fmind import __version__, articles, news, render
17
- from fmind.api import CONTROL_PATTERN, FmindError, load_article, load_news, load_profile
11
+ if TYPE_CHECKING:
12
+ from rich.console import Console, RenderableType
13
+
14
+ from fmind.api import Profile, ProjectsPayload
18
15
 
19
16
  app = typer.Typer(
20
17
  name="fmind",
@@ -26,7 +23,7 @@ app = typer.Typer(
26
23
  "Examples: fmind articles --json | jq '.[0].slug' • fmind news agent",
27
24
  context_settings={"help_option_names": ["-h", "--help"]},
28
25
  add_completion=False,
29
- rich_markup_mode="rich",
26
+ rich_markup_mode=None,
30
27
  pretty_exceptions_enable=False,
31
28
  )
32
29
 
@@ -37,6 +34,8 @@ LimitOption = Annotated[int, typer.Option("--limit", min=1, max=200, help="How m
37
34
 
38
35
  def _version(value: bool) -> None:
39
36
  if value:
37
+ from fmind import __version__
38
+
40
39
  typer.echo(f"fmind {__version__}")
41
40
  raise typer.Exit
42
41
 
@@ -59,29 +58,37 @@ def main(
59
58
 
60
59
  def _fail(message: str) -> typer.Exit:
61
60
  """Report a clear one-line error on stderr and end the command."""
61
+ from fmind.api import CONTROL_PATTERN
62
+
62
63
  message = CONTROL_PATTERN.sub(lambda match: ascii(match.group())[1:-1], message)
63
64
  message = message.encode("utf-8", errors="backslashreplace").decode("utf-8")
64
65
  typer.echo(f"fmind: {' '.join(message.split())}", err=True)
65
66
  return typer.Exit(code=1)
66
67
 
67
68
 
68
- def _doc() -> dict[str, Any]:
69
+ def _doc() -> Profile:
69
70
  """Load the profile, reporting a clear error instead of a traceback."""
71
+ from fmind.api import FmindError, load_profile
72
+
70
73
  try:
71
74
  return load_profile()
72
75
  except FmindError as error:
73
76
  raise _fail(str(error)) from error
74
77
 
75
78
 
76
- class _SystemPager:
79
+ class _SystemPager(Pager):
77
80
  """Page through the user's pager with colour, quitting at once when the text fits one screen."""
78
81
 
79
82
  def __init__(self, command: Sequence[str]) -> None:
80
83
  self.command = list(command)
81
84
 
82
85
  def show(self, content: str) -> None:
86
+ import contextlib
87
+ import signal
83
88
  import subprocess
84
89
 
90
+ from fmind.api import FmindError
91
+
85
92
  # Like Git: respect an explicit LESS, otherwise keep colours (-R), skip
86
93
  # paging for short output (-F), and leave the text on screen (-X).
87
94
  environment = {**os.environ, "LESS": os.environ.get("LESS", "FRX")}
@@ -129,7 +136,9 @@ def _full_screen_terminal() -> bool:
129
136
 
130
137
  def _pager_command() -> list[str] | None:
131
138
  """Return the pager for an interactive terminal, or None to print directly."""
139
+ import shlex
132
140
  import shutil
141
+ from pathlib import Path
133
142
 
134
143
  if not (sys.stdin.isatty() and sys.stdout.isatty() and _full_screen_terminal()):
135
144
  return None
@@ -143,6 +152,8 @@ def _pager_command() -> list[str] | None:
143
152
 
144
153
 
145
154
  def _console(ctx: typer.Context) -> Console:
155
+ from fmind import render
156
+
146
157
  return render.console(color=ctx.find_root().params["color"])
147
158
 
148
159
 
@@ -152,24 +163,38 @@ def _write(text: str) -> None:
152
163
  sys.stdout.flush()
153
164
 
154
165
 
155
- def _emit(ctx: typer.Context, body: RenderableType, payload: object, *, as_json: bool, page: bool = False) -> None:
166
+ def _emit(
167
+ ctx: typer.Context,
168
+ body: Callable[[], RenderableType],
169
+ payload: object,
170
+ *,
171
+ as_json: bool,
172
+ page: bool = False,
173
+ ) -> None:
156
174
  """Print either the rendered section or its JSON data."""
157
175
  if as_json or ctx.find_root().params["as_json"]:
176
+ import json
177
+
178
+ from fmind.api import CONTROL_PATTERN
179
+
158
180
  # json.dumps escapes C0 controls but not DEL or C1 (such as CSI); fields the
159
181
  # renderer does not validate still reach the terminal, so escape those too.
160
182
  text = json.dumps(payload, ensure_ascii=False, indent=2)
161
183
  _write(CONTROL_PATTERN.sub(lambda match: f"\\u{ord(match.group()):04x}", text) + "\n")
162
184
  return
185
+ from fmind import render
186
+ from fmind.api import FmindError
187
+
163
188
  out = _console(ctx)
164
189
  # Trim on terminals too: forced colour (--color, FORCE_COLOR) makes Rich treat a
165
190
  # pipe or file as a terminal, and line-end padding is invisible on a real one.
166
- trimmed = render.Trimmed(body)
191
+ trimmed = render.Trimmed(body())
167
192
  command = _pager_command() if page and out.is_terminal else None
168
193
  if command is None:
169
194
  out.print(trimmed, crop=False)
170
195
  return
171
196
  try:
172
- with out.pager(pager=_SystemPager(command), styles=True): # ty: ignore[invalid-argument-type]
197
+ with out.pager(pager=_SystemPager(command), styles=out.color_system is not None):
173
198
  out.print(trimmed, crop=False)
174
199
  except FmindError as error:
175
200
  raise _fail(str(error)) from error
@@ -181,31 +206,37 @@ def whoami(ctx: typer.Context, as_json: JsonOption = False) -> None:
181
206
  doc = _doc()
182
207
  _emit(
183
208
  ctx,
184
- render.whoami(doc),
209
+ lambda: _render().whoami(doc),
185
210
  {"metadata": doc["metadata"], "experience": doc["experience"][:1], "services": doc["services"]},
186
211
  as_json=as_json,
187
212
  )
188
213
 
189
214
 
215
+ def _render():
216
+ from fmind import render
217
+
218
+ return render
219
+
220
+
190
221
  @app.command()
191
222
  def about(ctx: typer.Context, as_json: JsonOption = False) -> None:
192
223
  """The biography, as published on the site."""
193
224
  doc = _doc()
194
- _emit(ctx, render.about(doc), doc["biography"], as_json=as_json)
225
+ _emit(ctx, lambda: _render().about(doc), doc["biography"], as_json=as_json)
195
226
 
196
227
 
197
228
  @app.command()
198
229
  def skills(ctx: typer.Context, as_json: JsonOption = False) -> None:
199
230
  """Core expertise, as published on the site."""
200
231
  doc = _doc()
201
- _emit(ctx, render.skills(doc), doc["expertise"], as_json=as_json)
232
+ _emit(ctx, lambda: _render().skills(doc), doc["expertise"], as_json=as_json)
202
233
 
203
234
 
204
235
  @app.command()
205
236
  def experiences(ctx: typer.Context, as_json: JsonOption = False) -> None:
206
237
  """Engagements in the order published by the website."""
207
238
  doc = _doc()
208
- _emit(ctx, render.experiences(doc), doc["experience"], as_json=as_json)
239
+ _emit(ctx, lambda: _render().experiences(doc), doc["experience"], as_json=as_json)
209
240
 
210
241
 
211
242
  @app.command()
@@ -216,7 +247,7 @@ def certifications(ctx: typer.Context, as_json: JsonOption = False) -> None:
216
247
  # spells it; `--json` and jq narrow the list better than a flag could.
217
248
  _emit(
218
249
  ctx,
219
- render.certifications(doc),
250
+ lambda: _render().certifications(doc),
220
251
  {"certifications": doc["certifications"], "thesis": doc["thesis"], "specializations": doc["specializations"]},
221
252
  as_json=as_json,
222
253
  )
@@ -226,29 +257,32 @@ def certifications(ctx: typer.Context, as_json: JsonOption = False) -> None:
226
257
  def community(ctx: typer.Context, as_json: JsonOption = False) -> None:
227
258
  """Ambassador and advisory roles."""
228
259
  doc = _doc()
229
- _emit(ctx, render.community(doc), doc["leadership"], as_json=as_json)
260
+ _emit(ctx, lambda: _render().community(doc), doc["leadership"], as_json=as_json)
230
261
 
231
262
 
232
263
  @app.command()
233
264
  def papers(ctx: typer.Context, as_json: JsonOption = False) -> None:
234
265
  """The doctorate and the peer-reviewed publications, with their code."""
235
266
  doc = _doc()
236
- _emit(ctx, render.papers(doc), {"thesis": doc["thesis"], "papers": doc["papers"]}, as_json=as_json)
267
+ _emit(ctx, lambda: _render().papers(doc), {"thesis": doc["thesis"], "papers": doc["papers"]}, as_json=as_json)
237
268
 
238
269
 
239
270
  @app.command()
240
271
  def projects(ctx: typer.Context, limit: LimitOption = 6, as_json: JsonOption = False) -> None:
241
272
  """Open-source repositories and video series; --limit bounds each list."""
242
273
  doc = _doc()
243
- payload = {"open_source": doc["open_source"][:limit], "youtube_series": doc["youtube_series"][:limit]}
244
- _emit(ctx, render.projects(payload), payload, as_json=as_json)
274
+ payload: ProjectsPayload = {
275
+ "open_source": doc["open_source"][:limit],
276
+ "youtube_series": doc["youtube_series"][:limit],
277
+ }
278
+ _emit(ctx, lambda: _render().projects(payload), payload, as_json=as_json)
245
279
 
246
280
 
247
281
  @app.command()
248
282
  def sites(ctx: typer.Context, as_json: JsonOption = False) -> None:
249
283
  """Interactive tools published alongside the writing."""
250
284
  doc = _doc()
251
- _emit(ctx, render.sites(doc), doc["site_pages"], as_json=as_json)
285
+ _emit(ctx, lambda: _render().sites(doc), doc["site_pages"], as_json=as_json)
252
286
 
253
287
 
254
288
  # Named for the command it is, not for the function: `articles` is the selection
@@ -256,10 +290,12 @@ def sites(ctx: typer.Context, as_json: JsonOption = False) -> None:
256
290
  @app.command("articles")
257
291
  def list_articles(ctx: typer.Context, limit: LimitOption = 6, as_json: JsonOption = False) -> None:
258
292
  """The most recent writing."""
293
+ from fmind import articles
294
+
259
295
  doc = _doc()
260
296
  posts = articles.latest(doc["articles"], limit=limit)
261
297
  footer = f"{len(doc['articles'])} published · {doc['metadata']['site_url'].rstrip('/')}/articles/"
262
- _emit(ctx, render.articles(posts, footer=footer), posts, as_json=as_json)
298
+ _emit(ctx, lambda: _render().articles(posts, footer=footer), posts, as_json=as_json)
263
299
 
264
300
 
265
301
  @app.command()
@@ -275,6 +311,8 @@ def search(
275
311
  as_json: JsonOption = False,
276
312
  ) -> None:
277
313
  """Find articles by term, newest match first."""
314
+ from fmind import articles
315
+
278
316
  doc = _doc()
279
317
  if tag is not None:
280
318
  names = [entry["name"] for entry in doc["tags"]]
@@ -282,7 +320,7 @@ def search(
282
320
  raise _fail(f"unknown tag {tag!r}; choose one of: {', '.join(names)}")
283
321
  found = articles.search(doc["articles"], " ".join(query or []), tag=tag, limit=limit)
284
322
  footer = f"{len(found)} shown · {len(doc['articles'])} published · fmind read <slug> opens one"
285
- _emit(ctx, render.articles(found, footer=footer), found, as_json=as_json)
323
+ _emit(ctx, lambda: _render().articles(found, footer=footer), found, as_json=as_json)
286
324
 
287
325
 
288
326
  @app.command()
@@ -293,6 +331,11 @@ def read(
293
331
  as_json: JsonOption = False,
294
332
  ) -> None:
295
333
  """Read one article in the terminal, from its published Markdown. Pages via $PAGER (default less, LESS=FRX)."""
334
+ import shlex
335
+
336
+ from fmind import articles
337
+ from fmind.api import FmindError, load_article
338
+
296
339
  wanted = slug.strip().lower()
297
340
  if not wanted:
298
341
  raise typer.BadParameter("slug must not be empty", param_hint="SLUG")
@@ -318,14 +361,14 @@ def read(
318
361
  return
319
362
  # The fetched article wins over any same-named field in the index entry.
320
363
  payload = {**(post or {}), "slug": resolved, "markdown": markdown}
321
- _emit(ctx, render.article_body(markdown), payload, as_json=as_json, page=True)
364
+ _emit(ctx, lambda: _render().article_body(markdown), payload, as_json=as_json, page=True)
322
365
 
323
366
 
324
367
  @app.command("tags")
325
368
  def list_tags(ctx: typer.Context, as_json: JsonOption = False) -> None:
326
369
  """The article tags that search --tag accepts."""
327
370
  doc = _doc()
328
- _emit(ctx, render.tags(doc), doc["tags"], as_json=as_json)
371
+ _emit(ctx, lambda: _render().tags(doc), doc["tags"], as_json=as_json)
329
372
 
330
373
 
331
374
  @app.command("news")
@@ -342,6 +385,9 @@ def list_news(
342
385
  as_json: JsonOption = False,
343
386
  ) -> None:
344
387
  """Daily curated links, newest edition first; terms keep only matching links."""
388
+ from fmind import news
389
+ from fmind.api import FmindError, load_news
390
+
345
391
  try:
346
392
  archive = load_news()
347
393
  except FmindError as error:
@@ -351,14 +397,14 @@ def list_news(
351
397
  count = limit if limit is not None else (10 if terms.strip() else 1)
352
398
  found = news.search(archive["editions"], terms, limit=count)
353
399
  footer = f"{len(found)} shown · {len(archive['editions'])} editions · {archive['url']}"
354
- _emit(ctx, render.news(found, footer=footer), found, as_json=as_json)
400
+ _emit(ctx, lambda: _render().news(found, footer=footer), found, as_json=as_json)
355
401
 
356
402
 
357
403
  @app.command()
358
404
  def hire(ctx: typer.Context, as_json: JsonOption = False) -> None:
359
405
  """What can be booked right now."""
360
406
  doc = _doc()
361
- _emit(ctx, render.hire(doc), doc["services"], as_json=as_json)
407
+ _emit(ctx, lambda: _render().hire(doc), doc["services"], as_json=as_json)
362
408
 
363
409
 
364
410
  @app.command()
@@ -366,12 +412,21 @@ def mcp(ctx: typer.Context) -> None:
366
412
  """Serve the website's MCP tools, resources, and prompts over protocol-only stdio (uses FMIND_PROFILE_URL)."""
367
413
  import asyncio
368
414
 
415
+ from fmind.api import FmindError
416
+
369
417
  if ctx.find_root().params["as_json"]:
370
418
  raise typer.BadParameter("mcp uses protocol-only stdio; --json applies to portfolio commands")
371
419
  try:
372
420
  from fmind.mcp import serve
373
421
  except ImportError as error:
374
- raise _fail("MCP support is not installed; run: uv tool install --upgrade 'fmind[mcp]'") from error
422
+ root = error.name.split(".", 1)[0] if isinstance(error, ModuleNotFoundError) and error.name else ""
423
+ if isinstance(error, ModuleNotFoundError) and (
424
+ error.name == "fmind.mcp" or root in {"httpx2", "mcp", "mcp_types"}
425
+ ):
426
+ raise _fail("MCP support is not installed; run: uv tool install --upgrade 'fmind[mcp]'") from error
427
+ raise _fail(
428
+ "MCP support could not be loaded; reinstall with: uv tool install --upgrade 'fmind[mcp]'"
429
+ ) from error
375
430
  try:
376
431
  asyncio.run(serve())
377
432
  except FmindError as error:
@@ -1,6 +1,7 @@
1
1
  """Bridge the website's read-only MCP surface from Streamable HTTP to stdio."""
2
2
 
3
3
  import asyncio
4
+ import contextlib
4
5
  import logging
5
6
  from collections.abc import AsyncIterator
6
7
  from typing import Any
@@ -15,7 +16,7 @@ from mcp.server.stdio import stdio_server
15
16
  from mcp.shared.exceptions import MCPError
16
17
 
17
18
  from fmind import __version__
18
- from fmind.api import MAX_BYTES, TIMEOUT_SECONDS, USER_AGENT, FmindError, origin_url
19
+ from fmind.api import MAX_BYTES, TIMEOUT_SECONDS, FmindError, origin_url, user_agent
19
20
 
20
21
 
21
22
  class _ResponseError(httpx2.StreamError):
@@ -63,7 +64,7 @@ class _BoundedTransport(httpx2.AsyncHTTPTransport):
63
64
  return httpx2.Response(504, request=request)
64
65
  except httpx2.TransportError:
65
66
  return httpx2.Response(502, request=request)
66
- if response.headers.get("content-encoding", "identity") != "identity":
67
+ if response.headers.get("content-encoding", "identity").strip().lower() != "identity":
67
68
  # The client asks for identity, so a compressed body is a broken upstream.
68
69
  await response.aclose()
69
70
  return httpx2.Response(502, request=request)
@@ -117,19 +118,24 @@ async def serve() -> None:
117
118
  logging.getLogger("mcp").setLevel(logging.CRITICAL)
118
119
  connected = False
119
120
  try:
120
- async with (
121
- httpx2.AsyncClient(
122
- transport=_BoundedTransport(),
123
- timeout=TIMEOUT_SECONDS,
124
- headers={"User-Agent": USER_AGENT, "Cache-Control": "no-cache", "Accept-Encoding": "identity"},
125
- ) as http,
126
- Client(
127
- streamable_http_client(endpoint, http_client=http),
128
- read_timeout_seconds=TIMEOUT_SECONDS,
129
- cache=None,
130
- ) as remote,
131
- stdio_server() as (reader, writer),
132
- ):
121
+ async with contextlib.AsyncExitStack() as stack:
122
+ http = await stack.enter_async_context(
123
+ httpx2.AsyncClient(
124
+ transport=_BoundedTransport(),
125
+ timeout=TIMEOUT_SECONDS,
126
+ max_redirects=3,
127
+ headers={"User-Agent": user_agent(), "Cache-Control": "no-cache", "Accept-Encoding": "identity"},
128
+ )
129
+ )
130
+ async with asyncio.timeout(TIMEOUT_SECONDS):
131
+ remote = await stack.enter_async_context(
132
+ Client(
133
+ streamable_http_client(endpoint, http_client=http),
134
+ read_timeout_seconds=TIMEOUT_SECONDS,
135
+ cache=None,
136
+ )
137
+ )
138
+ reader, writer = await stack.enter_async_context(stdio_server())
133
139
  server = create_bridge(remote)
134
140
  connected = True
135
141
  await server.run(reader, writer, server.create_initialization_options())
@@ -1,9 +1,11 @@
1
1
  """Select daily news editions from the news archive: newest, or matching."""
2
2
 
3
3
  from collections.abc import Sequence
4
- from typing import Any
4
+ from typing import TYPE_CHECKING
5
5
 
6
- type Edition = dict[str, Any]
6
+ if TYPE_CHECKING:
7
+ from fmind.api import NewsEdition as Edition
8
+ from fmind.api import NewsItem
7
9
 
8
10
 
9
11
  def _edition_text(edition: Edition) -> str:
@@ -11,7 +13,7 @@ def _edition_text(edition: Edition) -> str:
11
13
  return f"{edition['slug']} {edition['title']}".lower()
12
14
 
13
15
 
14
- def _item_text(item: dict[str, Any]) -> str:
16
+ def _item_text(item: NewsItem) -> str:
15
17
  """Return the searchable text of one link, lower-cased."""
16
18
  return " ".join((item["title"], item["domain"], item["description"], item["url"])).lower()
17
19
 
@@ -1,8 +1,10 @@
1
1
  """Render sections of the portfolio document as terminal output."""
2
2
 
3
3
  import errno
4
- from collections.abc import Iterable, Mapping, Sequence
5
- from typing import Any
4
+ import os
5
+ from collections import Counter
6
+ from collections.abc import Iterable, Sequence
7
+ from typing import TYPE_CHECKING
6
8
 
7
9
  from rich.console import Console, ConsoleOptions, Group, RenderableType, RenderResult
8
10
  from rich.segment import Segment
@@ -10,6 +12,9 @@ from rich.style import Style
10
12
  from rich.table import Table
11
13
  from rich.text import Text
12
14
 
15
+ if TYPE_CHECKING:
16
+ from fmind.api import Article, NewsEdition, Profile, ProjectsPayload
17
+
13
18
  # Use the terminal palette so its light/dark theme owns colour contrast.
14
19
  ACCENT = "bold blue"
15
20
 
@@ -24,9 +29,12 @@ class _Console(Console):
24
29
 
25
30
  def console(*, color: bool | None = None) -> Console:
26
31
  """Detect terminal colour and NO_COLOR unless explicitly overridden."""
32
+ # Rich's `no_color=True` only strips colours while still emitting SGR attributes
33
+ # and OSC 8 links on TTYs or under FORCE_COLOR; disabling color_system suppresses all ANSI.
34
+ suppress = color is False or (color is None and bool(os.environ.get("NO_COLOR")))
27
35
  return _Console(
28
36
  force_terminal=True if color is True else None,
29
- color_system="truecolor" if color is True else "auto",
37
+ color_system="truecolor" if color is True else (None if suppress else "auto"),
30
38
  no_color=None if color is None else not color,
31
39
  highlight=False,
32
40
  markup=False,
@@ -57,8 +65,9 @@ def _rstrip(line: list[Segment]) -> Iterable[Segment]:
57
65
 
58
66
  def _link(url: str) -> Text:
59
67
  """A published URL on one logical line: folding it would break copying and clicking."""
60
- # Terminals that support OSC 8 make it clickable; the text stays the literal URL.
61
- safe = url.startswith(("https://", "http://", "mailto:")) and not any(ch.isspace() for ch in url)
68
+ # Terminals that support OSC 8 make it clickable; fail closed at the sink to
69
+ # printable non-whitespace ASCII per OSC 8 / RFC 3986.
70
+ safe = url.startswith(("https://", "http://", "mailto:")) and all(0x21 <= ord(ch) <= 0x7E for ch in url)
62
71
  style = Style(underline=True, link=url) if safe else "underline"
63
72
  return Text(url, style=style, no_wrap=True, overflow="ignore")
64
73
 
@@ -83,15 +92,15 @@ def _rows(pairs: Sequence[tuple[str, RenderableType]]) -> Table:
83
92
  return table
84
93
 
85
94
 
86
- def whoami(doc: Mapping[str, Any]) -> RenderableType:
95
+ def whoami(doc: Profile) -> RenderableType:
87
96
  """Identity, location, featured experience, availability, contact, and social profiles."""
88
97
  meta = doc["metadata"]
89
- experience = doc.get("experience") or []
98
+ experience = doc["experience"]
90
99
  mission = Text("—")
91
100
  if experience:
92
101
  featured = experience[0]
93
102
  mission = Text(f"{featured['company']} — {featured['title']}")
94
- services = doc.get("services") or []
103
+ services = doc["services"]
95
104
  status = Text()
96
105
  for index, service in enumerate(services):
97
106
  if index:
@@ -122,7 +131,7 @@ def whoami(doc: Mapping[str, Any]) -> RenderableType:
122
131
  )
123
132
 
124
133
 
125
- def about(doc: Mapping[str, Any]) -> RenderableType:
134
+ def about(doc: Profile) -> RenderableType:
126
135
  """The biography paragraphs."""
127
136
  from rich.markdown import Markdown
128
137
 
@@ -130,13 +139,13 @@ def about(doc: Mapping[str, Any]) -> RenderableType:
130
139
  return _listing(blocks, "no biography published")
131
140
 
132
141
 
133
- def skills(doc: Mapping[str, Any]) -> RenderableType:
142
+ def skills(doc: Profile) -> RenderableType:
134
143
  """Show expertise without inventing command-line options or local labels."""
135
144
  blocks = [_entry(Text(card["title"], style="bold"), Text(card["description"])) for card in doc["expertise"]]
136
145
  return _listing(blocks, "no expertise published")
137
146
 
138
147
 
139
- def experiences(doc: Mapping[str, Any]) -> RenderableType:
148
+ def experiences(doc: Profile) -> RenderableType:
140
149
  """Engagements in the order published by the website."""
141
150
  blocks = [
142
151
  _entry(
@@ -150,7 +159,7 @@ def experiences(doc: Mapping[str, Any]) -> RenderableType:
150
159
  return _listing(blocks, "no experience published")
151
160
 
152
161
 
153
- def community(doc: Mapping[str, Any]) -> RenderableType:
162
+ def community(doc: Profile) -> RenderableType:
154
163
  """Ambassador and advisory roles, with their published links."""
155
164
  blocks = [
156
165
  _entry(
@@ -164,7 +173,7 @@ def community(doc: Mapping[str, Any]) -> RenderableType:
164
173
  return _listing(blocks, "no community role published")
165
174
 
166
175
 
167
- def certifications(doc: Mapping[str, Any]) -> RenderableType:
176
+ def certifications(doc: Profile) -> RenderableType:
168
177
  """Credentials, doctorate, and specializations with published evidence."""
169
178
  blocks: list[RenderableType] = []
170
179
  for badge in doc["certifications"]:
@@ -185,7 +194,7 @@ def certifications(doc: Mapping[str, Any]) -> RenderableType:
185
194
  return Group(*blocks)
186
195
 
187
196
 
188
- def projects(doc: Mapping[str, Any]) -> RenderableType:
197
+ def projects(doc: ProjectsPayload) -> RenderableType:
189
198
  """Open-source repositories, then video series."""
190
199
  blocks: list[RenderableType] = []
191
200
  for project in doc["open_source"]:
@@ -209,7 +218,7 @@ def projects(doc: Mapping[str, Any]) -> RenderableType:
209
218
  return _listing(blocks, "no project published")
210
219
 
211
220
 
212
- def articles(posts: Sequence[Mapping[str, Any]], *, footer: str = "") -> RenderableType:
221
+ def articles(posts: Sequence[Article], *, footer: str = "") -> RenderableType:
213
222
  """A list of articles, one block each, with `fmind read` slugs kept visible."""
214
223
  blocks: list[RenderableType] = []
215
224
  for post in posts:
@@ -224,20 +233,20 @@ def articles(posts: Sequence[Mapping[str, Any]], *, footer: str = "") -> Rendera
224
233
  return Group(*blocks, Text(footer)) if footer else Group(*blocks)
225
234
 
226
235
 
227
- def tags(doc: Mapping[str, Any]) -> RenderableType:
236
+ def tags(doc: Profile) -> RenderableType:
228
237
  """The site's article tags, each with its article count and the search that lists them."""
238
+ # Case-insensitive, like `fmind search --tag`, computed in one pass.
239
+ counts = Counter(name for post in doc["articles"] for name in {t.lower() for t in post["tags"]})
229
240
  blocks: list[RenderableType] = []
230
241
  for tag in doc["tags"]:
231
- # Case-insensitive, like `fmind search --tag`.
232
- name = tag["name"].lower()
233
- count = sum(name in {t.lower() for t in post["tags"]} for post in doc["articles"])
242
+ count = counts[tag["name"].lower()]
234
243
  hint = Text(f"{count} article{'' if count == 1 else 's'} · fmind search --tag ")
235
244
  hint.append(tag["name"], style="bold")
236
245
  blocks.append(_entry(Text(tag["name"], style=ACCENT), Text(tag["description"]), hint))
237
246
  return _listing(blocks, "no tag published")
238
247
 
239
248
 
240
- def news(editions: Sequence[Mapping[str, Any]], *, footer: str = "") -> RenderableType:
249
+ def news(editions: Sequence[NewsEdition], *, footer: str = "") -> RenderableType:
241
250
  """Daily news editions, each with its curated links."""
242
251
  blocks: list[RenderableType] = []
243
252
  for edition in editions:
@@ -262,7 +271,7 @@ def article_body(markdown: str) -> RenderableType:
262
271
  return Markdown(markdown, code_theme="ansi_light", hyperlinks=False)
263
272
 
264
273
 
265
- def papers(doc: Mapping[str, Any]) -> RenderableType:
274
+ def papers(doc: Profile) -> RenderableType:
266
275
  """The doctorate and the peer-reviewed record behind it."""
267
276
  thesis = doc["thesis"]
268
277
  thesis_lines: list[RenderableType] = [
@@ -288,7 +297,7 @@ def papers(doc: Mapping[str, Any]) -> RenderableType:
288
297
  return Group(*parts)
289
298
 
290
299
 
291
- def sites(doc: Mapping[str, Any]) -> RenderableType:
300
+ def sites(doc: Profile) -> RenderableType:
292
301
  """Interactive tools published alongside the writing."""
293
302
  blocks = [
294
303
  _entry(
@@ -302,7 +311,7 @@ def sites(doc: Mapping[str, Any]) -> RenderableType:
302
311
  return _listing(blocks, "no interactive site published")
303
312
 
304
313
 
305
- def hire(doc: Mapping[str, Any]) -> RenderableType:
314
+ def hire(doc: Profile) -> RenderableType:
306
315
  """What can be booked right now."""
307
316
  blocks = [
308
317
  _entry(
@@ -1,11 +0,0 @@
1
- """Read Médéric Hurier's (Fmind) portfolio and daily news from the terminal.
2
-
3
- Every command renders live documents published by https://www.fmind.dev, so this
4
- package carries no copy of its own and needs no release when the content changes.
5
- """
6
-
7
- from importlib.metadata import version
8
-
9
- __all__ = ["__version__"]
10
-
11
- __version__ = version("fmind")
File without changes
File without changes
File without changes
File without changes