@z29k/notabene 0.1.0

package/src/pages/[space]/[...slug].astro

@@ -0,0 +1,71 @@
+---
+import { getCollection, render } from "astro:content";
+import DocLayout from "../../layouts/DocLayout.astro";
+import SpaceIndex from "../../components/SpaceIndex.astro";
+import { buildNav, humanize, pageTitle, type NavNode } from "../../lib/nav";
+import { roots } from "../../config.mjs";
+
+export async function getStaticPaths() {
+  const groups = await Promise.all(
+    roots.map(async (root) => {
+      const entries = await getCollection(root.key as never);
+      const docs = entries.map((entry: { id: string }) => ({
+        params: { space: root.key, slug: entry.id },
+        props: { spaceKey: root.key, entry },
+      }));
+      // Page d'accueil de l'espace (slug vide → /<key>).
+      return [...docs, { params: { space: root.key, slug: undefined }, props: { spaceKey: root.key, entry: undefined } }];
+    }),
+  );
+  return groups.flat();
+}
+
+const { spaceKey, entry } = Astro.props;
+const root = roots.find((r) => r.key === spaceKey)!;
+const spaceLabel = root.label;
+const baseDir = root.path;
+
+let Content: Awaited<ReturnType<typeof render>>["Content"] | null = null;
+let headings: { depth: number; slug: string; text: string }[] = [];
+let nodes: NavNode[] = [];
+let page: string | undefined;
+let title = spaceLabel;
+const breadcrumb: { label: string; href?: string }[] = [{ label: spaceLabel, href: `/${spaceKey}` }];
+
+if (entry) {
+  const rendered = await render(entry);
+  Content = rendered.Content;
+  headings = rendered.headings;
+  title = pageTitle(entry.body, entry.id);
+  page = `${baseDir}/${entry.id}`;
+  const parts = entry.id.split("/");
+  for (let i = 0; i < parts.length - 1; i++) breadcrumb.push({ label: humanize(parts[i]) });
+  breadcrumb.push({ label: title });
+} else {
+  // Accueil d'espace : on rend le README/index racine s'il existe, sinon des cartes.
+  const all = await getCollection(spaceKey as never);
+  const readme = all.find((e: { id: string }) => /^(readme|index)$/i.test(e.id));
+  if (readme) {
+    const rendered = await render(readme);
+    Content = rendered.Content;
+    headings = rendered.headings;
+    title = pageTitle(readme.body, readme.id);
+    page = `${baseDir}/${readme.id}`;
+  } else {
+    nodes = await buildNav(spaceKey);
+  }
+}
+
+const current = entry ? `/${spaceKey}/${entry.id}` : `/${spaceKey}`;
+---
+
+<DocLayout
+  title={title}
+  current={current}
+  space={spaceKey}
+  page={page}
+  headings={headings}
+  breadcrumb={entry ? breadcrumb : []}
+>
+  {Content ? <Content /> : <SpaceIndex nodes={nodes} space={spaceKey} />}
+</DocLayout>

package/src/pages/api/comments.ts

