@z29k/notabene 0.1.0

package/src/config.mjs

@@ -0,0 +1,127 @@
+// Config resolver — the SINGLE place that knows the file layout. Imported by
+// astro.config.mjs, content.config.ts, the remark plugin and the runtime libs
+// (server-only: uses node:path/url; NEVER from a client script — the client gets
+// `clientRoots` serialized as JSON).
+//
+// Run-from-package model: the renderer lives in the consumer's node_modules and is
+// pointed at the consumer's repo at runtime. Only the DATA (docs, notabene.config,
+// .notabene store) lives in the consumer repo.
+//   NOTABENE_ROOT   — consumer repo root (defaults to process.cwd()).
+//   NOTABENE_CONFIG — path to notabene.config.mjs (defaults to <root>/notabene.config.mjs).
+// The CLI (bin/notabene.mjs) sets these before invoking astro.
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const REPO_ROOT = process.env.NOTABENE_ROOT
+  ? path.resolve(process.env.NOTABENE_ROOT)
+  : process.cwd();
+
+const CONFIG_PATH = process.env.NOTABENE_CONFIG
+  ? path.resolve(process.env.NOTABENE_CONFIG)
+  : path.resolve(REPO_ROOT, "notabene.config.mjs");
+
+// Top-level await: load the consumer's config by absolute path. Astro loads this
+// module (via astro.config.mjs / content.config.ts) as ESM, which supports TLA.
+let userConfig;
+try {
+  userConfig = (await import(/* @vite-ignore */ pathToFileURL(CONFIG_PATH).href)).default ?? {};
+} catch (err) {
+  throw new Error(
+    `notabene: could not load config at ${CONFIG_PATH}. Run \`notabene init\` first, ` +
+      `or set NOTABENE_CONFIG. (${err instanceof Error ? err.message : err})`,
+  );
+}
+
+function slugify(s) {
+  return String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Input format (§10.bis) — the renderer supports MDX AND CommonMark/GFM:
+//   "mdx"        (default): globs .md + .mdx, MDX integration loaded. .mdx parsed
+//                STRICT (JSX/expressions), .md as CommonMark/GFM LENIENT. A repo can
+//                mix both, by extension.
+//   "commonmark" (alias "gfm"/"md"): globs .md + .markdown, MDX NOT loaded. Everything
+//                CommonMark/GFM lenient — zero MDX dependency/strictness.
+const FORMAT = String(userConfig.format ?? "mdx").toLowerCase();
+export const format = FORMAT === "gfm" || FORMAT === "md" ? "commonmark" : FORMAT;
+export const mdxEnabled = format === "mdx";
+export const extensions = mdxEnabled ? ["md", "mdx"] : ["md", "markdown"];
+const extGlob = extensions.length === 1 ? extensions[0] : `{${extensions.join(",")}}`;
+
+function normalizeRoot(root) {
+  const rel = String(root.path).replace(/\\/g, "/").replace(/\/+$/, "");
+  const abs = path.resolve(REPO_ROOT, rel);
+  return {
+    key: root.key ?? slugify(root.label ?? rel),
+    label: root.label ?? rel,
+    description: root.description ?? "",
+    // Logical repo-relative path (= prefix of a comment's `page` field).
+    path: rel,
+    // Sidebar sub-title (e.g. "docs/").
+    subLabel: `${rel}/`,
+    exclude: Array.isArray(root.exclude) ? root.exclude : [],
+    abs,
+    baseUrl: pathToFileURL(abs),
+    // Content-loader glob: format extensions minus the exclusions.
+    pattern: [`**/*.${extGlob}`, ...(root.exclude ?? []).map((e) => `!${e}`)],
+  };
+}
+
+export const siteName = userConfig.siteName ?? "Docs";
+export const tagline = userConfig.tagline ?? "docs";
+export const locale = userConfig.locale ?? "en";
+export const port = userConfig.port ?? 3009;
+export const host = process.env.NOTABENE_HOST ? true : (userConfig.host ?? false);
+export const verify = Array.isArray(userConfig.verify) ? userConfig.verify : [];
+
+export const roots = (userConfig.roots ?? [{ label: "Docs", path: "docs" }]).map(
+  normalizeRoot,
+);
+
+// Store (comments + journal), resolved to absolute. Default: docs/.notabene.
+export const storeRel = (userConfig.store ?? "docs/.notabene")
+  .replace(/\\/g, "/")
+  .replace(/\/+$/, "");
+export const storeAbs = path.resolve(REPO_ROOT, storeRel);
+
+// Serializable roots for client scripts (no absolute paths / node:* leak).
+export const clientRoots = roots.map((r) => ({
+  key: r.key,
+  label: r.label,
+  path: r.path,
+}));
+
+/**
+ * Logical `page` path (e.g. "docs/plans/services/x") → site route
+ * (e.g. "/workbench/services/x"). Most specific root (longest path) first — a
+ * nested space (docs/plans) must win over its parent (docs).
+ */
+export function routeForPage(page) {
+  const ordered = [...roots].sort((a, b) => b.path.length - a.path.length);
+  for (const r of ordered) {
+    if (page === r.path) return `/${r.key}`;
+    if (page.startsWith(`${r.path}/`)) return `/${r.key}/${page.slice(r.path.length + 1)}`;
+  }
+  return "#";
+}
+
+export default {
+  REPO_ROOT,
+  siteName,
+  tagline,
+  locale,
+  format,
+  mdxEnabled,
+  extensions,
+  port,
+  host,
+  verify,
+  roots,
+  storeRel,
+  storeAbs,
+  clientRoots,
+  routeForPage,
+};

package/src/content.config.ts

@@ -0,0 +1,16 @@
+import { defineCollection } from "astro:content";
+import { glob } from "astro/loaders";
+import { roots } from "./config.mjs";
+
+// Contenu sourcé HORS de l'app (outil de vue par-dessus la doc du repo) : une
+// collection par espace déclaré dans notabene.config.mjs (`roots[]`). Le nom de
+// collection = la `key` de l'espace ; le `base` du glob = son dossier, résolu
+// contre la racine du repo (cf. src/config.mjs). Le glob inclut déjà `.mdx`.
+const collections: Record<string, ReturnType<typeof defineCollection>> = {};
+for (const root of roots) {
+  collections[root.key] = defineCollection({
+    loader: glob({ pattern: root.pattern, base: root.baseUrl }),
+  });
+}
+
+export { collections };

package/src/layouts/DocLayout.astro

@@ -0,0 +1,153 @@
+---
+import "../styles/global.css";
+import Sidebar from "../components/Sidebar.astro";
+import Toc from "../components/Toc.astro";
+import Comments from "../components/Comments.astro";
+import type { Space } from "../lib/nav";
+import { clientRoots, locale, siteName, tagline } from "../config.mjs";
+
+interface Heading {
+  depth: number;
+  slug: string;
+  text: string;
+}
+
+interface Crumb {
+  label: string;
+  href?: string;
+}
+
+interface Props {
+  title: string;
+  current?: string;
+  space?: Space;
+  /** Chemin logique repo-relatif (sans extension) — support Phase 2 commentaires. */
+  page?: string;
+  headings?: Heading[];
+  breadcrumb?: Crumb[];
+}
+
+const { title, current = "", space, page, headings = [], breadcrumb = [] } = Astro.props;
+---
+
+<!doctype html>
+<html lang={locale}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title} · {siteName}</title>
+    <script type="application/json" id="notabene-roots" set:html={JSON.stringify(clientRoots)} />
+  </head>
+  <body>
+    <header class="topbar">
+      <a href="/" class="brand">{siteName} <span>· {tagline}</span></a>
+      <div class="search">
+        <input id="search-input" type="search" placeholder="Search all docs…" autocomplete="off" />
+        <div id="search-results" class="search-results" hidden></div>
+      </div>
+      <a href="/comments" class="topbar-link">Commentaires</a>
+      <a href="/journal" class="topbar-link">Journal</a>
+    </header>
+
+    <div class="shell">
+      <aside class="sidebar">
+        <Sidebar current={current} activeSpace={space} />
+      </aside>
+
+      <main class="content">
+        {
+          breadcrumb.length > 0 && (
+            <nav class="breadcrumb" aria-label="Breadcrumb">
+              {breadcrumb.map((b, i) => (
+                <>
+                  {i > 0 && <span class="sep">/</span>}
+                  {b.href ? <a href={b.href}>{b.label}</a> : <span>{b.label}</span>}
+                </>
+              ))}
+            </nav>
+          )
+        }
+        <article id="doc-content" class="prose" data-space={space} data-page={page}>
+          <slot />
+        </article>
+        <Comments page={page} space={space} />
+      </main>
+
+      <aside class="rail">
+        <Toc headings={headings} />
+        <div id="cmt-rail" class="cmt-rail"></div>
+      </aside>
+    </div>
+
+    <script>
+      // Recherche client-side : index JSON (titre + headings + extrait), scoré.
+      const input = document.getElementById("search-input") as HTMLInputElement | null;
+      const box = document.getElementById("search-results");
+
+      interface Doc {
+        space: string;
+        href: string;
+        title: string;
+        headings: string[];
+        text: string;
+      }
+
+      const ROOTS: { key: string; label: string; path: string }[] = JSON.parse(
+        document.getElementById("notabene-roots")?.textContent || "[]",
+      );
+      const spaceLabel = (key: string): string =>
+        ROOTS.find((r) => r.key === key)?.label ?? key;
+
+      let index: Doc[] | null = null;
+      async function ensureIndex(): Promise<Doc[]> {
+        if (!index) index = await fetch("/search-index.json").then((r) => r.json());
+        return index ?? [];
+      }
+
+      function score(doc: Doc, q: string): number {
+        const t = doc.title.toLowerCase();
+        if (t === q) return 100;
+        if (t.startsWith(q)) return 80;
+        if (t.includes(q)) return 60;
+        if (doc.headings.some((h) => h.toLowerCase().includes(q))) return 30;
+        if (doc.text.toLowerCase().includes(q)) return 10;
+        return 0;
+      }
+
+      function esc(s: string): string {
+        return s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c] ?? c);
+      }
+
+      if (input && box) {
+        input.addEventListener("input", async () => {
+          const q = input.value.trim().toLowerCase();
+          if (!q) {
+            box.hidden = true;
+            box.innerHTML = "";
+            return;
+          }
+          const data = await ensureIndex();
+          const hits = data
+            .map((doc) => ({ doc, s: score(doc, q) }))
+            .filter((x) => x.s > 0)
+            .sort((a, b) => b.s - a.s)
+            .slice(0, 12);
+          box.innerHTML = hits.length
+            ? hits
+                .map(
+                  ({ doc }) =>
+                    `<a href="${doc.href}"><span class="r-space ${doc.space}">${esc(spaceLabel(doc.space))}</span><span class="r-title">${esc(doc.title)}</span></a>`,
+                )
+                .join("")
+            : `<div class="r-empty">No results</div>`;
+          box.hidden = false;
+        });
+
+        document.addEventListener("click", (e) => {
+          const target = e.target as Node;
+          if (!box.contains(target) && target !== input) box.hidden = true;
+        });
+      }
+    </script>
+  </body>
+</html>

