@conduction/docusaurus-preset 3.25.0 → 3.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conduction/docusaurus-preset",
-  "version": "3.25.0",
+  "version": "3.26.0",
   "scripts": {
     "prepack": "node scripts/prepack-bundle-css.js"
   },

package/src/components/FeatureGrid/FeatureGrid.module.css

@@ -70,8 +70,11 @@
   background: var(--c-mint-500);
   flex-shrink: 0;
 }
-.beta { background: var(--c-cobalt-500); }
-.soon { background: var(--c-orange-knvb); }
+/* Compound selectors (.h.beta / .h.soon) so the status colour always wins
+   over the default .h mint, regardless of how the CSS minifier reorders or
+   merges the single-class rules in the bundle. */
+.h.beta { background: var(--c-cobalt-500); }
+.h.soon { background: var(--c-orange-knvb); }
 
 .label {
   flex: 1;

package/src/components/FeaturesPage/FeaturesPage.jsx

@@ -1,47 +1,70 @@
 /**
  * <FeaturesPage />
  *
- * Route component used by the `conduction-features-page` plugin. Renders
- * the list of implemented/reviewed capabilities extracted from
- * `openspec/specs/` into `docs/features.json` (regenerated by the
- * org-wide Features Extract workflow stage).
+ * Route component used by the `conduction-features-page` plugin. Renders the
+ * app's commercial capability list, sourced (in priority order) from a curated
+ * `openspec/features.overlay.json` or, as a fallback, hardened spec derivation
+ * from `openspec/specs/` (see plugins/extractFeatures.js).
  *
- * Reuses the brand `<FeatureGrid>` for the actual list — every entry maps
- * to a single `<FeatureItem>` with status `stable` (the extractor only
- * emits specs whose frontmatter declares `implemented` or `reviewed`,
- * both of which are stable by definition).
+ * Each entry maps to a single `<FeatureItem>` inside `<FeatureGrid>`, coloured
+ * by its maturity: stable (mint), beta (blue), soon (orange).
+ *
+ * Locale-aware: on the Dutch site each entry shows `title_nl` / `summary_nl`
+ * when present, falling back to the English `title` / `summary`. A
+ * `providedBy` capability (e.g. surfaced from OpenRegister) is credited inline
+ * so cross-app functionality reads as real and attributed.
  *
  * Receives one prop module from the plugin via `addRoute({modules})`:
  *
  *   data: {
- *     features: Array<{slug, title, summary, docsUrl}>,
+ *     features: Array<{slug,title,summary,status,docsUrl,providedBy?,title_nl?,summary_nl?}>,
  *     title:    string,
  *     intro:    string | null,
  *   }
- *
- * Sites that want a different page chrome can swizzle the plugin route
- * to register their own component; this default is intentionally minimal
- * (one heading, one optional intro paragraph, the grid).
  */
 
 import React from 'react';
 import Layout from '@theme/Layout';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import FeatureGrid from '../FeatureGrid/FeatureGrid.jsx';
 
+// Display name + localized "powered by" lead-in for a providedBy app id.
+const PROVIDER_NAMES = {
+  openregister: 'OpenRegister',
+  opencatalogi: 'OpenCatalogi',
+  openconnector: 'OpenConnector',
+  docudesk: 'DocuDesk',
+  nldesign: 'NLDesign',
+};
+
+function providerCredit(providedBy, locale) {
+  if (!providedBy) return '';
+  const name = PROVIDER_NAMES[String(providedBy).toLowerCase()] || providedBy;
+  return locale === 'nl' ? `Draait op ${name}.` : `Powered by ${name}.`;
+}
+
 export default function FeaturesPage({data}) {
   const {features = [], title = 'Features', intro = null} = data || {};
+  const {i18n} = useDocusaurusContext();
+  const locale = (i18n && i18n.currentLocale) || 'en';
 
-  const items = features.map((f) => ({
-    label: f.title || f.slug,
-    tip: f.summary || '',
-    status: f.status || 'stable',
-    href: f.docsUrl || undefined,
-  }));
+  const items = features.map((f) => {
+    const label = (locale === 'nl' && f.title_nl) || f.title || f.slug;
+    const summary = (locale === 'nl' && f.summary_nl) || f.summary || '';
+    const credit = providerCredit(f.providedBy, locale);
+    const tip = [summary, credit].filter(Boolean).join(' ');
+    return {
+      label,
+      tip,
+      status: f.status || 'stable',
+      href: f.docsUrl || undefined,
+    };
+  });
 
   return (
     <Layout
       title={title}
-      description={intro || `Capabilities shipped in this app, sourced from openspec/specs/.`}
+      description={intro || `Capabilities shipped in this app.`}
     >
       <main className="container margin-vert--lg">
         <h1>{title}</h1>

package/src/plugins/extractFeatures.js

@@ -3,19 +3,26 @@
  *
  * Build-time port of the org-wide `scripts/extract-features.py`
  * (https://codeberg.org/Conduction/.github). Derives the published feature
- * list directly from an app's `openspec/specs/<slug>/spec.md` files so the
- * docs `/features` page is ALWAYS generated from the current specs — the
- * committed `docs/features.json` is no longer a hand-maintained source of
- * truth that can drift.
+ * list for the docs `/features` page from two sources, in priority order:
  *
- * Only specs whose YAML frontmatter declares `status: done` are emitted
- * (the canonical "shipped" status). Each entry: { slug, title, summary,
- * docsUrl } — identical shape and ordering (sorted by slug) to the Python
- * extractor, so docs output matches CI output byte-for-byte.
+ *   1. Commercial overlay — `openspec/features.overlay.json` (optional). When
+ *      present it is the AUTHORITATIVE curated list: honest maturity,
+ *      brand-voiced NL/EN benefit copy, roadmap rows, and capabilities
+ *      provided by another app (e.g. OpenRegister's AI assistants and content
+ *      leaves surfaced through a consuming app, via `providedBy`).
+ *   2. Spec derivation (fallback) — `openspec/specs/<slug>/spec.md`. Hardened:
+ *      internal/process specs are filtered out, engineering artifacts
+ *      (`@e2e`, `#<pr>`, `Spec:`, em-dashes, `TBD`) are stripped, and optional
+ *      frontmatter fields (`commercial`, `maturity`, `title`, `summary`,
+ *      `provided-by`, `*_nl`) let an author curate without an overlay.
  *
- * Returns null when the directory is absent or holds no done specs, so the
- * caller can fall back to a committed file on deploys that ship without
- * `openspec/`.
+ * Maturity is one of stable (mint) / beta (blue) / soon (orange). Each entry:
+ * { slug, title, summary, status, docsUrl } plus optional { providedBy,
+ * title_nl, summary_nl }. Overlay order is preserved; spec-derived entries are
+ * sorted by slug. Mirrors the Python extractor so docs output matches CI.
+ *
+ * Returns null when nothing is available, so the caller can fall back to a
+ * committed `docs/features.json` on deploys shipped without `openspec/`.
  */
 
 const fs = require('fs');
@@ -24,14 +31,16 @@ const path = require('path');
 const FRONTMATTER_RE = /^---\s*\n([\s\S]*?\n)---\s*\n([\s\S]*)$/;
 const SLUGGY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)+$/;
 
-// Map a spec's frontmatter status to a roadmap kind: stable (mint),
-// beta (cobalt blue), soon (orange). Unmapped statuses are skipped.
+// Fallback map: spec lifecycle status -> buyer-facing maturity. Used only when
+// a spec has no explicit `maturity:` and the app has no overlay.
 const STATUS_KIND = {
   done: 'stable', implemented: 'stable', reviewed: 'stable', active: 'stable', stable: 'stable',
   'in-progress': 'beta', implementing: 'beta', partial: 'beta', beta: 'beta',
   draft: 'soon', specified: 'soon', proposed: 'soon', planned: 'soon', 'coming-soon': 'soon', soon: 'soon',
 };
 
+const VALID_MATURITY = new Set(['stable', 'beta', 'soon']);
+
 const ACRONYMS = new Set([
   'ai', 'api', 'ui', 'ux', 'or', 'bi', 'mcp', 'tmlo', 'mdto', 'dcat', 'woo',
   'vth', 'kcc', 'crm', 'pdf', 'csv', 'sepa', 'zgw', 'ztc', 'dso', 'rbac',
@@ -40,6 +49,31 @@ const ACRONYMS = new Set([
   'pwa', 'sip', 'eml', 'sla', 'llm', 'rag', 'e2e', 'qr', 'vng',
 ]);
 
+// Slug segments that mark an internal/process spec (filtered unless the spec
+// sets `commercial: true` or an overlay re-includes it).
+const INTERNAL_SEGMENTS = new Set([
+  'refactor', 'refactoring', 'migrate', 'migration', 'migrations', 'migrated',
+  'test', 'tests', 'testing', 'e2e', 'ci', 'cd', 'docs', 'documentation',
+  'manifest', 'plumbing', 'scaffold', 'scaffolding', 'bootstrap', 'chore',
+  'cleanup', 'rename', 'renaming', 'bump', 'deps', 'dependency',
+  'dependencies', 'lint', 'linting', 'coverage', 'gate', 'gates', 'seed',
+  'seeding', 'fixture', 'fixtures', 'spike', 'poc', 'tooling', 'devx',
+  'internal',
+]);
+
+function field(front, key) {
+  const re = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:\\s*(.+?)\\s*$`, 'm');
+  const m = front.match(re);
+  if (!m) return null;
+  return m[1].trim().replace(/^["']|["']$/g, '');
+}
+
+function boolField(front, key) {
+  const raw = field(front, key);
+  if (raw === null) return null;
+  return ['true', 'yes', '1'].includes(raw.trim().toLowerCase());
+}
+
 function titlecaseSlug(slug) {
   return slug
     .split('-')
@@ -47,12 +81,53 @@ function titlecaseSlug(slug) {
     .join(' ');
 }
 
+function stripArtifacts(text) {
+  if (!text) return '';
+  let t = text;
+  t = t.replace(/@e2e\b[^\n.]*/gi, '');
+  t = t.replace(/\(?#\d+\)?/g, '');
+  t = t.replace(/\b(?:delta\s+)?spec:\s*/gi, '');
+  t = t.replace(/`/g, '');
+  t = t.replace(/\s*--\s*/g, ', ');
+  t = t.replace(/\s*[—]\s*/g, '. ');
+  t = t.replace(/\b(?:TODO|TBD)\b/gi, '');
+  t = t.replace(/\s+/g, ' ');
+  t = t.replace(/\s+([.,;:])/g, '$1');
+  t = t.replace(/\.\s*\./g, '.');
+  return t.replace(/^[\s.,;:-]+|[\s.,;:-]+$/g, '');
+}
+
 function cleanTitle(rawTitle, slug) {
-  let title = rawTitle.replace(/^\s*spec:\s*/i, '').replace(/\s+specification\s*$/i, '').trim();
+  let title = rawTitle.replace(/^\s*(?:delta\s+)?spec:\s*/i, '').replace(/\s+specification\s*$/i, '').trim();
+  title = stripArtifacts(title);
+  title = title.split('. ')[0].trim().replace(/\.$/, '');
   if (!title || title === slug || SLUGGY_RE.test(title)) title = titlecaseSlug(slug);
   return title;
 }
 
+function firstSentence(summary) {
+  let s = stripArtifacts(summary);
+  if (!s) return '';
+  const m = s.match(/^as an? .*? so that (.+)$/i);
+  if (m) s = m[1].trim();
+  s = s.split('. ')[0].trim();
+  if (!s || ['tbd', 'todo', 'purpose'].includes(s.toLowerCase())) return '';
+  s = s.charAt(0).toUpperCase() + s.slice(1);
+  if (!s.endsWith('.')) s += '.';
+  return s;
+}
+
+function isInternalSlug(slug) {
+  return slug.split('-').some((seg) => INTERNAL_SEGMENTS.has(seg));
+}
+
+function attachOptional(entry, providedBy, titleNl, summaryNl) {
+  if (providedBy) entry.providedBy = providedBy;
+  if (titleNl) entry.title_nl = titleNl;
+  if (summaryNl) entry.summary_nl = summaryNl;
+  return entry;
+}
+
 function parseSpec(specPath, slug) {
   let text;
   try {
@@ -60,45 +135,108 @@ function parseSpec(specPath, slug) {
   } catch (e) {
     return null;
   }
-
   const fm = FRONTMATTER_RE.exec(text);
   if (fm === null) return null;
   const front = fm[1];
   const body = fm[2];
 
-  const statusMatch = front.match(/^status:\s*(.+?)\s*$/m);
-  const status = statusMatch ? statusMatch[1].trim().replace(/^["']|["']$/g, '').toLowerCase() : '';
-  const kind = STATUS_KIND[status];
+  const commercial = boolField(front, 'commercial');
+  if (commercial === false) return null;
+
+  const status = (field(front, 'status') || '').toLowerCase();
+  const maturity = (field(front, 'maturity') || '').toLowerCase();
+  let kind = VALID_MATURITY.has(maturity) ? maturity : STATUS_KIND[status];
+  if (!kind) kind = commercial === true ? 'beta' : null;
   if (!kind) return null;
 
-  const titleMatch = body.match(/^#\s+(.+?)\s*$/m);
-  const rawTitle = titleMatch ? titleMatch[1].trim() : slug;
-  const title = cleanTitle(rawTitle, slug);
+  if (isInternalSlug(slug) && commercial !== true) return null;
+
+  const titleOverride = field(front, 'title');
+  let title;
+  if (titleOverride) {
+    title = stripArtifacts(titleOverride) || titlecaseSlug(slug);
+  } else {
+    const titleMatch = body.match(/^#\s+(.+?)\s*$/m);
+    const rawTitle = titleMatch ? titleMatch[1].trim() : slug;
+    title = cleanTitle(rawTitle, slug);
+  }
 
+  const summaryOverride = field(front, 'summary') || field(front, 'tagline');
   let summary = '';
-  const purposeHeading = body.match(/^##\s+Purpose\s*$/m);
-  if (purposeHeading) {
-    const rest = body.slice(purposeHeading.index + purposeHeading[0].length);
-    const nextHeadingIdx = rest.search(/\n##\s/);
-    const section = (nextHeadingIdx === -1 ? rest : rest.slice(0, nextHeadingIdx)).trim();
-    const firstPara = section.split(/\n\s*\n/)[0] || '';
-    summary = firstPara.trim().split(/\s+/).join(' ');
+  if (summaryOverride) {
+    summary = firstSentence(summaryOverride);
+  } else {
+    const purposeHeading = body.match(/^##\s+Purpose\s*$/m);
+    if (purposeHeading) {
+      const rest = body.slice(purposeHeading.index + purposeHeading[0].length);
+      const nextHeadingIdx = rest.search(/\n##\s/);
+      const section = (nextHeadingIdx === -1 ? rest : rest.slice(0, nextHeadingIdx)).trim();
+      const firstPara = section.split(/\n\s*\n/)[0] || '';
+      summary = firstSentence(firstPara);
+    }
   }
 
-  return {
+  const entry = {
     slug,
     title,
     summary,
     status: kind,
     docsUrl: `openspec/specs/${slug}/spec.md`,
   };
+  return attachOptional(
+    entry,
+    field(front, 'provided-by') || field(front, 'providedBy'),
+    field(front, 'title_nl'),
+    firstSentence(field(front, 'summary_nl') || field(front, 'tagline_nl') || ''),
+  );
+}
+
+function normalizeOverlayEntry(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  let slug = String(raw.slug || '').trim();
+  let status = String(raw.status || '').trim().toLowerCase();
+  if (!VALID_MATURITY.has(status)) status = STATUS_KIND[status] || 'stable';
+  const title = String(raw.title || '').trim() || (slug ? titlecaseSlug(slug) : '');
+  if (!title) return null;
+  if (!slug) slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const entry = {
+    slug,
+    title,
+    summary: String(raw.summary || '').trim(),
+    status,
+    docsUrl: String(raw.docsUrl || `openspec/specs/${slug}/spec.md`),
+  };
+  return attachOptional(
+    entry,
+    raw.providedBy,
+    raw.title_nl ? String(raw.title_nl).trim() : null,
+    raw.summary_nl ? String(raw.summary_nl).trim() : null,
+  );
+}
+
+function loadOverlay(specsDir) {
+  const overlayPath = path.resolve(specsDir, '..', 'features.overlay.json');
+  let data;
+  try {
+    if (!fs.statSync(overlayPath).isFile()) return null;
+    data = JSON.parse(fs.readFileSync(overlayPath, 'utf8'));
+  } catch (e) {
+    return null;
+  }
+  const rawList = Array.isArray(data) ? data : (data && data.features);
+  if (!Array.isArray(rawList)) return null;
+  const entries = rawList.map(normalizeOverlayEntry).filter((e) => e !== null);
+  return entries.length > 0 ? entries : null;
 }
 
 /**
  * @param {string} specsDir Absolute path to `<app>/openspec/specs`.
- * @returns {Array<{slug,title,summary,docsUrl}>|null}
+ * @returns {Array<object>|null}
  */
 function extractFeatures(specsDir) {
+  const overlay = loadOverlay(specsDir);
+  if (overlay !== null) return overlay;
+
   let slugs;
   try {
     if (!fs.statSync(specsDir).isDirectory()) return null;
@@ -124,4 +262,4 @@ function extractFeatures(specsDir) {
   return entries.length > 0 ? entries : null;
 }
 
-module.exports = { extractFeatures };
+module.exports = {extractFeatures};