@@ -0,0 +1,68 @@
+import type { APIRoute } from "astro";
+import { createComment, listAllComments, listComments, patchComment, removeComment } from "../../lib/comments";
+
+// On-demand (lecture/écriture de fichiers) — pas de prerender.
+export const prerender = false;
+
+const json = (data: unknown, status = 200) =>
+  new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+  });
+
+// GARDE-FOU (§3) : la voie d'écriture (elle modifie le git du repo) n'existe qu'en
+// `astro dev`. En build/preview (PROD), les mutations sont refusées — l'écriture
+// ne fait pas partie de l'artefact déployable. Override explicite : NOTABENE_ALLOW_WRITE=1.
+const WRITABLE = import.meta.env.DEV || process.env.NOTABENE_ALLOW_WRITE === "1";
+const denyIfReadOnly = () =>
+  WRITABLE ? null : json({ error: "read-only: write API disabled outside dev" }, 403);
+
+export const GET: APIRoute = async ({ url }) => {
+  if (url.searchParams.get("all")) return json(await listAllComments());
+  const page = url.searchParams.get("page");
+  if (!page) return json({ error: "page query param required" }, 400);
+  return json(await listComments(page));
+};
+
+export const POST: APIRoute = async ({ request }) => {
+  const denied = denyIfReadOnly();
+  if (denied) return denied;
+  const b = await request.json().catch(() => null);
+  if (!b || !b.page || !b.space || !b.scope || !b.body) {
+    return json({ error: "page, space, scope, body required" }, 400);
+  }
+  const comment = await createComment({
+    space: b.space,
+    page: b.page,
+    scope: b.scope,
+    anchor: b.anchor ?? null,
+    author: b.author,
+    body: b.body,
+  });
+  return json(comment, 201);
+};
+
+export const PATCH: APIRoute = async ({ request }) => {
+  const denied = denyIfReadOnly();
+  if (denied) return denied;
+  const b = await request.json().catch(() => null);
+  if (!b || !b.page || !b.id) return json({ error: "page, id required" }, 400);
+  const updated = await patchComment(b.page, b.id, {
+    status: b.status,
+    hold: b.hold,
+    resolution: b.resolution,
+    reply: b.reply,
+    edit: b.edit,
+  });
+  if (!updated) return json({ error: "not found" }, 404);
+  return json(updated);
+};
+
+export const DELETE: APIRoute = async ({ request }) => {
+  const denied = denyIfReadOnly();
+  if (denied) return denied;
+  const b = await request.json().catch(() => null);
+  if (!b || !b.page || !b.id) return json({ error: "page, id required" }, 400);
+  const ok = await removeComment(b.page, b.id);
+  return json({ deleted: ok }, ok ? 200 : 404);
+};

package/src/pages/comments.astro