package/src/lib/comment-types.ts

@@ -0,0 +1,53 @@
+// Types partagés client ⇄ serveur pour les commentaires (pas d'I/O ici).
+//
+// ⚠️ CONTRAT DE DONNÉES (`.notabene` = API publique). Le store est committé en git
+// et lu par l'agent → sa forme ne peut plus être cassée en douce. Versionné par un
+// sidecar `<store>/meta.json` (`{ "schemaVersion": <n> }`, cf. SCHEMA_VERSION).
+// Toute évolution de forme = bump `schemaVersion` + migrateur, jamais de mutation
+// silencieuse. Cf. docs/plans/docs-review-oss.mdx §9.
+
+/** Version du schéma du store (sidecar `<store>/meta.json`). */
+export const SCHEMA_VERSION = 1;
+
+export interface CommentAnchor {
+  /** Texte exact sélectionné (W3C TextQuoteSelector). */
+  quote: string;
+  /** ~32-40 chars de contexte avant/après (désambiguïse les quotes répétées et
+   *  ancre le ré-ancrage rendu→source — load-bearing, ne pas retirer). */
+  prefix: string;
+  suffix: string;
+  /** Heading le plus proche au-dessus de la sélection (repère lisible). */
+  section: string | null;
+}
+
+export interface CommentReply {
+  author: string;
+  body: string;
+  ts: string;
+}
+
+export type CommentStatus = "open" | "addressed" | "resolved";
+/** Clé d'un espace (root de notabene.config) — chaîne libre, plus le duo figé. */
+export type CommentSpace = string;
+export type CommentScope = "selection" | "page";
+
+export interface Comment {
+  id: string;
+  /** Espace = `key` du root de notabene.config (ex. reference, workbench). */
+  space: CommentSpace;
+  /** Chemin logique repo-relatif de la page (= data-page), ex. docs/architecture/billing. */
+  page: string;
+  scope: CommentScope;
+  /** null pour un commentaire global de page. */
+  anchor: CommentAnchor | null;
+  thread: CommentReply[];
+  status: CommentStatus;
+  /** « En attente » : travail en cours côté utilisateur — l'agent IGNORE ces
+   *  commentaires lors d'une passe « prends en compte » (jusqu'à réactivation). */
+  hold: boolean;
+  /** Rempli par l'agent quand il traite le commentaire. `journalEntryId` lie la
+   *  résolution à l'entrée de `journal.json` qui la décrit (cf. JournalEntry.id). */
+  resolution: { note: string; journalEntryId?: string } | null;
+  createdAt: string;
+  updatedAt: string;
+}

