fmind 0.2.0__tar.gz → 2.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fmind
-Version: 0.2.0
+Version: 2.0.0
 Summary: Read Médéric Hurier's (Fmind) portfolio from the terminal.
 Keywords: portfolio,cli,fmind,resume,articles
 Author: Médéric Hurier
@@ -10,7 +10,7 @@ Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Utilities
-Requires-Dist: typer>=0.15
+Requires-Dist: typer>=0.26
 Requires-Dist: rich>=13.9
 Requires-Dist: httpx2>=2.12,<3 ; extra == 'mcp'
 Requires-Dist: mcp>=2.2,<3 ; extra == 'mcp'
@@ -42,6 +42,7 @@ Every command fetches from the website and asks HTTP caches to revalidate. There
 
 | Command                                     | Shows                                             |
 | ------------------------------------------- | ------------------------------------------------- |
+| `fmind`                                     | The `whoami` card and a pointer to `--help`       |
 | `fmind whoami`                              | Name, featured experience, availability, contact  |
 | `fmind about`                               | The biography                                     |
 | `fmind skills`                              | Core expertise, as published on the site          |
@@ -58,20 +59,22 @@ Every command fetches from the website and asks HTTP caches to revalidate. There
 
 The commands group sections of the website's profile API. Their names stay stable when the website's navigation or visual design changes.
 
-`--limit` bounds projects, articles, and search results; `--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.
+`--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.
 
 `--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.
 
+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.
+
 ### Reading
 
-`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.
+`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.
 
 ```bash
 fmind search "agent security"
 fmind search --tag MLOps --limit 3
 ```
 
-`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. Use `--raw` for the Markdown source.
+`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. In an interactive terminal it pages through `$PAGER` (default `less`, with `LESS=FRX` unless you set `LESS`), so short articles print directly; `PAGER=cat` disables paging. Use `--raw` for the Markdown source.
 
 ```bash
 slug="$(fmind articles --limit 1 --json | jq -r '.[0].slug')"
@@ -86,9 +89,15 @@ fmind read "$slug" --raw | glow -
 ```bash
 fmind articles --limit 20 --json | jq -r '.[] | "\(.date[:10])  \(.title)"'
 fmind search agent --json | jq -r '.[].url'
-fmind certifications --json | jq -r '.[] | select(.active) | .title'
+fmind certifications --json | jq -r '.certifications[] | select(.active) | .title'
 ```
 
+`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`.
+
+**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.
+
+**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.
+
 ## Install
 
 ```bash
@@ -145,7 +154,7 @@ mise run smoke     # exercise every command against the live site
 mise run all       # format, check, test, build — the gate CI runs
 ```
 
-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 and tests Python 3.11–3.13 for compatibility.
+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.13 for compatibility, and tests the declared dependency floors with `--resolution lowest-direct` on Python 3.11.
 
 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.
 

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

@@ -18,6 +18,7 @@ Every command fetches from the website and asks HTTP caches to revalidate. There
 
 | Command                                     | Shows                                             |
 | ------------------------------------------- | ------------------------------------------------- |
+| `fmind`                                     | The `whoami` card and a pointer to `--help`       |
 | `fmind whoami`                              | Name, featured experience, availability, contact  |
 | `fmind about`                               | The biography                                     |
 | `fmind skills`                              | Core expertise, as published on the site          |
@@ -34,20 +35,22 @@ Every command fetches from the website and asks HTTP caches to revalidate. There
 
 The commands group sections of the website's profile API. Their names stay stable when the website's navigation or visual design changes.
 
-`--limit` bounds projects, articles, and search results; `--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.
+`--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.
 
 `--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.
 
+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.
+
 ### Reading
 
-`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.
+`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.
 
 ```bash
 fmind search "agent security"
 fmind search --tag MLOps --limit 3
 ```
 
-`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. Use `--raw` for the Markdown source.
+`fmind read` takes a slug, or enough of one to be unambiguous, and prints the article. In an interactive terminal it pages through `$PAGER` (default `less`, with `LESS=FRX` unless you set `LESS`), so short articles print directly; `PAGER=cat` disables paging. Use `--raw` for the Markdown source.
 
 ```bash
 slug="$(fmind articles --limit 1 --json | jq -r '.[0].slug')"
@@ -62,9 +65,15 @@ fmind read "$slug" --raw | glow -
 ```bash
 fmind articles --limit 20 --json | jq -r '.[] | "\(.date[:10])  \(.title)"'
 fmind search agent --json | jq -r '.[].url'