@@ -0,0 +1,146 @@
+---
+import DocLayout from "../layouts/DocLayout.astro";
+import { roots } from "../config.mjs";
+---
+
+<DocLayout title="Tous les commentaires">
+  <h1>Tous les commentaires</h1>
+  <p class="lede">Vue agrégée de toute la doc, avec filtres. Clic sur une page → ouvre le commentaire à son emplacement.</p>
+
+  <div class="caf-filters">
+    <input id="caf-search" type="search" placeholder="Rechercher (texte, page, citation)…" />
+    <select id="caf-status">
+      <option value="active">Actifs</option>
+      <option value="open">Open</option>
+      <option value="resolved">Résolus</option>
+      <option value="all">Tous statuts</option>
+    </select>
+    <select id="caf-space">
+      <option value="all">Tous espaces</option>
+      {roots.map((r) => <option value={r.key}>{r.label}</option>)}
+    </select>
+    <select id="caf-hold">
+      <option value="all">Attente : tous</option>
+      <option value="active">Hors attente</option>
+      <option value="hold">En attente</option>
+    </select>
+    <span id="caf-count" class="cmt-count"></span>
+  </div>
+
+  <div id="caf-list" class="caf-list"><p class="cmt-empty">Chargement…</p></div>
+</DocLayout>
+
+<script>
+  import { ICONS } from "../lib/icons";
+
+  interface Anchor { quote: string; prefix: string; suffix: string; section: string | null }
+  interface Reply { author: string; body: string; ts: string }
+  interface Comment {
+    id: string; space: string; page: string; scope: string;
+    anchor: Anchor | null; thread: Reply[]; status: string; hold: boolean;
+    resolution: { note: string; journalEntryId?: string } | null; createdAt: string; updatedAt: 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;
+
+  const listEl = document.getElementById("caf-list")!;
+  const countEl = document.getElementById("caf-count")!;
+  const searchEl = document.getElementById("caf-search") as HTMLInputElement;
+  const statusEl = document.getElementById("caf-status") as HTMLSelectElement;
+  const spaceEl = document.getElementById("caf-space") as HTMLSelectElement;
+  const holdEl = document.getElementById("caf-hold") as HTMLSelectElement;
+
+  let all: Comment[] = [];
+  const esc = (s: string) =>
+    s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c] || c);
+  const api = (method: string, body?: unknown) =>
+    fetch("/api/comments" + (method === "GET" ? "?all=1" : ""), {
+      method,
+      headers: { "content-type": "application/json" },
+      body: body ? JSON.stringify(body) : undefined,
+    }).then((r) => r.json());
+  const fmt = (s: string) => s.slice(0, 16).replace("T", " ");
+  // Root le plus spécifique (path le plus long) d'abord — cf. config.routeForPage.
+  const ROUTE_ROOTS = [...ROOTS].sort((a, b) => b.path.length - a.path.length);
+  function routeFor(page: string): string {
+    for (const r of ROUTE_ROOTS) {
+      if (page === r.path) return `/${r.key}`;
+      if (page.startsWith(`${r.path}/`)) return `/${r.key}/${page.slice(r.path.length + 1)}`;
+    }
+    return "#";
+  }
+
+  function render() {
+    const q = searchEl.value.trim().toLowerCase();
+    const fs = statusEl.value;
+    const fsp = spaceEl.value;
+    const fh = holdEl.value;
+    const rows = all
+      .filter((c) => {
+        if (fsp !== "all" && c.space !== fsp) return false;
+        if (fs === "active" && c.status === "resolved") return false;
+        if (fs === "open" && c.status !== "open") return false;
+        if (fs === "resolved" && c.status !== "resolved") return false;
+        if (fh === "active" && c.hold) return false;
+        if (fh === "hold" && !c.hold) return false;
+        if (q) {
+          const hay = (c.page + " " + (c.anchor?.quote || "") + " " + c.thread.map((t) => t.body).join(" ")).toLowerCase();
+          if (!hay.includes(q)) return false;
+        }
+        return true;
+      })
+      .sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+
+    countEl.textContent = `${rows.length} / ${all.length}`;
+    listEl.innerHTML = rows.length
+      ? rows
+          .map((c) => {
+            const head = c.thread[0];
+            return `<article class="caf-row ${c.status}${c.hold ? " held" : ""}" data-id="${c.id}" data-page="${esc(c.page)}">
+              <div class="caf-row-top">
+                <span class="cmt-dot ${c.status}"></span>
+                <a class="caf-page" href="${routeFor(c.page)}?c=${c.id}">${esc(c.page)}</a>
+                <span class="r-space ${c.space}">${esc(spaceLabel(c.space))}</span>
+                ${c.scope === "selection" ? `<span class="caf-quote">“${esc((c.anchor?.quote || "").slice(0, 60))}”</span>` : `<span class="cmt-scope">📄 page</span>`}
+                ${c.hold ? '<span class="cmt-hold-badge">⏸ en attente</span>' : ""}
+                ${c.thread.length > 1 ? `<span class="caf-replies">${c.thread.length - 1} rép.</span>` : ""}
+              </div>
+              <div class="caf-body"><b>${esc(head.author)}</b> ${esc(head.body)}</div>
+              ${c.resolution?.note ? `<div class="cmt-resolution">✔ ${esc(c.resolution.note)}</div>` : ""}
+              <div class="caf-actions">
+                <span class="cmt-ts">${fmt(c.updatedAt)}</span>
+                ${c.status === "resolved" ? `<button data-act="reopen" title="Rouvrir" aria-label="Rouvrir">${ICONS.reopen}</button>` : `<button data-act="resolve" title="Résoudre" aria-label="Résoudre">${ICONS.check}</button>`}
+                <button data-act="${c.hold ? "unhold" : "hold"}" title="${c.hold ? "Réactiver" : "Mettre en attente"}" aria-label="${c.hold ? "Réactiver" : "Mettre en attente"}">${c.hold ? ICONS.play : ICONS.pause}</button>
+                <button data-act="delete" class="danger" title="Supprimer" aria-label="Supprimer">${ICONS.trash}</button>
+              </div>
+            </article>`;
+          })
+          .join("")
+      : `<p class="cmt-empty">Aucun commentaire pour ces filtres.</p>`;
+  }
+
+  async function load() {
+    all = await api("GET");
+    render();
+  }
+
+  for (const el of [searchEl, statusEl, spaceEl, holdEl]) el.addEventListener("input", render);
+
+  listEl.addEventListener("click", async (e) => {
+    const btn = (e.target as HTMLElement).closest("button[data-act]") as HTMLElement | null;
+    if (!btn) return;
+    const row = btn.closest(".caf-row") as HTMLElement;
+    const id = row.dataset.id!;
+    const page = row.dataset.page!;
+    const act = btn.dataset.act!;
+    if (act === "resolve" || act === "reopen") await api("PATCH", { page, id, status: act === "resolve" ? "resolved" : "open" });
+    else if (act === "hold" || act === "unhold") await api("PATCH", { page, id, hold: act === "hold" });
+    else if (act === "delete") await api("DELETE", { page, id });
+    await load();
+  });
+
+  load();
+</script>