package/src/lib/comments.ts

@@ -0,0 +1,141 @@
+// Store de commentaires (serveur, dev-only). Un fichier JSON par page sous
+// `<store>/<page>.json` (committé en git, lisible par l'agent). Le chemin du store
+// vient de notabene.config (`store`, cf. src/config.mjs) — jamais en dur. Le glob
+// de contenu exclut le store → il n'est jamais interprété comme du contenu.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { storeAbs } from "../config.mjs";
+import type { Comment, CommentAnchor, CommentScope, CommentSpace, CommentStatus } from "./comment-types";
+
+const STORE_ROOT = storeAbs;
+// Fichiers réservés du store (jamais des pages de commentaires).
+const RESERVED = new Set(["journal.json", "meta.json"]);
+
+function fileFor(page: string): string {
+  // Anti-traversal : pas de `..`, pas de slash initial.
+  const safe = page.replace(/\\/g, "/").replace(/\.\.+/g, "").replace(/^\/+/, "");
+  return path.join(STORE_ROOT, `${safe}.json`);
+}
+
+async function read(page: string): Promise<Comment[]> {
+  try {
+    return JSON.parse(await fs.readFile(fileFor(page), "utf8")) as Comment[];
+  } catch {
+    return [];
+  }
+}
+
+async function write(page: string, comments: Comment[]): Promise<void> {
+  const f = fileFor(page);
+  await fs.mkdir(path.dirname(f), { recursive: true });
+  if (comments.length === 0) {
+    await fs.rm(f, { force: true });
+    return;
+  }
+  await fs.writeFile(f, `${JSON.stringify(comments, null, 2)}\n`, "utf8");
+}
+
+function newId(): string {
+  return `c_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+}
+
+export async function listComments(page: string): Promise<Comment[]> {
+  return read(page);
+}
+
+/** Tous les commentaires, toutes pages (pour la page globale /comments). */
+export async function listAllComments(): Promise<Comment[]> {
+  const out: Comment[] = [];
+  async function walk(dir: string) {
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) await walk(full);
+      // Fichiers réservés (journal/meta) au niveau racine du store → ignorés.
+      else if (e.name.endsWith(".json") && !(dir === STORE_ROOT && RESERVED.has(e.name))) {
+        try {
+          out.push(...(JSON.parse(await fs.readFile(full, "utf8")) as Comment[]));
+        } catch {
+          /* ignore fichier illisible */
+        }
+      }
+    }
+  }
+  await walk(STORE_ROOT);
+  return out;
+}
+
+export async function createComment(input: {
+  space: CommentSpace;
+  page: string;
+  scope: CommentScope;
+  anchor: CommentAnchor | null;
+  author?: string;
+  body: string;
+}): Promise<Comment> {
+  const comments = await read(input.page);
+  const now = new Date().toISOString();
+  const comment: Comment = {
+    id: newId(),
+    space: input.space,
+    page: input.page,
+    scope: input.scope,
+    anchor: input.scope === "selection" ? input.anchor : null,
+    thread: [{ author: input.author || "quentin", body: input.body, ts: now }],
+    status: "open",
+    hold: false,
+    resolution: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+  comments.push(comment);
+  await write(input.page, comments);
+  return comment;
+}
+
+export async function patchComment(
+  page: string,
+  id: string,
+  patch: {
+    status?: CommentStatus;
+    hold?: boolean;
+    resolution?: { note: string; journalEntryId?: string } | null;
+    reply?: { author?: string; body: string };
+    edit?: { body: string };
+  },
+): Promise<Comment | null> {
+  const comments = await read(page);
+  const c = comments.find((x) => x.id === id);
+  if (!c) return null;
+  // Édition du message original : autorisée UNIQUEMENT si pas encore traité
+  // (status open) ET sans réponse (thread = 1). Enforcement serveur.
+  if (patch.edit?.body && c.status === "open" && c.thread.length === 1) {
+    c.thread[0].body = patch.edit.body;
+  }
+  if (patch.status) c.status = patch.status;
+  if (patch.hold !== undefined) c.hold = patch.hold;
+  if (patch.resolution !== undefined) c.resolution = patch.resolution;
+  if (patch.reply?.body) {
+    c.thread.push({
+      author: patch.reply.author || "quentin",
+      body: patch.reply.body,
+      ts: new Date().toISOString(),
+    });
+  }
+  c.updatedAt = new Date().toISOString();
+  await write(page, comments);
+  return c;
+}
+
+export async function removeComment(page: string, id: string): Promise<boolean> {
+  const comments = await read(page);
+  const next = comments.filter((x) => x.id !== id);
+  if (next.length === comments.length) return false;
+  await write(page, next);
+  return true;
+}

package/src/lib/icons.ts

@@ -0,0 +1,17 @@
+// Icônes inline (Lucide, MIT) sous forme de chaînes SVG — les cartes de
+// commentaires sont rendues en JS (innerHTML), donc pas de composant Astro ici.
+// Monochromes (stroke = currentColor) → héritent de la couleur du bouton.
+const svg = (inner: string) =>
+  `<svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${inner}</svg>`;
+
+export const ICONS = {
+  check: svg('<path d="M20 6 9 17l-5-5"/>'),
+  reopen: svg('<path d="M1 4v6h6"/><path d="M3.51 15a9 9 0 1 0 2.13-9.36L1 10"/>'),
+  pause: svg('<rect x="14" y="3" width="4" height="18" rx="1"/><rect x="6" y="3" width="4" height="18" rx="1"/>'),
+  play: svg('<polygon points="6 3 20 12 6 21 6 3"/>'),
+  reply: svg('<polyline points="9 17 4 12 9 7"/><path d="M20 18v-2a4 4 0 0 0-4-4H4"/>'),
+  edit: svg('<path d="M12 20h9"/><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z"/>'),
+  trash: svg(
+    '<path d="M3 6h18"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/><line x1="10" x2="10" y1="11" y2="17"/><line x1="14" x2="14" y1="11" y2="17"/>',
+  ),
+};

package/src/lib/journal.ts

@@ -0,0 +1,40 @@
+// Journal des modifications de la doc (serveur, lecture seule côté site).
+// Écrit par l'agent lors d'une passe de revue (édition directe de
+// `<store>/journal.json`), affiché par la page /journal. Chemin du store dérivé
+// de notabene.config (cf. src/config.mjs) — jamais en dur.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { storeAbs } from "../config.mjs";
+
+export interface JournalChange {
+  /** Chemin logique de la page modifiée (= data-page), ex. docs/architecture/billing. */
+  page: string;
+  /** Commentaires traités par cette modification (ids). */
+  commentIds: string[];
+  /** Ce qui a changé. */
+  what: string;
+  /** Pourquoi (issu du commentaire). */
+  why: string;
+  /** Référence optionnelle (sha de commit, etc.). */
+  ref?: string;
+}
+
+export interface JournalEntry {
+  id: string;
+  /** ISO date (YYYY-MM-DD). */
+  date: string;
+  title: string;
+  /** Résumé prose de la passe. */
+  summary: string;
+  changes: JournalChange[];
+}
+
+const JOURNAL_FILE = path.join(storeAbs, "journal.json");
+
+export async function readJournal(): Promise<JournalEntry[]> {
+  try {
+    return JSON.parse(await fs.readFile(JOURNAL_FILE, "utf8")) as JournalEntry[];
+  } catch {
+    return [];
+  }
+}

package/src/lib/nav.ts

@@ -0,0 +1,132 @@
+import { getCollection } from "astro:content";
+import { locale } from "../config.mjs";
+
+// Un espace = la `key` d'un root de notabene.config (plus le duo figé
+// reference/workbench). Chaîne libre.
+export type Space = string;
+
+export interface NavLeaf {
+  type: "leaf";
+  title: string;
+  href: string;
+  segment: string;
+}
+
+export interface NavGroup {
+  type: "group";
+  label: string;
+  segment: string;
+  prefix: string;
+  children: NavNode[];
+}
+
+export type NavNode = NavLeaf | NavGroup;
+
+// Mots à rendre en capitales (acronymes), et petits mots gardés en minuscule.
+const ACRONYMS = new Set([
+  "api", "iam", "dns", "ip", "ips", "url", "ssl", "tls", "ocr", "qr", "mac", "http",
+  "https", "sse", "ws", "id", "ttl", "ssrf", "mx", "smtp", "dnsbl", "dbl", "dnswl",
+  "fcrdns", "csv", "pdf", "svg", "png", "json", "mdx", "wasm", "cli", "vnc", "ha",
+  "db", "s3", "ui", "ux", "seo", "jwt", "mfa", "totp", "rgpd", "gdpr", "ai", "llm",
+  "waf", "ecs", "doh", "do53", "svcb",
+]);
+const SMALL_WORDS = new Set([
+  "and", "or", "of", "the", "a", "an", "de", "du", "des", "la", "le", "les", "et",
+  "à", "pour", "par", "sur", "in",
+]);
+
+export function humanize(seg: string): string {
+  const words = seg
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2") // sépare le camelCase (ex. ipAddress)
+    .split(/[-_\s]+/)
+    .filter(Boolean);
+  return words
+    .map((w, i) => {
+      const lw = w.toLowerCase();
+      if (ACRONYMS.has(lw)) return lw.toUpperCase();
+      if (i > 0 && SMALL_WORDS.has(lw)) return lw;
+      return w.charAt(0).toUpperCase() + w.slice(1).toLowerCase();
+    })
+    .join(" ");
+}
+
+/**
+ * Libellé COURT de navigation = nom de fichier humanisé. Le H1 (souvent verbeux,
+ * pensé pour une lecture standalone) sert au titre de la page, pas à la sidebar.
+ */
+export function navLabel(id: string): string {
+  const seg = id.split("/").pop() ?? id;
+  if (/^(readme|index)$/i.test(seg)) return "Overview";
+  return humanize(seg);
+}
+
+/** Titre de page = premier H1 (descriptif), sinon le libellé de nav. */
+export function pageTitle(body: string | undefined, id: string): string {
+  const m = body?.match(/^#\s+(.+?)\s*$/m);
+  if (m) return m[1].replace(/[*_`]/g, "").trim();
+  return navLabel(id);
+}
+
+async function entriesOf(space: Space) {
+  // Nom de collection = key de l'espace (cf. content.config.ts). Dynamique.
+  return getCollection(space as never);
+}
+
+/** Construit l'arbre de navigation d'un espace à partir des ids slash-séparés. */
+export async function buildNav(space: Space): Promise<NavNode[]> {
+  const entries = await entriesOf(space);
+  const rootChildren: NavNode[] = [];
+
+  for (const entry of entries) {
+    // README/index RACINE = page d'accueil de l'espace, pas une feuille de nav.
+    if (/^(readme|index)$/i.test(entry.id)) continue;
+    const parts = entry.id.split("/");
+    let children = rootChildren;
+
+    for (let i = 0; i < parts.length - 1; i++) {
+      const seg = parts[i];
+      let group = children.find(
+        (c): c is NavGroup => c.type === "group" && c.segment === seg,
+      );
+      if (!group) {
+        group = {
+          type: "group",
+          label: humanize(seg),
+          segment: seg,
+          prefix: `/${space}/${parts.slice(0, i + 1).join("/")}`,
+          children: [],
+        };
+        children.push(group);
+      }
+      children = group.children;
+    }
+
+    children.push({
+      type: "leaf",
+      title: navLabel(entry.id),
+      href: `/${space}/${entry.id}`,
+      segment: parts[parts.length - 1],
+    });
+  }
+
+  sortNodes(rootChildren);
+  return rootChildren;
+}
+
+function rank(node: NavNode): number {
+  // README / index en tête, puis les groupes, puis les autres pages.
+  if (node.type === "leaf" && /^(readme|index)$/i.test(node.segment)) return 0;
+  if (node.type === "group") return 1;
+  return 2;
+}
+
+function sortNodes(nodes: NavNode[]): void {
+  nodes.sort((a, b) => {
+    const r = rank(a) - rank(b);
+    if (r !== 0) return r;
+    const an = a.type === "group" ? a.label : a.title;
+    const bn = b.type === "group" ? b.label : b.title;
+    return an.localeCompare(bn, locale);
+  });
+  for (const n of nodes) if (n.type === "group") sortNodes(n.children);
+}