fmind 2.0.4__tar.gz → 2.1.0__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,8 +1,8 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fmind
3
- Version: 2.0.4
4
- Summary: Read Médéric Hurier's (Fmind) portfolio from the terminal.
5
- Keywords: portfolio,cli,fmind,resume,articles
3
+ Version: 2.1.0
4
+ Summary: Read Médéric Hurier's (Fmind) portfolio and daily news from the terminal.
5
+ Keywords: portfolio,cli,fmind,resume,articles,news,mcp
6
6
  Author: Médéric Hurier
7
7
  Author-email: Médéric Hurier <contact@fmind.dev>
8
8
  License-Expression: MIT
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
25
25
 
26
26
  # fmind
27
27
 
28
- Read [Médéric Hurier's (Fmind)](https://www.fmind.dev/) portfolio from the terminal.
28
+ Read [Médéric Hurier's (Fmind)](https://www.fmind.dev/) portfolio and daily tech news from the terminal.
29
29
 
30
30
  ```bash
31
31
  uvx fmind whoami
@@ -33,26 +33,28 @@ 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 |
52
-
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
-
55
- `--limit` bounds articles and search results, and each project list (repositories and video series); `--json` prints a command's data instead of prose; `--raw` prints an article's Markdown source. Search also accepts `--tag`. Use `--json` and `jq` for other filtering.
36
+ | Command | Shows |
37
+ | ---------------------------------------------- | --------------------------------------------------------- |
38
+ | `fmind` | The `whoami` card and a pointer to `--help` |
39
+ | `fmind whoami` | Name, headline, location, experience, availability, links |
40
+ | `fmind about` | The biography |
41
+ | `fmind skills` | Core expertise, as published on the site |
42
+ | `fmind experiences` | Engagements in website order |
43
+ | `fmind certifications` | Certifications, the PhD, specializations |
44
+ | `fmind community` | Ambassador and advisory roles |
45
+ | `fmind papers` | The doctorate and the peer-reviewed papers, with code |
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 tags` | The article tags, with counts and their `search --tag` |
52
+ | `fmind news [query...] [--limit]` | Daily curated links, newest edition first |
53
+ | `fmind hire` | What can be booked right now |
54
+
55
+ The commands group sections of the website's profile and news APIs. Their names stay stable when the website's navigation or visual design changes.
56
+
57
+ `--limit` bounds articles, search results, news editions, and each project list (repositories and video series); `--json` prints a command's data instead of prose; `--raw` prints an article's Markdown source. Search also accepts `--tag`. Use `--json` and `jq` for other filtering.
56
58
 
57
59
  `--json` works before or after the command: both `fmind --json experiences` and `fmind experiences --json` print the raw website section. Global `--color` / `--no-color` and `--version` go before the command. Colour is detected automatically, including `NO_COLOR` and redirected output. Use `fmind --help` or `fmind <command> --help` for options.
58
60
 
@@ -60,14 +62,14 @@ Output uses your terminal's default text colour and blue accent. Community roles
60
62
 
61
63
  ### Reading
62
64
 
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.
65
+ `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
66
 
65
67
  ```bash
66
- fmind search "agent security"
68
+ fmind search agent security
67
69
  fmind search --tag MLOps --limit 3
68
70
  ```
69
71
 
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.
72
+ `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
73
 
72
74
  ```bash
73
75
  slug="$(fmind articles --limit 1 --json | jq -r '.[0].slug')"
@@ -75,6 +77,17 @@ fmind read "$slug"
75
77
  fmind read "$slug" --raw | glow -
76
78
  ```
77
79
 
80
+ ### News
81
+
82
+ `fmind news` prints the latest daily edition of curated links on AI agents, Python, security, and cloud engineering. Search terms keep only the links that contain all of them, matched against titles, domains, summaries, and URLs; an edition date such as `2026-11-06` or `2026-11` selects every link of those editions. `--limit` counts editions: 1 by default, 10 when searching.
83
+
84
+ ```bash
85
+ fmind news # the latest edition
86
+ fmind news --limit 7 # the past week
87
+ fmind news agent security # matching links, newest edition first
88
+ fmind news 2026-11-06 # one edition
89
+ ```
90
+
78
91
  ### Piping
79
92
 
80
93
  `--json` turns every command into a data source, so the portfolio composes with the rest of the shell. JSON goes to stdout without colour or prose; errors go to stderr. With `read --raw --json`, JSON takes precedence and includes the Markdown in its `markdown` field.
@@ -83,9 +96,10 @@ fmind read "$slug" --raw | glow -
83
96
  fmind articles --limit 20 --json | jq -r '.[] | "\(.date[:10]) \(.title)"'
84
97
  fmind search agent --json | jq -r '.[].url'
85
98
  fmind certifications --json | jq -r '.certifications[] | select(.active) | .title'
99
+ fmind news --limit 7 --json | jq -r '.[].items[] | "\(.domain) \(.title)"'
86
100
  ```
87
101
 
88
- `whoami --json` includes `metadata`, `experience` (a list containing the featured engagement, or an empty list), and `services`. `certifications --json` includes `certifications`, `thesis`, and `specializations`. `projects --json` includes `open_source` and `youtube_series`, each keeping the website's fields and bounded by `--limit`.
102
+ `whoami --json` includes `metadata`, `experience` (a list containing the featured engagement, or an empty list), and `services`. `certifications --json` includes `certifications`, `thesis`, and `specializations`. `projects --json` includes `open_source` and `youtube_series`, each keeping the website's fields and bounded by `--limit`. `news --json` is a list of editions with the website's fields; a search keeps only the matching `items`.
89
103
 
90
104
  **Migration to 2.0.0:** `projects --json` now returns an object instead of one mixed array; change filters from `.[]` to `.open_source[]` or `.youtube_series[]`. `--limit` now bounds each list, so video series are no longer crowded out by repositories.
91
105
 
@@ -105,7 +119,7 @@ Point it at another origin with `FMIND_PROFILE_URL` — useful against a local `
105
119
  FMIND_PROFILE_URL=http://127.0.0.1:8080/api/profile fmind whoami
106
120
  ```
107
121
 
108
- Article reads and the MCP bridge follow the same origin, so one variable moves the whole CLI.
122
+ News and article reads and the MCP bridge follow the same origin, so one variable moves the whole CLI.
109
123
 
110
124
  ## MCP over stdio
111
125
 
@@ -129,7 +143,7 @@ For a host that accepts JSON configuration:
129
143
  }
130
144
  ```
131
145
 
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.
146
+ `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
147
 
134
148
  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
149
 
@@ -141,15 +155,16 @@ From this checkout, run `uv run --extra mcp fmind mcp`. The optional extra uses
141
155
  mise install # install the pinned toolchain
142
156
  mise run install # sync the locked environment and install hooks
143
157
  mise run format # ruff imports and format, dprint
144
- mise run check # ruff, ty, actionlint, zizmor, gitleaks, dependency audit
158
+ mise run check # lockfile, ruff, ty, dprint, jactionlint, betterleaks, dependency audit
145
159
  mise run test # offline pytest with branch coverage
146
160
  mise run smoke # exercise every command against the live site
161
+ mise run build # build the wheel and source distribution
147
162
  mise run all # format, check, test, build — the gate CI runs
148
163
  ```
149
164
 
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.
165
+ 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
166
 
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.
167
+ 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
168
 
154
169
  ## License
155
170
 
fmind-2.1.0/README.md ADDED
@@ -0,0 +1,146 @@
1
+ # fmind
2
+
3
+ Read [Médéric Hurier's (Fmind)](https://www.fmind.dev/) portfolio and daily tech news from the terminal.
4
+
5
+ ```bash
6
+ uvx fmind whoami
7
+ ```
8
+
9
+ ## Commands
10
+
11
+ | Command | Shows |
12
+ | ---------------------------------------------- | --------------------------------------------------------- |
13
+ | `fmind` | The `whoami` card and a pointer to `--help` |
14
+ | `fmind whoami` | Name, headline, location, experience, availability, links |
15
+ | `fmind about` | The biography |
16
+ | `fmind skills` | Core expertise, as published on the site |
17
+ | `fmind experiences` | Engagements in website order |
18
+ | `fmind certifications` | Certifications, the PhD, specializations |
19
+ | `fmind community` | Ambassador and advisory roles |
20
+ | `fmind papers` | The doctorate and the peer-reviewed papers, with code |
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 tags` | The article tags, with counts and their `search --tag` |
27
+ | `fmind news [query...] [--limit]` | Daily curated links, newest edition first |
28
+ | `fmind hire` | What can be booked right now |
29
+
30
+ The commands group sections of the website's profile and news APIs. Their names stay stable when the website's navigation or visual design changes.
31
+
32
+ `--limit` bounds articles, search results, news editions, and each project list (repositories and video series); `--json` prints a command's data instead of prose; `--raw` prints an article's Markdown source. Search also accepts `--tag`. Use `--json` and `jq` for other filtering.
33
+
34
+ `--json` works before or after the command: both `fmind --json experiences` and `fmind experiences --json` print the raw website section. Global `--color` / `--no-color` and `--version` go before the command. Colour is detected automatically, including `NO_COLOR` and redirected output. Use `fmind --help` or `fmind <command> --help` for options.
35
+
36
+ Output uses your terminal's default text colour and blue accent. Community roles and credentials use stacked entries with their published links, so they remain readable in narrow terminals. Links are never folded, so they stay copyable, and terminals that support OSC 8 hyperlinks make them clickable. Redirected output carries no trailing whitespace.
37
+
38
+ ### Reading
39
+
40
+ `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.
41
+
42
+ ```bash
43
+ fmind search agent security
44
+ fmind search --tag MLOps --limit 3
45
+ ```
46
+
47
+ `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.
48
+
49
+ ```bash
50
+ slug="$(fmind articles --limit 1 --json | jq -r '.[0].slug')"
51
+ fmind read "$slug"
52
+ fmind read "$slug" --raw | glow -
53
+ ```
54
+
55
+ ### News
56
+
57
+ `fmind news` prints the latest daily edition of curated links on AI agents, Python, security, and cloud engineering. Search terms keep only the links that contain all of them, matched against titles, domains, summaries, and URLs; an edition date such as `2026-11-06` or `2026-11` selects every link of those editions. `--limit` counts editions: 1 by default, 10 when searching.
58
+
59
+ ```bash
60
+ fmind news # the latest edition
61
+ fmind news --limit 7 # the past week
62
+ fmind news agent security # matching links, newest edition first
63
+ fmind news 2026-11-06 # one edition
64
+ ```
65
+
66
+ ### Piping
67
+
68
+ `--json` turns every command into a data source, so the portfolio composes with the rest of the shell. JSON goes to stdout without colour or prose; errors go to stderr. With `read --raw --json`, JSON takes precedence and includes the Markdown in its `markdown` field.
69
+
70
+ ```bash
71
+ fmind articles --limit 20 --json | jq -r '.[] | "\(.date[:10]) \(.title)"'
72
+ fmind search agent --json | jq -r '.[].url'
73
+ fmind certifications --json | jq -r '.certifications[] | select(.active) | .title'
74
+ fmind news --limit 7 --json | jq -r '.[].items[] | "\(.domain) \(.title)"'
75
+ ```
76
+
77
+ `whoami --json` includes `metadata`, `experience` (a list containing the featured engagement, or an empty list), and `services`. `certifications --json` includes `certifications`, `thesis`, and `specializations`. `projects --json` includes `open_source` and `youtube_series`, each keeping the website's fields and bounded by `--limit`. `news --json` is a list of editions with the website's fields; a search keeps only the matching `items`.
78
+
79
+ **Migration to 2.0.0:** `projects --json` now returns an object instead of one mixed array; change filters from `.[]` to `.open_source[]` or `.youtube_series[]`. `--limit` now bounds each list, so video series are no longer crowded out by repositories.
80
+
81
+ **Migration to 1.0.0:** `certifications --json` now returns an object instead of an array; change credential filters from `.[]` to `.certifications[]`. The `experience` field in `whoami --json` is additive. Update existing scripts before upgrading from 0.2.0.
82
+
83
+ ## Install
84
+
85
+ ```bash
86
+ uvx fmind whoami # zero install
87
+ uv tool install fmind # persistent
88
+ pipx install fmind # alternative
89
+ ```
90
+
91
+ Point it at another origin with `FMIND_PROFILE_URL` — useful against a local `mise run watch` server of the website:
92
+
93
+ ```bash
94
+ FMIND_PROFILE_URL=http://127.0.0.1:8080/api/profile fmind whoami
95
+ ```
96
+
97
+ News and article reads and the MCP bridge follow the same origin, so one variable moves the whole CLI.
98
+
99
+ ## MCP over stdio
100
+
101
+ Install the optional MCP dependencies and let your agent host launch the bridge:
102
+
103
+ ```bash
104
+ uv tool install 'fmind[mcp]'
105
+ fmind mcp
106
+ ```
107
+
108
+ For a host that accepts JSON configuration:
109
+
110
+ ```json
111
+ {
112
+ "mcpServers": {
113
+ "fmind": {
114
+ "command": "uvx",
115
+ "args": ["--from", "fmind[mcp]", "fmind", "mcp"]
116
+ }
117
+ }
118
+ }
119
+ ```
120
+
121
+ `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.
122
+
123
+ 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.
124
+
125
+ From this checkout, run `uv run --extra mcp fmind mcp`. The optional extra uses the [official MCP Python SDK](https://py.sdk.modelcontextprotocol.io/); ordinary portfolio commands still need only Typer and Rich.
126
+
127
+ ## Development
128
+
129
+ ```bash
130
+ mise install # install the pinned toolchain
131
+ mise run install # sync the locked environment and install hooks
132
+ mise run format # ruff imports and format, dprint
133
+ mise run check # lockfile, ruff, ty, dprint, jactionlint, betterleaks, dependency audit
134
+ mise run test # offline pytest with branch coverage
135
+ mise run smoke # exercise every command against the live site
136
+ mise run build # build the wheel and source distribution
137
+ mise run all # format, check, test, build — the gate CI runs
138
+ ```
139
+
140
+ 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.
141
+
142
+ 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.
143
+
144
+ ## License
145
+
146
+ [MIT](LICENSE) — © 2026 Médéric Hurier (Fmind).
@@ -1,7 +1,7 @@
1
1
  [project]
2
2
  name = "fmind"
3
- version = "2.0.4"
4
- description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
3
+ version = "2.1.0"
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"
7
7
  license-files = ["LICENSE"]
@@ -12,6 +12,8 @@ keywords = [
12
12
  "fmind",
13
13
  "resume",
14
14
  "articles",
15
+ "news",
16
+ "mcp",
15
17
  ]
16
18
  classifiers = [
17
19
  "Environment :: Console",
@@ -74,10 +76,23 @@ select = [
74
76
  "S",
75
77
  "SIM",
76
78
  "RUF",
79
+ "TID",
80
+ ]
81
+
82
+ [tool.ruff.lint.flake8-tidy-imports]
83
+ banned-module-level-imports = [
84
+ "fmind.mcp",
85
+ "httpx2",
86
+ "mcp",
87
+ "mcp_types",
77
88
  ]
78
89
 
79
90
  [tool.ruff.lint.per-file-ignores]
80
- "tests/**" = ["S101"]
91
+ "src/fmind/mcp.py" = ["TID253"]
92
+ "tests/**" = [
93
+ "S101",
94
+ "TID253",
95
+ ]
81
96
 
82
97
  [tool.ruff.format]
83
98
  docstring-code-format = true
@@ -1,14 +1,14 @@
1
1
  # https://packaging.python.org/en/latest/specifications/pyproject-toml/
2
2
  [project]
3
3
  name = "fmind"
4
- version = "2.0.4"
5
- description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
4
+ version = "2.1.0"
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"
8
8
  license-files = ["LICENSE"]
9
9
  authors = [{ name = "Médéric Hurier", email = "contact@fmind.dev" }]
10
10
  requires-python = ">=3.11"
11
- keywords = ["portfolio", "cli", "fmind", "resume", "articles"]
11
+ keywords = ["portfolio", "cli", "fmind", "resume", "articles", "news", "mcp"]
12
12
  classifiers = [
13
13
  "Environment :: Console",
14
14
  "Intended Audience :: Developers",
@@ -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
 
@@ -0,0 +1,11 @@
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")
@@ -18,9 +18,13 @@ from typing import Any
18
18
  from fmind import __version__
19
19
 
20
20
  PROFILE_URL = "https://www.fmind.dev/api/profile"
21
+ NEWS_PATH = "/api/news"
21
22
  TIMEOUT_SECONDS = 15.0
22
23
  # Bound memory use even when the origin serves an unexpected document.
23
24
  MAX_BYTES = 8 * 1024 * 1024
25
+ # `--json` re-indents forwarded fields, so output grows with the square of their
26
+ # nesting; the published profile nests four levels.
27
+ MAX_DEPTH = 32
24
28
  USER_AGENT = f"fmind/{__version__} (+https://github.com/fmind/cli)"
25
29
  # Slugs reach a URL, so only the shape the site actually mints is accepted.
26
30
  SLUG_PATTERN = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*\Z")
@@ -29,7 +33,22 @@ CONTROL_PATTERN = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]")
29
33
 
30
34
  # Only fields consumed by this CLI are required; new website fields pass through.
31
35
  PROFILE_SHAPE = {
32
- "metadata": dict.fromkeys(("name", "alternate_name", "job_title", "headline_primary", "email", "site_url"), str),
36
+ "metadata": {
37
+ **dict.fromkeys(
38
+ (
39
+ "name",
40
+ "alternate_name",
41
+ "job_title",
42
+ "headline_primary",
43
+ "headline_secondary",
44
+ "work_location",
45
+ "email",
46
+ "site_url",
47
+ ),
48
+ str,
49
+ ),
50
+ "socials": [{"name": str, "url": str}],
51
+ },
33
52
  "biography": [str],
34
53
  "expertise": [{"title": str, "description": str}],
35
54
  "experience": [{"company": str, "title": str, "description": str, "tags": [str]}],
@@ -37,13 +56,26 @@ PROFILE_SHAPE = {
37
56
  "certifications": [{"title": str, "issuer": str, "active": bool, "url": str}],
38
57
  "specializations": [{"title": str, "issuer_details": str, "url": str}],
39
58
  "thesis": {"title": str, "institution_details": str, "description": str, "url": str},
40
- "papers": [{"title": str, "venue": str, "url": str}],
59
+ "papers": [{"title": str, "venue": str, "url": str, "code": str, "code_label": str}],
41
60
  "open_source": [{"title": str, "description": str, "href": str}],
42
61
  "youtube_series": [{"title": str, "description": str, "url": str}],
43
62
  "site_pages": [{"title": str, "description": str, "audience": str, "url": str}],
44
63
  "articles": [{"title": str, "description": str, "slug": str, "date": str, "tags": [str], "reading_minutes": int}],
45
64
  "services": [{"title": str, "description": str, "badge": str, "cta_url": str}],
46
- "tags": [{"name": str}],
65
+ "tags": [{"name": str, "description": str}],
66
+ }
67
+ # The same rule for the daily news archive at /api/news.
68
+ NEWS_SHAPE = {
69
+ "url": str,
70
+ "editions": [
71
+ {
72
+ "slug": str,
73
+ "date": str,
74
+ "title": str,
75
+ "url": str,
76
+ "items": [{"title": str, "url": str, "domain": str, "description": str}],
77
+ }
78
+ ],
47
79
  }
48
80
 
49
81
 
@@ -148,6 +180,10 @@ def _fetch(url: str, accept: str, deadline: float) -> bytes:
148
180
  return bytes(payload)
149
181
 
150
182
 
183
+ # Each JSON endpoint by the name used in its error messages and the document it serves.
184
+ _DOCUMENTS = {"profile": "portfolio document", "news": "news archive"}
185
+
186
+
151
187
  def _validate(value: object, shape: object, path: str) -> None:
152
188
  """Check the few nested JSON shapes needed for rendering, without a dependency."""
153
189
  if isinstance(shape, dict) and isinstance(value, dict):
@@ -161,7 +197,9 @@ def _validate(value: object, shape: object, path: str) -> None:
161
197
  raise FmindError(f"the website returned terminal control characters at {path}")
162
198
  return
163
199
  else:
164
- raise FmindError(f"the profile endpoint returned an invalid portfolio document at {path}")
200
+ # The path starts with the endpoint name, such as `profile.metadata`.
201
+ name = path.split(".", 1)[0].split("[", 1)[0]
202
+ raise FmindError(f"the {name} endpoint returned an invalid {_DOCUMENTS[name]} at {path}")
165
203
 
166
204
 
167
205
  def _reject_constant(name: str) -> None:
@@ -169,31 +207,39 @@ def _reject_constant(name: str) -> None:
169
207
  raise ValueError(name)
170
208
 
171
209
 
172
- def _parse_profile(payload: bytes) -> dict[str, Any]:
173
- """Decode the portfolio document, rejecting anything that is not one."""
210
+ def _parse_json(payload: bytes, shape: object, name: str) -> dict[str, Any]:
211
+ """Decode one of the website's JSON documents, rejecting anything that is not one."""
212
+ noun = _DOCUMENTS[name]
174
213
  try:
175
214
  document = json.loads(payload, parse_constant=_reject_constant)
176
215
  except (ValueError, RecursionError) as error:
177
- raise FmindError("the profile endpoint did not return JSON") from error
216
+ raise FmindError(f"the {name} endpoint did not return JSON") from error
178
217
  # Check keys and future fields too: JSON output forwards them even when the
179
218
  # renderer does not consume them. The decoder accepts surrogates and can turn
180
219
  # finite JSON literals such as 1e999 into infinity.
181
- pending = [document]
220
+ pending = [(document, 0)]
182
221
  while pending:
183
- value = pending.pop()
222
+ value, depth = pending.pop()
223
+ if depth > MAX_DEPTH:
224
+ raise FmindError(f"the {name} endpoint returned a {noun} nested over {MAX_DEPTH} levels")
184
225
  if isinstance(value, float) and not math.isfinite(value):
185
- raise FmindError("the profile endpoint returned a non-finite number")
226
+ raise FmindError(f"the {name} endpoint returned a non-finite number")
186
227
  if isinstance(value, str):
187
228
  try:
188
229
  value.encode("utf-8")
189
230
  except UnicodeEncodeError as error:
190
- raise FmindError("the profile endpoint returned invalid Unicode") from error
231
+ raise FmindError(f"the {name} endpoint returned invalid Unicode") from error
191
232
  elif isinstance(value, dict):
192
- pending.extend(value)
193
- pending.extend(value.values())
233
+ pending.extend((item, depth + 1) for item in (*value, *value.values()))
194
234
  elif isinstance(value, list):
195
- pending.extend(value)
196
- _validate(document, PROFILE_SHAPE, "profile")
235
+ pending.extend((item, depth + 1) for item in value)
236
+ _validate(document, shape, name)
237
+ return document
238
+
239
+
240
+ def _parse_profile(payload: bytes) -> dict[str, Any]:
241
+ """Decode the portfolio document behind every section command."""
242
+ document = _parse_json(payload, PROFILE_SHAPE, "profile")
197
243
  links = document["thesis"].get("links")
198
244
  if links is not None:
199
245
  _validate(links, [{"label": str, "url": str}], "profile.thesis.links")
@@ -218,6 +264,11 @@ def load_profile(*, url: str | None = None) -> dict[str, Any]:
218
264
  return _parse_profile(_download(url if url is not None else _profile_url()))
219
265
 
220
266
 
267
+ def load_news() -> dict[str, Any]:
268
+ """Return the daily news archive, on the same origin as the profile."""
269
+ return _parse_json(_download(origin_url(NEWS_PATH)), NEWS_SHAPE, "news")
270
+
271
+
221
272
  def load_article(slug: str, *, profile_url: str | None = None) -> str:
222
273
  """Return the Markdown source of one published article."""
223
274
  url = article_url(slug, profile_url=profile_url)
@@ -3,25 +3,26 @@
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
16
17
  from rich.pager import Pager
17
18
 
18
- from fmind import __version__, articles, render
19
- from fmind.api import CONTROL_PATTERN, FmindError, load_article, load_profile
19
+ from fmind import __version__, articles, news, render
20
+ from fmind.api import CONTROL_PATTERN, FmindError, load_article, load_news, load_profile
20
21
 
21
22
  app = typer.Typer(
22
23
  name="fmind",
23
- help="Read Médéric Hurier's (Fmind) portfolio from the terminal. Every command renders the live "
24
- "profile published at https://www.fmind.dev/api/profile. Without a command, show the whoami card. "
24
+ help="Read Médéric Hurier's (Fmind) portfolio and daily news from the terminal. Every command renders "
25
+ "live documents published by https://www.fmind.dev. Without a command, show the whoami card. "
25
26
  "Use mcp for the stdio MCP bridge.",
26
27
  add_completion=False,
27
28
  rich_markup_mode="rich",
@@ -72,6 +73,14 @@ def _doc() -> dict[str, Any]:
72
73
  raise _fail(str(error)) from error
73
74
 
74
75
 
76
+ def _news() -> dict[str, Any]:
77
+ """Load the news archive, reporting a clear error instead of a traceback."""
78
+ try:
79
+ return load_news()
80
+ except FmindError as error:
81
+ raise _fail(str(error)) from error
82
+
83
+
75
84
  class _SystemPager(Pager):
76
85
  """Page through the user's pager with colour, quitting at once when the text fits one screen."""
77
86
 
@@ -82,17 +91,52 @@ class _SystemPager(Pager):
82
91
  # Like Git: respect an explicit LESS, otherwise keep colours (-R), skip
83
92
  # paging for short output (-F), and leave the text on screen (-X).
84
93
  environment = {**os.environ, "LESS": os.environ.get("LESS", "FRX")}
94
+ message = "could not display the article with PAGER; check PAGER or use PAGER=cat"
85
95
  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
96
+ process = subprocess.Popen(self.command, stdin=subprocess.PIPE, stderr=subprocess.DEVNULL, env=environment) # noqa: S603
97
+ except OSError as error:
98
+ raise FmindError(message) from error
99
+ # Like the standard library's pager: Ctrl-C belongs to the pager. subprocess.run
100
+ # would kill it, leaving the terminal in raw mode, so wait for it to quit instead.
101
+ # Ctrl-C drops the unwritten rest, and a pager that quits early closes the pipe.
102
+ with (
103
+ contextlib.suppress(OSError),
104
+ cast("IO[bytes]", process.stdin) as pipe,
105
+ contextlib.suppress(KeyboardInterrupt),
106
+ ):
107
+ pipe.write(content.encode())
108
+ while True:
109
+ try:
110
+ code = process.wait()
111
+ break
112
+ except KeyboardInterrupt:
113
+ pass
114
+ if code != 0:
115
+ raise FmindError(message)
116
+
117
+
118
+ def _full_screen_terminal() -> bool:
119
+ """Whether TERM describes a terminal that a full-screen pager can drive."""
120
+ # Otherwise less stops at a "terminal is not fully functional" prompt that the
121
+ # hidden stderr turns into a blank screen: TERM unset or dumb, or missing from
122
+ # terminfo (TERM=xterm-kitty over SSH). setupterm also rejects generic and
123
+ # hardcopy entries such as `unknown`.
124
+ if os.environ.get("TERM", "") in {"", "dumb"}:
125
+ return False
126
+ try:
127
+ import curses # only the pager needs it, and Windows lacks it
128
+ except ImportError:
129
+ return True
130
+ try:
131
+ curses.setupterm()
132
+ except curses.error:
133
+ return False
134
+ return True
91
135
 
92
136
 
93
137
  def _pager_command() -> list[str] | None:
94
138
  """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":
139
+ if not (sys.stdin.isatty() and sys.stdout.isatty() and _full_screen_terminal()):
96
140
  return None
97
141
  try:
98
142
  command = shlex.split(os.environ.get("PAGER", "less"))
@@ -122,23 +166,23 @@ def _emit(ctx: typer.Context, body: RenderableType, payload: Any, *, as_json: bo
122
166
  _write(CONTROL_PATTERN.sub(lambda match: f"\\u{ord(match.group()):04x}", text) + "\n")
123
167
  return
124
168
  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
169
+ # Trim on terminals too: forced colour (--color, FORCE_COLOR) makes Rich treat a
170
+ # pipe or file as a terminal, and line-end padding is invisible on a real one.
171
+ trimmed = render.Trimmed(body)
172
+ command = _pager_command() if page and out.is_terminal else None
129
173
  if command is None:
130
- out.print(body, crop=False)
174
+ out.print(trimmed, crop=False)
131
175
  return
132
176
  try:
133
177
  with out.pager(pager=_SystemPager(command), styles=True):
134
- out.print(body, crop=False)
178
+ out.print(trimmed, crop=False)
135
179
  except FmindError as error:
136
180
  raise _fail(str(error)) from error
137
181
 
138
182
 
139
183
  @app.command()
140
184
  def whoami(ctx: typer.Context, as_json: JsonOption = False) -> None:
141
- """Name, featured experience, availability, and contact."""
185
+ """Name, headline, location, featured experience, availability, and contact."""
142
186
  doc = _doc()
143
187
  _emit(
144
188
  ctx,
@@ -192,7 +236,7 @@ def community(ctx: typer.Context, as_json: JsonOption = False) -> None:
192
236
 
193
237
  @app.command()
194
238
  def papers(ctx: typer.Context, as_json: JsonOption = False) -> None:
195
- """The doctorate and the peer-reviewed publications."""
239
+ """The doctorate and the peer-reviewed publications, with their code."""
196
240
  doc = _doc()
197
241
  _emit(ctx, render.papers(doc), {"thesis": doc["thesis"], "papers": doc["papers"]}, as_json=as_json)
198
242
 
@@ -226,8 +270,11 @@ def list_articles(ctx: typer.Context, limit: LimitOption = 6, as_json: JsonOptio
226
270
  @app.command()
227
271
  def search(
228
272
  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.")] = "",
273
+ # Optional, so filtering by tag alone needs no empty positional argument; several
274
+ # words need no quotes, so the hint printed by `read` runs as written.
275
+ query: Annotated[
276
+ list[str] | None, typer.Argument(help="Terms to match against titles, summaries, tags and slugs.")
277
+ ] = None,
231
278
  tag: Annotated[str | None, typer.Option("--tag", help="Restrict to one of the site's tags, such as Agent.")] = None,
232
279
  limit: LimitOption = 10,
233
280
  as_json: JsonOption = False,
@@ -238,7 +285,7 @@ def search(
238
285
  names = [entry["name"] for entry in doc["tags"]]
239
286
  if tag.lower() not in {name.lower() for name in names}:
240
287
  raise _fail(f"unknown tag {tag!r}; choose one of: {', '.join(names)}")
241
- found = articles.search(doc["articles"], query, tag=tag, limit=limit)
288
+ found = articles.search(doc["articles"], " ".join(query or []), tag=tag, limit=limit)
242
289
  footer = f"{len(found)} shown · {len(doc['articles'])} published · fmind read <slug> opens one"
243
290
  _emit(ctx, render.articles(found, footer=footer), found, as_json=as_json)
244
291
 
@@ -254,7 +301,8 @@ def read(
254
301
  doc = _doc()
255
302
  matches = articles.candidates(doc["articles"], slug.strip().lower())
256
303
  if not matches:
257
- raise _fail(f"no article matches {slug!r} — try: fmind search {slug}")
304
+ # Quote only what the shell would split or expand, so the hint runs as printed.
305
+ raise _fail(f"no article matches {slug!r} — try: fmind {shlex.join(['search', *slug.split()])}")
258
306
  if len(matches) > 1:
259
307
  listed = ", ".join(matches[:10])
260
308
  raise _fail(f"{slug!r} matches {len(matches)} articles: {listed}")
@@ -267,10 +315,40 @@ def read(
267
315
  if raw and not (as_json or ctx.find_root().params["as_json"]):
268
316
  _write(markdown)
269
317
  return
270
- payload = {"slug": resolved, "markdown": markdown, **(post or {})}
318
+ # The fetched article wins over any same-named field in the index entry.
319
+ payload = {**(post or {}), "slug": resolved, "markdown": markdown}
271
320
  _emit(ctx, render.article_body(markdown), payload, as_json=as_json, page=True)
272
321
 
273
322
 
323
+ @app.command("tags")
324
+ def list_tags(ctx: typer.Context, as_json: JsonOption = False) -> None:
325
+ """The article tags that search --tag accepts."""
326
+ doc = _doc()
327
+ _emit(ctx, render.tags(doc), doc["tags"], as_json=as_json)
328
+
329
+
330
+ @app.command("news")
331
+ def list_news(
332
+ ctx: typer.Context,
333
+ query: Annotated[
334
+ list[str] | None,
335
+ typer.Argument(help="Terms to match against link titles, domains, summaries, URLs, and edition dates."),
336
+ ] = None,
337
+ limit: Annotated[
338
+ int | None,
339
+ typer.Option("--limit", min=1, max=200, help="How many editions to show: 1 by default, 10 with terms."),
340
+ ] = None,
341
+ as_json: JsonOption = False,
342
+ ) -> None:
343
+ """Daily curated links, newest edition first; terms keep only matching links."""
344
+ archive = _news()
345
+ terms = " ".join(query or [])
346
+ # Today's edition is the common read; a search looks further back by default.
347
+ found = news.search(archive["editions"], terms, limit=limit or (10 if terms.strip() else 1))
348
+ footer = f"{len(found)} shown · {len(archive['editions'])} editions · {archive['url']}"
349
+ _emit(ctx, render.news(found, footer=footer), found, as_json=as_json)
350
+
351
+
274
352
  @app.command()
275
353
  def hire(ctx: typer.Context, as_json: JsonOption = False) -> None:
276
354
  """What can be booked right now."""
@@ -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
@@ -0,0 +1,38 @@
1
+ """Select daily news editions from the news archive: newest, or matching."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ Edition = dict[str, Any]
8
+
9
+
10
+ def _edition_text(edition: Edition) -> str:
11
+ """Return the searchable header of one edition, lower-cased: its date slug and title."""
12
+ return f"{edition['slug']} {edition['title']}".lower()
13
+
14
+
15
+ def _item_text(item: dict[str, Any]) -> str:
16
+ """Return the searchable text of one link, lower-cased."""
17
+ return " ".join((item["title"], item["domain"], item["description"], item["url"])).lower()
18
+
19
+
20
+ def search(editions: list[Edition], query: str, *, limit: int) -> list[Edition]:
21
+ """Return newest-first editions, keeping only the links that contain every term of `query`.
22
+
23
+ Terms are ANDed, case-insensitively, against the edition header and each link,
24
+ so `2026-11-06` selects that whole edition and `agent 2026-11` keeps November's
25
+ agent links. Without terms, return the latest editions unchanged.
26
+ """
27
+ terms = query.lower().split()
28
+ found: list[Edition] = []
29
+ if limit <= 0:
30
+ return found
31
+ for edition in sorted(editions, key=lambda e: e["date"], reverse=True):
32
+ header = _edition_text(edition)
33
+ items = [item for item in edition["items"] if all(t in f"{header} {_item_text(item)}" for t in terms)]
34
+ if items:
35
+ found.append(edition if len(items) == len(edition["items"]) else {**edition, "items": items})
36
+ if len(found) >= limit:
37
+ break
38
+ return found
@@ -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))
@@ -73,7 +78,7 @@ def _rows(pairs: list[tuple[str, RenderableType]]) -> Table:
73
78
 
74
79
 
75
80
  def whoami(doc: dict[str, Any]) -> RenderableType:
76
- """Identity, featured experience, availability, and contact."""
81
+ """Identity, location, featured experience, availability, contact, and social profiles."""
77
82
  meta = doc["metadata"]
78
83
  experience = doc.get("experience") or []
79
84
  mission = Text("—")
@@ -92,7 +97,8 @@ def whoami(doc: dict[str, Any]) -> RenderableType:
92
97
  [
93
98
  ("Name", Text(f"{meta['name']} ({meta['alternate_name']})", style="bold")),
94
99
  ("Role", Text(meta["job_title"])),
95
- ("Headline", Text(meta["headline_primary"])),
100
+ ("Headline", Text("\n".join(filter(None, (meta["headline_primary"], meta["headline_secondary"]))))),
101
+ ("Location", Text(meta["work_location"])),
96
102
  ("Experience", mission),
97
103
  ("Status", status),
98
104
  ]
@@ -101,7 +107,11 @@ def whoami(doc: dict[str, Any]) -> RenderableType:
101
107
  # with the same 11-character label and two-space gap.
102
108
  *(
103
109
  Text.assemble((f"{label:<13}", ACCENT), _link(value), no_wrap=True, overflow="ignore")
104
- for label, value in (("Contact", meta["email"]), ("Website", meta["site_url"]))
110
+ for label, value in (
111
+ ("Contact", meta["email"]),
112
+ ("Website", meta["site_url"]),
113
+ *((social["name"], social["url"]) for social in meta["socials"]),
114
+ )
105
115
  ),
106
116
  )
107
117
 
@@ -113,37 +123,36 @@ def about(doc: dict[str, Any]) -> RenderableType:
113
123
 
114
124
  def skills(doc: dict[str, Any]) -> RenderableType:
115
125
  """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"]))
126
+ blocks = [_entry(Text(card["title"], style="bold"), Text(card["description"])) for card in doc["expertise"]]
127
+ return _listing(blocks, "no expertise published")
117
128
 
118
129
 
119
130
  def experiences(doc: dict[str, Any]) -> RenderableType:
120
131
  """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"]
132
+ blocks = [
133
+ _entry(
134
+ Text(job["company"].upper(), style=ACCENT),
135
+ Text(job["title"], style="bold"),
136
+ Text(job["description"]),
137
+ Text(" ".join(job["tags"])),
130
138
  )
131
- )
139
+ for job in doc["experience"]
140
+ ]
141
+ return _listing(blocks, "no experience published")
132
142
 
133
143
 
134
144
  def community(doc: dict[str, Any]) -> RenderableType:
135
145
  """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"]
146
+ blocks = [
147
+ _entry(
148
+ Text(role["organization"], style=ACCENT),
149
+ Text(role["role"], style="bold"),
150
+ Text(role["description"]),
151
+ _link(role["url"]),
145
152
  )
146
- )
153
+ for role in doc["leadership"]
154
+ ]
155
+ return _listing(blocks, "no community role published")
147
156
 
148
157
 
149
158
  def certifications(doc: dict[str, Any]) -> RenderableType:
@@ -180,7 +189,7 @@ def projects(doc: dict[str, Any], *, limit: int = 6) -> RenderableType:
180
189
  blocks += [
181
190
  _entry(Text(video["title"], style="bold"), Text(video["description"]), _link(video["url"])) for video in series
182
191
  ]
183
- return Group(*blocks)
192
+ return _listing(blocks, "no project published")
184
193
 
185
194
 
186
195
  def articles(posts: list[dict[str, Any]], *, footer: str = "") -> RenderableType:
@@ -198,6 +207,33 @@ def articles(posts: list[dict[str, Any]], *, footer: str = "") -> RenderableType
198
207
  return Group(*blocks, Text(footer)) if footer else Group(*blocks)
199
208
 
200
209
 
210
+ def tags(doc: dict[str, Any]) -> RenderableType:
211
+ """The site's article tags, each with its article count and the search that lists them."""
212
+ blocks: list[RenderableType] = []
213
+ for tag in doc["tags"]:
214
+ # Case-insensitive, like `fmind search --tag`.
215
+ name = tag["name"].lower()
216
+ count = sum(name in {t.lower() for t in post["tags"]} for post in doc["articles"])
217
+ hint = Text(f"{count} article{'' if count == 1 else 's'} · fmind search --tag ")
218
+ hint.append(tag["name"], style="bold")
219
+ blocks.append(_entry(Text(tag["name"], style=ACCENT), Text(tag["description"]), hint))
220
+ return _listing(blocks, "no tag published")
221
+
222
+
223
+ def news(editions: list[dict[str, Any]], *, footer: str = "") -> RenderableType:
224
+ """Daily news editions, each with its curated links."""
225
+ blocks: list[RenderableType] = []
226
+ for edition in editions:
227
+ blocks += [Text(edition["title"], style=ACCENT), _link(edition["url"]), Text()]
228
+ blocks += [
229
+ _entry(Text(item["title"], style="bold"), Text(item["description"]), _link(item["url"]))
230
+ for item in edition["items"]
231
+ ]
232
+ if not blocks:
233
+ return Text("no news edition matches")
234
+ return Group(*blocks, Text(footer)) if footer else Group(*blocks)
235
+
236
+
201
237
  def article_body(markdown: str) -> RenderableType:
202
238
  """One article, rendered from its published Markdown source.
203
239
 
@@ -225,9 +261,13 @@ def papers(doc: dict[str, Any]) -> RenderableType:
225
261
  if thesis.get("links"):
226
262
  parts.append(Text())
227
263
  parts += [Text("PUBLICATIONS", style=ACCENT), Text()]
228
- parts += [
229
- _entry(Text(paper["title"], style="bold"), Text(paper["venue"]), _link(paper["url"])) for paper in doc["papers"]
230
- ]
264
+ for paper in doc["papers"]:
265
+ lines: list[RenderableType] = [Text(paper["title"], style="bold"), Text(paper["venue"]), _link(paper["url"])]
266
+ if paper["code"]:
267
+ code = Text(f" {paper['code_label'] or 'Code'} ", no_wrap=True, overflow="ignore")
268
+ code.append_text(_link(paper["code"]))
269
+ lines.append(code)
270
+ parts.append(_entry(*lines))
231
271
  return Group(*parts)
232
272
 
233
273
 
@@ -242,19 +282,18 @@ def sites(doc: dict[str, Any]) -> RenderableType:
242
282
  )
243
283
  for page in doc["site_pages"]
244
284
  ]
245
- return Group(*blocks) if blocks else Text("no interactive site published")
285
+ return _listing(blocks, "no interactive site published")
246
286
 
247
287
 
248
288
  def hire(doc: dict[str, Any]) -> RenderableType:
249
289
  """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"]
290
+ blocks = [
291
+ _entry(
292
+ Text(service["title"], style="bold"),
293
+ Text(service["description"]),
294
+ Text(service["badge"], style="bold"),
295
+ _link(service["cta_url"]),
259
296
  )
260
- )
297
+ for service in doc["services"]
298
+ ]
299
+ return _listing(blocks, "no service published")
fmind-2.0.4/README.md DELETED
@@ -1,131 +0,0 @@
1
- # fmind
2
-
3
- Read [Médéric Hurier's (Fmind)](https://www.fmind.dev/) portfolio from the terminal.
4
-
5
- ```bash
6
- uvx fmind whoami
7
- ```
8
-
9
- ## Commands
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 |
27
-
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
-
30
- `--limit` bounds articles and search results, and each project list (repositories and video series); `--json` prints a command's data instead of prose; `--raw` prints an article's Markdown source. Search also accepts `--tag`. Use `--json` and `jq` for other filtering.
31
-
32
- `--json` works before or after the command: both `fmind --json experiences` and `fmind experiences --json` print the raw website section. Global `--color` / `--no-color` and `--version` go before the command. Colour is detected automatically, including `NO_COLOR` and redirected output. Use `fmind --help` or `fmind <command> --help` for options.
33
-
34
- Output uses your terminal's default text colour and blue accent. Community roles and credentials use stacked entries with their published links, so they remain readable in narrow terminals. Links are never folded, so they stay copyable, and terminals that support OSC 8 hyperlinks make them clickable. Redirected output carries no trailing whitespace.
35
-
36
- ### Reading
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.
39
-
40
- ```bash
41
- fmind search "agent security"
42
- fmind search --tag MLOps --limit 3
43
- ```
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.
46
-
47
- ```bash
48
- slug="$(fmind articles --limit 1 --json | jq -r '.[0].slug')"
49
- fmind read "$slug"
50
- fmind read "$slug" --raw | glow -
51
- ```
52
-
53
- ### Piping
54
-
55
- `--json` turns every command into a data source, so the portfolio composes with the rest of the shell. JSON goes to stdout without colour or prose; errors go to stderr. With `read --raw --json`, JSON takes precedence and includes the Markdown in its `markdown` field.
56
-
57
- ```bash
58
- fmind articles --limit 20 --json | jq -r '.[] | "\(.date[:10]) \(.title)"'
59
- fmind search agent --json | jq -r '.[].url'
60
- fmind certifications --json | jq -r '.certifications[] | select(.active) | .title'
61
- ```
62
-
63
- `whoami --json` includes `metadata`, `experience` (a list containing the featured engagement, or an empty list), and `services`. `certifications --json` includes `certifications`, `thesis`, and `specializations`. `projects --json` includes `open_source` and `youtube_series`, each keeping the website's fields and bounded by `--limit`.
64
-
65
- **Migration to 2.0.0:** `projects --json` now returns an object instead of one mixed array; change filters from `.[]` to `.open_source[]` or `.youtube_series[]`. `--limit` now bounds each list, so video series are no longer crowded out by repositories.
66
-
67
- **Migration to 1.0.0:** `certifications --json` now returns an object instead of an array; change credential filters from `.[]` to `.certifications[]`. The `experience` field in `whoami --json` is additive. Update existing scripts before upgrading from 0.2.0.
68
-
69
- ## Install
70
-
71
- ```bash
72
- uvx fmind whoami # zero install
73
- uv tool install fmind # persistent
74
- pipx install fmind # alternative
75
- ```
76
-
77
- Point it at another origin with `FMIND_PROFILE_URL` — useful against a local `mise run watch` server of the website:
78
-
79
- ```bash
80
- FMIND_PROFILE_URL=http://127.0.0.1:8080/api/profile fmind whoami
81
- ```
82
-
83
- Article reads and the MCP bridge follow the same origin, so one variable moves the whole CLI.
84
-
85
- ## MCP over stdio
86
-
87
- Install the optional MCP dependencies and let your agent host launch the bridge:
88
-
89
- ```bash
90
- uv tool install 'fmind[mcp]'
91
- fmind mcp
92
- ```
93
-
94
- For a host that accepts JSON configuration:
95
-
96
- ```json
97
- {
98
- "mcpServers": {
99
- "fmind": {
100
- "command": "uvx",
101
- "args": ["--from", "fmind[mcp]", "fmind", "mcp"]
102
- }
103
- }
104
- }
105
- ```
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.
108
-
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
-
111
- From this checkout, run `uv run --extra mcp fmind mcp`. The optional extra uses the [official MCP Python SDK](https://py.sdk.modelcontextprotocol.io/); ordinary portfolio commands still need only Typer and Rich.
112
-
113
- ## Development
114
-
115
- ```bash
116
- mise install # install the pinned toolchain
117
- mise run install # sync the locked environment and install hooks
118
- mise run format # ruff imports and format, dprint
119
- mise run check # ruff, ty, actionlint, zizmor, gitleaks, dependency audit
120
- mise run test # offline pytest with branch coverage
121
- mise run smoke # exercise every command against the live site
122
- mise run all # format, check, test, build — the gate CI runs
123
- ```
124
-
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
-
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
-
129
- ## License
130
-
131
- [MIT](LICENSE) — © 2026 Médéric Hurier (Fmind).
@@ -1,11 +0,0 @@
1
- """Read Médéric Hurier's (Fmind) portfolio from the terminal.
2
-
3
- Every command renders https://www.fmind.dev/api/profile, so this package carries
4
- no copy of its own and needs no release when the website 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