-fmind certifications --json | jq -r '.[] | select(.active) | .title'
+fmind certifications --json | jq -r '.certifications[] | select(.active) | .title'
 ```
 
+`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`.
+
+**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.
+
+**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.
+
 ## Install
 
 ```bash
@@ -121,7 +130,7 @@ mise run smoke     # exercise every command against the live site
 mise run all       # format, check, test, build — the gate CI runs
 ```
 
-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 and tests Python 3.11–3.13 for compatibility.
+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.13 for compatibility, and tests the declared dependency floors with `--resolution lowest-direct` on Python 3.11.
 
 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.
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "fmind"
-version = "0.2.0"
+version = "2.0.0"
 description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
 readme = "README.md"
 license = "MIT"
@@ -19,7 +19,7 @@ classifiers = [
     "Topic :: Utilities",
 ]
 dependencies = [
-    "typer>=0.15",
+    "typer>=0.26",
     "rich>=13.9",
 ]
 
@@ -51,7 +51,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.12.10,<0.13"]
+requires = ["uv_build>=0.12.17,<0.13"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

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

@@ -1,7 +1,7 @@
 # https://packaging.python.org/en/latest/specifications/pyproject-toml/
 [project]
 name = "fmind"
-version = "0.2.0"
+version = "2.0.0"
 description = "Read Médéric Hurier's (Fmind) portfolio from the terminal."
 readme = "README.md"
 license = "MIT"
@@ -14,7 +14,7 @@ classifiers = [
   "Programming Language :: Python :: 3 :: Only",
   "Topic :: Utilities",
 ]
-dependencies = ["typer>=0.15", "rich>=13.9"]
+dependencies = ["typer>=0.26", "rich>=13.9"]
 
 [project.urls]
 Homepage = "https://www.fmind.dev/"
@@ -40,7 +40,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.12.10,<0.13"]
+requires = ["uv_build>=0.12.17,<0.13"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

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

@@ -29,16 +29,17 @@ PROFILE_SHAPE = {
     "biography": [str],
     "expertise": [{"title": str, "description": str}],
     "experience": [{"company": str, "title": str, "description": str, "tags": [str]}],
-    "leadership": [{"organization": str, "role": str, "description": str}],
-    "certifications": [{"title": str, "issuer": str, "active": bool}],
-    "specializations": [{"title": str, "issuer_details": str}],
+    "leadership": [{"organization": str, "role": str, "description": str, "url": str}],
+    "certifications": [{"title": str, "issuer": str, "active": bool, "url": str}],
+    "specializations": [{"title": str, "issuer_details": str, "url": str}],
     "thesis": {"title": str, "institution_details": str, "description": str, "url": str},
     "papers": [{"title": str, "venue": str, "url": str}],
     "open_source": [{"title": str, "description": str, "href": str}],
     "youtube_series": [{"title": str, "description": str, "url": str}],
     "site_pages": [{"title": str, "description": str, "audience": str, "url": str}],
     "articles": [{"title": str, "description": str, "slug": str, "date": str, "tags": [str], "reading_minutes": int}],
-    "services": [{"title": str, "description": str, "badge": str, "badge_type": str, "cta_url": str}],
+    "services": [{"title": str, "description": str, "badge": str, "cta_url": str}],
+    "tags": [{"name": str}],
 }
 
 

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

@@ -4,11 +4,16 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
+import shlex
+import shutil
+import subprocess
 import sys
 from typing import Annotated, Any
 
 import typer
-from rich.console import RenderableType
+from rich.console import Console, RenderableType
+from rich.pager import Pager
 
 from fmind import __version__, articles, render
 from fmind.api import FmindError, load_article, load_profile
@@ -16,14 +21,14 @@ from fmind.api import FmindError, load_article, load_profile
 app = typer.Typer(
     name="fmind",
     help="Read Médéric Hurier's (Fmind) portfolio from the terminal. Every command renders the live "
-    "profile published at https://www.fmind.dev/api/profile. Use mcp for the stdio MCP bridge.",
+    "profile published at https://www.fmind.dev/api/profile. Without a command, show the whoami card. "
+    "Use mcp for the stdio MCP bridge.",
     add_completion=False,
-    no_args_is_help=True,
     rich_markup_mode="rich",
     pretty_exceptions_enable=False,
 )
 
-JsonOption = Annotated[bool, typer.Option("--json", help="Print the raw section as JSON instead of prose.")]
+JsonOption = Annotated[bool, typer.Option("--json", help="Print the command's data as JSON instead of prose.")]
 # One option name for "how many", on every command that prints a list.
 LimitOption = Annotated[int, typer.Option("--limit", min=1, max=200, help="How many entries to show.")]
 
@@ -34,8 +39,9 @@ def _version(value: bool) -> None:
         raise typer.Exit
 
 
-@app.callback()
+@app.callback(invoke_without_command=True)
 def main(
+    ctx: typer.Context,
     as_json: JsonOption = False,
     color: Annotated[
         bool | None, typer.Option("--color/--no-color", help="Force or suppress ANSI colour; auto by default.")
@@ -43,6 +49,11 @@ def main(
     _v: Annotated[bool, typer.Option("--version", callback=_version, is_eager=True, help="Show the version.")] = False,
 ) -> None:
     """Set output options before the command, or use --json on any command."""
+    if ctx.invoked_subcommand is None:
+        # A bare `fmind` works like a business card; `--help` lists everything else.
+        whoami(ctx)
+        if not as_json:
+            _console(ctx).print("\nfmind --help lists every command.", style="dim")
 
 
 def _fail(message: str) -> typer.Exit:
@@ -59,19 +70,57 @@ def _doc() -> dict[str, Any]:
         raise _fail(str(error)) from error
 
 
-def _emit(
-    ctx: typer.Context, body: RenderableType, payload: Any, *, as_json: bool, banner: dict[str, Any] | None = None
-) -> None:
-    """Print either the rendered section or its raw JSON."""
+class _SystemPager(Pager):
+    """Page through the user's pager with colour, quitting at once when the text fits one screen."""
+
+    def __init__(self, command: list[str]) -> None:
+        self.command = command
+
+    def show(self, content: str) -> None:
+        # Like Git: respect an explicit LESS, otherwise keep colours (-R), skip
+        # paging for short output (-F), and leave the text on screen (-X).
+        environment = {**os.environ, "LESS": os.environ.get("LESS", "FRX")}
+        subprocess.run(self.command, input=content.encode(), env=environment, check=False)  # noqa: S603
+
+
+def _pager_command() -> list[str] | None:
+    """Return the pager for an interactive terminal, or None to print directly."""
+    if not (sys.stdin.isatty() and sys.stdout.isatty()) or os.environ.get("TERM") == "dumb":
+        return None
+    try:
+        command = shlex.split(os.environ.get("PAGER", "less"))
+    except ValueError:
+        return None
+    if not command or command[0] == "cat" or shutil.which(command[0]) is None:
+        return None
+    return command
+
+
+def _console(ctx: typer.Context) -> Console:
+    return render.console(color=ctx.find_root().params["color"])
+
+
+def _write(text: str) -> None:
+    """Write and flush, so a closed reader (`| head`) fails inside Click's EPIPE handling, not at exit."""
+    sys.stdout.write(text)
+    sys.stdout.flush()
+
+
+def _emit(ctx: typer.Context, body: RenderableType, payload: Any, *, as_json: bool, page: bool = False) -> None:
+    """Print either the rendered section or its JSON data."""
     if as_json or ctx.find_root().params["as_json"]:
-        json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
-        sys.stdout.write("\n")
+        _write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
         return
-    out = render.console(color=ctx.find_root().params["color"])
-    if banner is not None:
-        out.print(render.banner(banner))
-        out.print()
-    out.print(body)
+    out = _console(ctx)
+    if not out.is_terminal:
+        out.print(render.Trimmed(body), crop=False)
+        return
+    command = _pager_command() if page else None
+    if command is None:
+        out.print(body, crop=False)
+        return
+    with out.pager(pager=_SystemPager(command), styles=True):
+        out.print(body, crop=False)
 
 
 @app.command()
@@ -79,7 +128,10 @@ def whoami(ctx: typer.Context, as_json: JsonOption = False) -> None:
     """Name, featured experience, availability, and contact."""
     doc = _doc()
     _emit(
-        ctx, render.whoami(doc), {"metadata": doc["metadata"], "services": doc["services"]}, banner=doc, as_json=as_json
+        ctx,
+        render.whoami(doc),
+        {"metadata": doc["metadata"], "experience": doc["experience"][:1], "services": doc["services"]},
+        as_json=as_json,
     )
 
 
@@ -110,7 +162,12 @@ def certifications(ctx: typer.Context, as_json: JsonOption = False) -> None:
     doc = _doc()
     # Every credential is listed with its state spelled out, the way the website
     # spells it; `--json` and jq narrow the list better than a flag could.
-    _emit(ctx, render.certifications(doc), doc["certifications"], as_json=as_json)
+    _emit(
+        ctx,
+        render.certifications(doc),
+        {"certifications": doc["certifications"], "thesis": doc["thesis"], "specializations": doc["specializations"]},
+        as_json=as_json,
+    )
 
 
 @app.command()
@@ -129,9 +186,10 @@ def papers(ctx: typer.Context, as_json: JsonOption = False) -> None:
 
 @app.command()
 def projects(ctx: typer.Context, limit: LimitOption = 6, as_json: JsonOption = False) -> None:
-    """Open-source repositories and video series."""
+    """Open-source repositories and video series; --limit bounds each list."""
     doc = _doc()
-    _emit(ctx, render.projects(doc, limit=limit), (doc["open_source"] + doc["youtube_series"])[:limit], as_json=as_json)
+    payload = {"open_source": doc["open_source"][:limit], "youtube_series": doc["youtube_series"][:limit]}
+    _emit(ctx, render.projects(doc, limit=limit), payload, as_json=as_json)
 
 
 @app.command()
@@ -163,6 +221,10 @@ def search(
 ) -> None:
     """Find articles by term, newest match first."""
     doc = _doc()
+    if tag is not None:
+        names = [entry["name"] for entry in doc["tags"]]
+        if tag.lower() not in {name.lower() for name in names}:
+            raise _fail(f"unknown tag {tag!r}; choose one of: {', '.join(names)}")
     found = articles.search(doc["articles"], query, tag=tag, limit=limit)
     footer = f"{len(found)} shown · {len(doc['articles'])} published · fmind read <slug> opens one"
     _emit(ctx, render.articles(found, footer=footer), found, as_json=as_json)
@@ -190,9 +252,10 @@ def read(
         raise _fail(str(error)) from error
     post = articles.by_slug(doc["articles"], resolved)
     if raw and not (as_json or ctx.find_root().params["as_json"]):
-        sys.stdout.write(markdown)
+        _write(markdown)
         return
-    _emit(ctx, render.article_body(markdown), {"slug": resolved, "markdown": markdown, **(post or {})}, as_json=as_json)
+    payload = {"slug": resolved, "markdown": markdown, **(post or {})}
+    _emit(ctx, render.article_body(markdown), payload, as_json=as_json, page=True)
 
 
 @app.command()

fmind-2.0.0/src/fmind/render.py

@@ -0,0 +1,254 @@
+"""Render sections of the portfolio document as terminal output."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from rich.console import Console, ConsoleOptions, Group, RenderableType, RenderResult
+from rich.markdown import Markdown
+from rich.padding import Padding
+from rich.segment import Segment
+from rich.style import Style
+from rich.table import Table
+from rich.text import Text
+
+# Use the terminal palette so its light/dark theme owns colour contrast.
+ACCENT = "bold blue"
+
+
+def console(*, color: bool | None = None) -> Console:
+    """Detect terminal colour and NO_COLOR unless explicitly overridden."""
+    return Console(
+        force_terminal=True if color is True else None,
+        color_system="truecolor" if color is True else "auto",
+        no_color=None if color is None else not color,
+        highlight=False,
+        markup=False,
+    )
+
+
+class Trimmed:
+    """Drop the padding Rich adds at line ends, which only shows once output is redirected."""
+
+    def __init__(self, renderable: RenderableType) -> None:
+        self.renderable = renderable
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        for line in Segment.split_lines(console.render(self.renderable, options)):
+            yield from _rstrip(line)
+            yield Segment.line()
+
+
+def _rstrip(line: list[Segment]) -> Iterable[Segment]:
+    """Remove trailing whitespace from one rendered line, keeping control codes."""
+    while line and not line[-1].control and not line[-1].text.rstrip():
+        line.pop()
+    if line and not line[-1].control:
+        text, style, _ = line[-1]
+        line[-1] = Segment(text.rstrip(), style)
+    return line
+
+
+def _link(url: str) -> Text:
+    """A published URL on one logical line: folding it would break copying and clicking."""
+    # Terminals that support OSC 8 make it clickable; the text stays the literal URL.
+    style = Style(underline=True, link=url) if url.startswith(("https://", "http://", "mailto:")) else "underline"
+    return Text(url, style=style, no_wrap=True, overflow="ignore")
+
+
+def _entry(*lines: RenderableType) -> Group:
+    """One stacked entry followed by a blank line, without padding that would crop links."""
+    return Group(*lines, Text())
+
+
+def _rows(pairs: list[tuple[str, RenderableType]]) -> Table:
+    """Lay out aligned key/value rows without visible borders."""
+    table = Table.grid(padding=(0, 2))
+    table.add_column(style=ACCENT, width=11, overflow="fold")
+    table.add_column(overflow="fold")
+    for key, value in pairs:
+        table.add_row(key, value)
+    return table
+
+
+def whoami(doc: dict[str, Any]) -> RenderableType:
+    """Identity, featured experience, availability, and contact."""
+    meta = doc["metadata"]
+    experience = doc.get("experience") or []
+    mission = Text("—")
+    if experience:
+        featured = experience[0]
+        mission = Text(f"{featured['company']} — {featured['title']}")
+    services = doc.get("services") or []
+    status = Text()
+    for index, service in enumerate(services):
+        if index:
+            status.append("\n")
+        status.append(service["title"], style="bold")
+        status.append(f" — {service['badge']}")
+    return _rows(
+        [
+            ("Name", Text(f"{meta['name']} ({meta['alternate_name']})", style="bold")),
+            ("Role", Text(meta["job_title"])),
+            ("Headline", Text(meta["headline_primary"])),
+            ("Experience", mission),
+            ("Status", status),
+            ("Contact", _link(meta["email"])),
+            ("Website", _link(meta["site_url"])),
+        ]
+    )
+
+
+def about(doc: dict[str, Any]) -> RenderableType:
+    """The biography paragraphs."""
+    return Group(*(Padding(Markdown(p, hyperlinks=False), (0, 0, 1, 0)) for p in doc["biography"]))
+
+
+def skills(doc: dict[str, Any]) -> RenderableType:
+    """Show expertise without inventing command-line options or local labels."""
+    return Group(*(_entry(Text(card["title"], style="bold"), Text(card["description"])) for card in doc["expertise"]))
+
+
+def experiences(doc: dict[str, Any]) -> RenderableType:
+    """Engagements in the order published by the website."""
+    return Group(
+        *(
+            _entry(
+                Text(job["company"].upper(), style=ACCENT),
+                Text(job["title"], style="bold"),
+                Text(job["description"]),
+                Text("  ".join(job["tags"])),
+            )
+            for job in doc["experience"]
+        )
+    )
+
+
+def community(doc: dict[str, Any]) -> RenderableType:
+    """Ambassador and advisory roles, with their published links."""
+    return Group(
+        *(
+            _entry(
+                Text(role["organization"], style=ACCENT),
+                Text(role["role"], style="bold"),
+                Text(role["description"]),
+                _link(role["url"]),
+            )
+            for role in doc["leadership"]
+        )
+    )
+
+
+def certifications(doc: dict[str, Any]) -> RenderableType:
+    """Credentials, doctorate, and specializations with published evidence."""
+    blocks: list[RenderableType] = []
+    for badge in doc["certifications"]:
+        state = "active" if badge["active"] else "past"
+        blocks.append(
+            _entry(Text(f"[{state}] {badge['title']}", style=ACCENT), Text(badge["issuer"]), _link(badge["url"]))
+        )
+    thesis = doc["thesis"]
+    blocks.append(
+        _entry(Text(thesis["title"], style=ACCENT), Text(thesis["institution_details"]), _link(thesis["url"]))
+    )
+    if doc["specializations"]:
+        blocks += [Text("SPECIALIZATIONS", style=ACCENT), Text()]
+    blocks += [
+        _entry(Text(spec["title"], style="bold"), Text(spec["issuer_details"]), _link(spec["url"]))
+        for spec in doc["specializations"]
+    ]
+    return Group(*blocks)
+
+
+def projects(doc: dict[str, Any], *, limit: int = 6) -> RenderableType:
+    """Open-source repositories, then video series; `limit` bounds each list."""
+    count = max(limit, 0)
+    blocks: list[RenderableType] = [
+        _entry(Text(project["title"], style="bold"), Text(project["description"]), _link(project["href"]))
+        for project in doc["open_source"][:count]
+    ]
+    series = doc["youtube_series"][:count]
+    if series:
+        blocks += [Text("VIDEO SERIES", style=ACCENT), Text()]
+    blocks += [
+        _entry(Text(video["title"], style="bold"), Text(video["description"]), _link(video["url"])) for video in series
+    ]
+    return Group(*blocks)
+
+
+def articles(posts: list[dict[str, Any]], *, footer: str = "") -> RenderableType:
+    """A list of articles, one block each, with `fmind read` slugs kept visible."""
+    blocks: list[RenderableType] = []
+    for post in posts:
+        head = Text(post["date"][:10], style=ACCENT)
+        head.append(f"  {post['reading_minutes']} min")
+        head.append(f"  {'  '.join(post['tags'])}")
+        body = Text("fmind read ")
+        body.append(post["slug"], style="bold")
+        blocks.append(_entry(head, Text(post["title"], style="bold"), body))
+    if not blocks:
+        return Text("no article matches")
+    return Group(*blocks, Text(footer)) if footer else Group(*blocks)
+
+
+def article_body(markdown: str) -> RenderableType:
+    """One article, rendered from its published Markdown source.
+
+    The source already opens with the title, summary, date, reading time, tags and
+    canonical URL, so nothing is prepended here.
+    """
+    return Markdown(markdown, code_theme="ansi_dark", hyperlinks=False)
+
+
+def papers(doc: dict[str, Any]) -> RenderableType:
+    """The doctorate and the peer-reviewed record behind it."""
+    thesis = doc["thesis"]
+    parts: list[RenderableType] = [
+        _entry(
+            Text(thesis["title"], style="bold"),
+            Text(thesis["institution_details"]),
+            Text(thesis["description"]),
+            _link(thesis["url"]),
+        )
+    ]
+    for link in thesis.get("links") or []:
+        row = Text(f"  {link['label']}  ", no_wrap=True, overflow="ignore")
+        row.append_text(_link(link["url"]))
+        parts.append(row)
+    if thesis.get("links"):
+        parts.append(Text())
+    parts += [Text("PUBLICATIONS", style=ACCENT), Text()]
+    parts += [
+        _entry(Text(paper["title"], style="bold"), Text(paper["venue"]), _link(paper["url"])) for paper in doc["papers"]
+    ]
+    return Group(*parts)
+
+
+def sites(doc: dict[str, Any]) -> RenderableType:
+    """Interactive tools published alongside the writing."""
+    blocks = [
+        _entry(
+            Text(page["title"], style="bold"),
+            Text(page["description"]),
+            Text(f"for {page['audience']}"),
+            _link(page["url"]),
+        )
+        for page in doc["site_pages"]
+    ]
+    return Group(*blocks) if blocks else Text("no interactive site published")
+
+
+def hire(doc: dict[str, Any]) -> RenderableType:
+    """What can be booked right now."""
+    return Group(
+        *(
+            _entry(
+                Text(service["title"], style="bold"),
+                Text(service["description"]),
+                Text(service["badge"], style="bold"),
+                _link(service["cta_url"]),
+            )
+            for service in doc["services"]
+        )
+    )

fmind-0.2.0/src/fmind/render.py

@@ -1,254 +0,0 @@
-"""Render sections of the portfolio document as terminal output."""
-
-from __future__ import annotations
-
-from typing import Any
-
-from rich.console import Console, Group, RenderableType
-from rich.markdown import Markdown
-from rich.padding import Padding
-from rich.table import Table
-from rich.text import Text
-
-ACCENT = "bold #00ff41"
-HI = "bold #ccffd9"
-DIM = "#57a86e"
-FLAG = "#7dffab"
-ERR = "#ff7a5c"
-
-WORDMARK = (
-    "█▀▀▀  █▄ ▄█  ▀█▀  █▄  █  █▀▀▄ ",
-    "█▄▄   █ ▀ █   █   █ █ █  █   █",
-    "█     █   █   █   █  ██  █   █",
-    "█     █   █  ▄█▄  █   █  █▄▄▀ ",
-)
-
-
-def console(*, color: bool | None = None) -> Console:
-    """Detect terminal colour and NO_COLOR unless explicitly overridden."""
-    return Console(
-        force_terminal=True if color is True else None,
-        color_system="truecolor" if color is True else "auto",
-        no_color=None if color is None else not color,
-        highlight=False,
-        markup=False,
-    )
-
-
-def _rows(pairs: list[tuple[str, RenderableType]], key_width: int = 11) -> Table:
-    """Lay out aligned key/value rows without visible borders."""
-    table = Table.grid(padding=(0, 2))
-    table.add_column(style=ACCENT, width=key_width, overflow="fold")
-    table.add_column(overflow="fold")
-    for key, value in pairs:
-        table.add_row(key, value)
-    return table
-
-
-def banner(doc: dict[str, Any]) -> RenderableType:
-    """The wordmark beside the name, role and headline."""
-    meta = doc["metadata"]
-    mark = Text("\n".join(WORDMARK), style=ACCENT)
-    identity = Group(
-        Text(meta["name"], style=HI),
-        Text(meta["job_title"], style="#00ff41"),
-        Text(meta["headline_primary"], style=DIM),
-    )
-    side = Table.grid(padding=(0, 3))
-    side.add_column(no_wrap=True)
-    side.add_column(overflow="fold")
-    side.add_row(mark, identity)
-    return side
-
-
-def whoami(doc: dict[str, Any]) -> RenderableType:
-    """Identity, featured experience, availability, and contact."""
-    meta = doc["metadata"]
-    experience = doc.get("experience") or []
-    mission = Text("—", style=DIM)
-    if experience:
-        current = experience[0]
-        mission = Text(f"{current['company']} — {current['title']}", style="#74e492")
-    services = doc.get("services") or []
-    status = Text()
-    for index, service in enumerate(services):
-        open_now = service.get("badge_type") != "error"
-        if index:
-            status.append("\n")
-        status.append("● ", style="#00ff41" if open_now else ERR)
-        status.append(service["title"], style=HI)
-        status.append(f" — {service['badge']}", style=DIM)
-    return _rows(
-        [
-            ("Name", Text(f"{meta['name']} ({meta['alternate_name']})", style=HI)),
-            ("Role", Text(meta["job_title"], style="#74e492")),
-            ("Experience", mission),
-            ("Status", status),
-            ("Contact", Text(meta["email"], style=FLAG)),
-            ("Website", Text(meta["site_url"], style=FLAG)),
-        ]
-    )
-
-
-def about(doc: dict[str, Any]) -> RenderableType:
-    """The biography paragraphs."""
-    return Group(*(Padding(Markdown(p, hyperlinks=False), (0, 0, 1, 0)) for p in doc["biography"]))
-
-
-def skills(doc: dict[str, Any]) -> RenderableType:
-    """Show expertise without inventing command-line options or local labels."""
-    return Group(
-        *(
-            Padding(Group(Text(card["title"], style=HI), Text(card["description"], style=DIM)), (0, 0, 1, 0))
-            for card in doc["expertise"]
-        )
-    )
-
-
-def experiences(doc: dict[str, Any]) -> RenderableType:
-    """Engagements in the order published by the website."""
-    blocks: list[RenderableType] = []
-    for job in doc["experience"]:
-        head = Text(job["company"].upper(), style=ACCENT)
-        body = Group(
-            head,
-            Text(job["title"], style=HI),
-            Text(job["description"], style=DIM),
-            Text("  ".join(job["tags"]), style=FLAG),
-        )
-        blocks.append(Padding(body, (0, 0, 1, 0)))
-    return Group(*blocks)
-
-
-def community(doc: dict[str, Any]) -> RenderableType:
-    """Ambassador and advisory roles."""
-    return _rows(
-        [
-            (r["organization"], Group(Text(r["role"], style=HI), Text(r["description"], style=DIM)))
-            for r in doc["leadership"]
-        ],
-        key_width=28,
-    )
-
-
-def certifications(doc: dict[str, Any]) -> RenderableType:
-    """Credentials, the doctorate that backs them, and the specializations."""
-    table = Table.grid(padding=(0, 2))
-    table.add_column(width=8, no_wrap=True)
-    table.add_column(overflow="fold")
-    for badge in doc["certifications"]:
-        active = bool(badge["active"])
-        # Spell out the published state so colour never carries it alone.
-        state = Text("[active]" if active else "[past]", style="#00ff41" if active else DIM)
-        body = Text(badge["title"], style=HI if active else "#74e492")
-        body.append(f" — {badge['issuer']}", style=DIM)
-        table.add_row(state, body)
-    degree = Text(doc["thesis"]["title"], style=HI)
-    degree.append(f" — {doc['thesis']['institution_details']}", style=DIM)
-    specs = Text("\n".join(f"  {s['title']} — {s['issuer_details']}" for s in doc["specializations"]), style=DIM)
-    return Group(
-        table,
-        Padding(degree, (1, 0, 0, 0)),
-        Padding(Group(Text("SPECIALIZATIONS", style=DIM), specs), (1, 0, 0, 0)),
-    )
-
-
-def projects(doc: dict[str, Any], *, limit: int = 6) -> RenderableType:
-    """Open-source repositories and video series."""
-    items = [(p["title"], p["description"], p["href"]) for p in doc["open_source"]]
-    items += [(v["title"], v["description"], v["url"]) for v in doc["youtube_series"]]
-    blocks = [
-        Padding(Group(Text(title, style=HI), Text(description, style=DIM), Text(url, style=FLAG)), (0, 0, 1, 0))
-        for title, description, url in items[: max(limit, 0)]
-    ]
-    return Group(*blocks)
-
-
-def articles(posts: list[dict[str, Any]], *, footer: str = "") -> RenderableType:
-    """A list of articles, one block each, with `fmind read` slugs kept visible."""
-    blocks: list[RenderableType] = []
-    for post in posts:
-        head = Text(post["date"][:10], style=ACCENT)
-        head.append(f"  {post['reading_minutes']} min", style=DIM)
-        head.append(f"  {'  '.join(post['tags'])}", style=FLAG)
-        body = Text("fmind read ", style=DIM)
-        body.append(post["slug"], style=FLAG)
-        blocks.append(Padding(Group(head, Text(post["title"], style=HI), body), (0, 0, 1, 0)))
-    if not blocks:
-        return Text("no article matches", style=DIM)
-    return Group(*blocks, Text(footer, style=DIM)) if footer else Group(*blocks)
-
-
-def article_body(markdown: str) -> RenderableType:
-    """One article, rendered from its published Markdown source.
-
-    The source already opens with the title, summary, date, reading time, tags and
-    canonical URL, so nothing is prepended here.
-    """
-    return Markdown(markdown, code_theme="ansi_dark", hyperlinks=False)
-
-
-def papers(doc: dict[str, Any]) -> RenderableType:
-    """The doctorate and the peer-reviewed record behind it."""
-    thesis = doc["thesis"]
-    head = Group(
-        Text(thesis["title"], style=HI),
-        Text(thesis["institution_details"], style="#74e492"),
-        Text(thesis["description"], style=DIM),
-        Text(thesis["url"], style=FLAG),
-    )
-    parts: list[RenderableType] = [Padding(head, (0, 0, 1, 0))]
-    for link in thesis.get("links") or []:
-        row = Text("  ", style=DIM)
-        row.append(link["label"], style="#74e492")
-        row.append(f"  {link['url']}", style=FLAG)
-        parts.append(row)
-    if thesis.get("links"):
-        parts.append(Text())
-    parts.append(Text("PUBLICATIONS", style=ACCENT))
-    for paper in doc["papers"]:
-        body = Group(
-            Text(paper["title"], style=HI),
-            Text(paper["venue"], style=DIM),
-            Text(paper["url"], style=FLAG),
-        )
-        parts.append(Padding(body, (1, 0, 0, 0)))
-    return Group(*parts)
-
-
-def sites(doc: dict[str, Any]) -> RenderableType:
-    """Interactive tools published alongside the writing."""
-    blocks = [
-        Padding(
-            Group(
-                Text(page["title"], style=HI),
-                Text(page["description"], style=DIM),
-                Text(f"for {page['audience']}", style="#74e492"),
-                Text(page["url"], style=FLAG),
-            ),
-            (0, 0, 1, 0),
-        )
-        for page in doc["site_pages"]
-    ]
-    return Group(*blocks) if blocks else Text("no interactive site published", style=DIM)
-
-
-def hire(doc: dict[str, Any]) -> RenderableType:
-    """What can be booked right now."""
-    blocks: list[RenderableType] = []
-    for service in doc["services"]:
-        open_now = service.get("badge_type") != "error"
-        state = Text("● ", style="#00ff41" if open_now else ERR)
-        state.append(service["badge"], style="#00ff41" if open_now else ERR)
-        blocks.append(
-            Padding(
-                Group(
-                    Text(service["title"], style=HI),
-                    Text(service["description"], style=DIM),
-                    state,
-                    Text(service["cta_url"], style=FLAG),
-                ),
-                (0, 0, 1, 0),
-            )
-        )
-    return Group(*blocks)