package/src/pages/index.astro

@@ -0,0 +1,23 @@
+---
+import DocLayout from "../layouts/DocLayout.astro";
+import { roots, siteName } from "../config.mjs";
+---
+
+<DocLayout title="Home">
+  <h1>{siteName} documentation</h1>
+  <p class="lede">
+    {roots.length} space{roots.length > 1 ? "s" : ""}, sourced live from the repo.
+  </p>
+
+  <div class="home-cards">
+    {
+      roots.map((root) => (
+        <a class="home-card" href={`/${root.key}`}>
+          <h2>{root.label}</h2>
+          <p><code>{root.subLabel}</code></p>
+          {root.description && <p>{root.description}</p>}
+        </a>
+      ))
+    }
+  </div>
+</DocLayout>

package/src/pages/journal.astro

@@ -0,0 +1,50 @@
+---
+export const prerender = false;
+import DocLayout from "../layouts/DocLayout.astro";
+import { readJournal } from "../lib/journal";
+import { routeForPage as routeFor } from "../config.mjs";
+
+const entries = (await readJournal()).slice().reverse(); // plus récent en premier
+---
+
+<DocLayout title="Journal">
+  <h1>Journal des modifications</h1>
+  <p class="lede">
+    Historique des passes de revue : ce qui a changé dans la doc, et <strong>pourquoi</strong>
+    (lié aux commentaires qui l'ont déclenché).
+  </p>
+
+  {
+    entries.length === 0 ? (
+      <p class="cmt-empty">
+        Aucune passe enregistrée. Quand Claude traite des commentaires, une entrée est ajoutée ici.
+      </p>
+    ) : (
+      <div class="journal">
+        {entries.map((e) => (
+          <section class="journal-entry">
+            <header class="journal-head">
+              <span class="journal-date">{e.date}</span>
+              <h2>{e.title}</h2>
+            </header>
+            <p class="journal-summary">{e.summary}</p>
+            <ul class="journal-changes">
+              {e.changes.map((c) => (
+                <li>
+                  <a href={routeFor(c.page)} class="journal-page">
+                    {c.page}
+                  </a>
+                  <span class="journal-what"> — {c.what}</span>
+                  <div class="journal-why">{c.why}</div>
+                  {c.commentIds.length > 0 && (
+                    <div class="journal-cids">commentaires : {c.commentIds.join(", ")}</div>
+                  )}
+                </li>
+              ))}
+            </ul>
+          </section>
+        ))}
+      </div>
+    )
+  }
+</DocLayout>

package/src/pages/search-index.json.ts

@@ -0,0 +1,49 @@
+import type { APIRoute } from "astro";
+import { getCollection } from "astro:content";
+import { roots } from "../config.mjs";
+
+/** Markdown → texte brut approximatif (pour l'index de recherche). */
+function strip(md: string): string {
+  return md
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`[^`]*`/g, " ")
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, " ")
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/^[#>|]+/gm, " ")
+    .replace(/[*_~]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export const GET: APIRoute = async () => {
+  const out: {
+    space: string;
+    href: string;
+    title: string;
+    headings: string[];
+    text: string;
+  }[] = [];
+
+  for (const root of roots) {
+    const space = root.key;
+    const entries = await getCollection(space as never);
+    for (const entry of entries) {
+      const body = entry.body ?? "";
+      const titleMatch = body.match(/^#\s+(.+?)\s*$/m);
+      const headings = [...body.matchAll(/^#{2,4}\s+(.+?)\s*$/gm)].map((m) =>
+        m[1].replace(/[*_`]/g, "").trim(),
+      );
+      out.push({
+        space,
+        href: `/${space}/${entry.id}`,
+        title: titleMatch ? titleMatch[1].replace(/[*_`]/g, "").trim() : entry.id,
+        headings,
+        text: strip(body).slice(0, 1500),
+      });
+    }
+  }
+
+  return new Response(JSON.stringify(out), {
+    headers: { "content-type": "application/json; charset=utf-8" },
+  });
+};

package/src/remark/rewrite-links.mjs

@@ -0,0 +1,63 @@
+import path from "node:path";
+
+// Réécrit les liens RELATIFS vers des fichiers .md/.mdx (entre docs) en routes du
+// site. Sans ça, les liens inter-doc (`[x](../foo.md)`) pointent vers des fichiers
+// et donnent des 404 dans le site.
+//
+//   <root.path>/**  → /<root.key>/<slug>
+//
+// Générique : la table de correspondance vient des `roots[]` de notabene.config
+// (cf. src/config.mjs), pas de chemins en dur. Les liens externes (http…, mailto),
+// absolus (/…), ancres (#…) et non-.md sont laissés intacts. Les cibles .md HORS
+// des espaces déclarés sont laissées telles quelles.
+
+function slug(rel) {
+  return rel.replace(/\\/g, "/").replace(/\.mdx?$/i, "");
+}
+
+function visit(node, fn) {
+  fn(node);
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) visit(child, fn);
+  }
+}
+
+/**
+ * @param {{ key: string, abs: string }[]} roots — espaces normalisés (config.mjs).
+ */
+export function remarkRewriteLinks(roots) {
+  // Root le plus spécifique (chemin absolu le plus long) d'abord : un espace
+  // imbriqué (docs/plans) doit gagner sur son parent (docs).
+  const ordered = [...roots].sort((a, b) => b.abs.length - a.abs.length);
+
+  function toRoute(abs) {
+    for (const r of ordered) {
+      if (abs === r.abs || abs.startsWith(r.abs + path.sep)) {
+        return `/${r.key}/${slug(path.relative(r.abs, abs))}`;
+      }
+    }
+    return null;
+  }
+
+  return (tree, file) => {
+    const from = file?.path ?? file?.history?.[0];
+    if (!from) return;
+    const fromDir = path.dirname(from);
+
+    visit(tree, (node) => {
+      if (node.type !== "link" && node.type !== "definition") return;
+      const url = node.url;
+      if (typeof url !== "string") return;
+      if (/^[a-z]+:/i.test(url) || url.startsWith("/") || url.startsWith("#")) return;
+
+      const hashIdx = url.indexOf("#");
+      const target = hashIdx === -1 ? url : url.slice(0, hashIdx);
+      const hash = hashIdx === -1 ? "" : url.slice(hashIdx);
+      if (!/\.mdx?$/i.test(target)) return;
+
+      const abs = path.resolve(fromDir, target);
+      const route = toRoute(abs);
+      if (route) node.url = route + hash;
+    });
+  };
+}