@nusoft/nuos-build-catalogue 0.26.0 → 0.27.0

package/dist/render/surfaces.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Render the `ui-ux/` register as a single companion HTML page.
+ *
+ * Output structure:
+ *   1. Sitemap — every surface listed (linked to its card lower down), grouped
+ *      where possible by the persona handle it serves.
+ *   2. Surface cards — one per surface markdown file, showing type, persona, the
+ *      "What they see" prose, primary actions, contracts touched, design-system
+ *      pieces used.
+ *
+ * The intent is the human-reviewable artefact the markdown can't be:
+ * a non-developer scanning the whole UI surface set in one scroll.
+ */
+export interface SurfaceRenderResult {
+    written: boolean;
+    outPath: string;
+    surfaceCount: number;
+}
+export declare function renderSurfaces(opts: {
+    buildRoot: string;
+    projectName: string;
+    generatedAt: string;
+}): Promise<SurfaceRenderResult>;

package/dist/render/surfaces.js

@@ -0,0 +1,144 @@
+/**
+ * Render the `ui-ux/` register as a single companion HTML page.
+ *
+ * Output structure:
+ *   1. Sitemap — every surface listed (linked to its card lower down), grouped
+ *      where possible by the persona handle it serves.
+ *   2. Surface cards — one per surface markdown file, showing type, persona, the
+ *      "What they see" prose, primary actions, contracts touched, design-system
+ *      pieces used.
+ *
+ * The intent is the human-reviewable artefact the markdown can't be:
+ * a non-developer scanning the whole UI surface set in one scroll.
+ */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseSections, firstParagraph, isPlaceholder, } from './parser.js';
+import { pageWrapper, card, emptyState, escapeHtml, renderProse, renderInlineMarkdown, } from './html.js';
+const SKIP_FILES = new Set(['_index.md', 'surface-template.md']);
+export async function renderSurfaces(opts) {
+    const dir = path.join(opts.buildRoot, 'ui-ux');
+    const outPath = path.join(dir, '_view.html');
+    if (!existsSync(dir)) {
+        return { written: false, outPath, surfaceCount: 0 };
+    }
+    const surfaces = await loadSurfaces(dir);
+    const body = renderBody(surfaces);
+    const html = pageWrapper({
+        title: 'Surfaces & sitemap',
+        projectName: opts.projectName,
+        generatedAt: opts.generatedAt,
+        sourceNote: '<code>docs/build/ui-ux/</code>',
+        body,
+    });
+    await mkdir(dir, { recursive: true });
+    await writeFile(outPath, html, 'utf8');
+    return { written: true, outPath, surfaceCount: surfaces.length };
+}
+async function loadSurfaces(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const surfaces = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (SKIP_FILES.has(entry.name))
+            continue;
+        const filePath = path.join(dir, entry.name);
+        const md = await readFile(filePath, 'utf8');
+        if (isPlaceholder(md))
+            continue;
+        surfaces.push(parseSurface(entry.name, md));
+    }
+    surfaces.sort((a, b) => a.title.localeCompare(b.title));
+    return surfaces;
+}
+function parseSurface(file, md) {
+    const sections = parseSections(md);
+    const preamble = sections.get('') ?? '';
+    const titleMatch = md.match(/^#\s+(.+)$/m);
+    return {
+        file,
+        slug: file.replace(/\.md$/, ''),
+        title: titleMatch ? titleMatch[1].trim() : file,
+        type: extractMetadata(preamble, 'Type'),
+        status: extractMetadata(preamble, 'Status'),
+        personaRefs: extractPersonaRefs(sections.get('Who uses this surface') ?? ''),
+        sections,
+    };
+}
+function extractMetadata(preamble, key) {
+    const re = new RegExp(`\\*\\*${key}:\\*\\*\\s*(.+)`, 'i');
+    const m = preamble.match(re);
+    return m ? m[1].trim() : null;
+}
+function extractPersonaRefs(body) {
+    const out = [];
+    const re = /P\d{3}/g;
+    let m;
+    while ((m = re.exec(body)) !== null)
+        out.push(m[0]);
+    return Array.from(new Set(out));
+}
+function renderBody(surfaces) {
+    if (surfaces.length === 0) {
+        return card('No surfaces filed yet', emptyState('Phase C of planning produces this content. Once surfaces are filed in docs/build/ui-ux/, this view will render them.'));
+    }
+    return [renderSitemap(surfaces), ...surfaces.map(renderSurfaceCard)].join('\n');
+}
+function renderSitemap(surfaces) {
+    const groups = new Map();
+    for (const s of surfaces) {
+        const key = s.personaRefs.length > 0 ? s.personaRefs.join(', ') : '(no persona linked)';
+        const bucket = groups.get(key) ?? [];
+        bucket.push(s);
+        groups.set(key, bucket);
+    }
+    const sections = [...groups.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([persona, group]) => {
+        const items = group
+            .map((s) => {
+            const typeTag = s.type ? ` <span class="tag">${escapeHtml(s.type)}</span>` : '';
+            return `<li><a href="#${escapeHtml(s.slug)}">${escapeHtml(s.title)}</a>${typeTag}</li>`;
+        })
+            .join('');
+        return `<h4>${escapeHtml(persona)}</h4><ul class="sitemap-list">${items}</ul>`;
+    })
+        .join('');
+    return card('Sitemap', sections);
+}
+function renderSurfaceCard(s) {
+    const tags = [];
+    if (s.type)
+        tags.push(`<span class="tag">${escapeHtml(s.type)}</span>`);
+    if (s.status)
+        tags.push(`<span class="tag tag--status">${escapeHtml(s.status)}</span>`);
+    for (const ref of s.personaRefs)
+        tags.push(`<span class="tag">${escapeHtml(ref)}</span>`);
+    const headerTags = tags.length > 0 ? `<div class="card__tags">${tags.join(' ')}</div>` : '';
+    const sectionBlocks = [headerTags];
+    for (const [heading, body] of s.sections) {
+        if (heading === '' || heading.toLowerCase() === 'notes')
+            continue;
+        if (heading === 'Open questions about this surface' && !body.trim())
+            continue;
+        const rendered = body.trim() ? renderProse(body) : '';
+        if (!rendered)
+            continue;
+        sectionBlocks.push(`<h4>${escapeHtml(heading)}</h4>${rendered}`);
+    }
+    // Best-effort wireframe: render the first paragraph of "What they see" as a
+    // hint label inside a skeletal frame. Not a real wireframe — a signal that
+    // this is a surface and roughly what it contains.
+    const seen = s.sections.get('What they see') ?? '';
+    const hint = firstParagraph(seen);
+    const wireframe = hint
+        ? `<div class="wireframe"><div class="wireframe__label">${renderInlineMarkdown(hint).slice(0, 240)}</div></div>`
+        : '';
+    return `<section id="${escapeHtml(s.slug)}" class="card">
+    <h3>${escapeHtml(s.title)}</h3>
+    ${wireframe}
+    <div class="card__body">${sectionBlocks.join('')}</div>
+  </section>`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "prepublishOnly": "npm run build",
     "verify-storage": "tsx scripts/verify-persistence.ts",
-    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/mode.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts",
+    "test": "tsx --test tests/chunk.test.ts tests/metadata.test.ts tests/crawl.test.ts tests/migrate.test.ts tests/commands-read.test.ts tests/regenerate.test.ts tests/commands-write.test.ts tests/ac-parse.test.ts tests/create.test.ts tests/init.test.ts tests/wu-111-soak-findings.test.ts tests/plan.test.ts tests/mode.test.ts tests/render.test.ts tests/swarm.test.ts tests/setup-progress-bar.test.ts tests/setup-ollama-pull.test.ts tests/setup-run-llm-setup.test.ts tests/wu-active.test.ts tests/install-claude-hooks.test.ts",
     "typecheck": "tsc --noEmit",
     "index": "tsx src/cli.ts index",
     "search": "tsx src/cli.ts search"

package/templates/agents/coder.md

@@ -38,15 +38,17 @@ If anything in the work unit is ambiguous, **stop and surface the ambiguity to t
 
 1. **Plan the change in your head first**, then state it in 1-2 sentences before writing code. Match existing code idioms; don't introduce new patterns the project hasn't adopted.
 
-2. **Make the smallest change that satisfies the work unit's acceptance criteria.** Don't refactor adjacent code "while you're there" unless the work unit explicitly asks for it.
+2. **Search before writing (DRY — strict).** Before adding any new helper, utility, type, component, hook, validator, query, styled primitive, or constant: grep the codebase for one that already does the job — by name (the noun you'd naturally call it), by shape (signature, prop list, structural pattern), and in the conventional locations for the stack (`lib/`, `utils/`, `hooks/`, `components/`, `types/`, `db/queries/`, `schemas/`, equivalents). If found, import and use it (extend in-place if it needs a small addition). If close-but-not-quite, **stop and surface to the coordinator** — extending the existing thing is almost always cheaper than spawning a parallel implementation. This rule applies to new code in *this* WU; pre-existing duplication elsewhere is a follow-up to file, not your job. Search-and-reuse only — this is *not* a directive to extract net-new abstractions; the rule against premature abstraction (point 4) still applies.
 
-3. **Write code that the tester can verify.** Every acceptance criterion in the work unit should be checkable by looking at the running system — your code should make that easy.
+3. **Make the smallest change that satisfies the work unit's acceptance criteria.** Don't refactor adjacent code "while you're there" unless the work unit explicitly asks for it.
 
-4. **Avoid speculative abstractions.** Three similar lines of code beats a premature abstraction. Don't design for hypothetical future requirements. The architect designs; you implement what's needed now.
+4. **Write code that the tester can verify.** Every acceptance criterion in the work unit should be checkable by looking at the running system — your code should make that easy.
 
-5. **No comments unless WHY is non-obvious.** A hidden constraint, a workaround for a specific bug, behaviour that would surprise a reader. If removing the comment wouldn't confuse a future reader, don't write it.
+5. **Avoid speculative abstractions.** Three similar lines of code beats a premature abstraction. Don't design for hypothetical future requirements. The architect designs; you implement what's needed now.
 
-6. **Write testable code (vitest gate).** If `methodfile.json` declares `testing.framework: "vitest"` with `testing.enforced: true`, every source file you create or substantially modify in this WU must end up covered by at least one vitest test — the tester writes them, but your job is to make that cheap. Export the units the tester needs to reach; avoid burying observable logic inside untestable closures; keep side effects at the edges. Files that genuinely can't be unit-tested (pure type declarations, config glue) are fine — flag them in your notes so the reviewer doesn't treat them as drift.
+6. **No comments unless WHY is non-obvious.** A hidden constraint, a workaround for a specific bug, behaviour that would surprise a reader. If removing the comment wouldn't confuse a future reader, don't write it.
+
+7. **Write testable code (vitest gate).** If `methodfile.json` declares `testing.framework: "vitest"` with `testing.enforced: true`, every source file you create or substantially modify in this WU must end up covered by at least one vitest test — the tester writes them, but your job is to make that cheap. Export the units the tester needs to reach; avoid burying observable logic inside untestable closures; keep side effects at the edges. Files that genuinely can't be unit-tested (pure type declarations, config glue) are fine — flag them in your notes so the reviewer doesn't treat them as drift.
 
 ## When you finish
 

package/templates/agents/reviewer.md

@@ -46,13 +46,15 @@ nuos-catalogue memory store --value="<the pattern and why it matters>" --wu=<han
 
 4. **Does it match existing code idioms?** New patterns introduced without justification are a yellow flag — surface them to the coordinator as either "rename to match existing X" or "intentional, file as new pattern in architecture/".
 
-5. **Does it surface or hide changes future work needs to know?** If the coder modified an interface that downstream work depends on, the change should be in a decision file or a contract update — not silent.
+5. **Does new code reinvent something the codebase already has? (DRY — strict.)** For each new helper, utility, type, component, hook, validator, query, styled primitive, or constant the coder added in this WU, grep the codebase for an existing implementation that does the same job — by name, by signature/shape, and in the conventional locations for the stack (`lib/`, `utils/`, `hooks/`, `components/`, `types/`, `db/queries/`, `schemas/`, equivalents). If you find one, raise a **BLOCKER** citing the existing path; the coder must reuse it (extending the existing one in place if needed) rather than ship a parallel implementation. This applies only to *new* code in this WU vs. the *existing* codebase — don't flag duplication within the WU's own output as a violation; the rule against premature abstraction still governs net-new shared code.
 
-6. **Is there dead-weight or scope creep?** Refactors adjacent to the work unit that weren't asked for. Speculative abstractions. Unnecessary comments. Half-implementations of features not in this work unit.
+6. **Does it surface or hide changes future work needs to know?** If the coder modified an interface that downstream work depends on, the change should be in a decision file or a contract update — not silent.
 
-7. **Is jargon being introduced into user-facing copy?** If the work unit serves a non-engineer persona, the surface text should match the project's voice file. Flag anything that sounds like dev-speak in a user-facing surface.
+7. **Is there dead-weight or scope creep?** Refactors adjacent to the work unit that weren't asked for. Speculative abstractions. Unnecessary comments. Half-implementations of features not in this work unit.
 
-8. **Does the vitest gate pass (JS/TS projects)?** If `methodfile.json` declares `testing.framework: "vitest"` with `testing.enforced: true`, run both gates from [build-wu.md §Step 5.5](../protocols/build-wu.md):
+8. **Is jargon being introduced into user-facing copy?** If the work unit serves a non-engineer persona, the surface text should match the project's voice file. Flag anything that sounds like dev-speak in a user-facing surface.
+
+9. **Does the vitest gate pass (JS/TS projects)?** If `methodfile.json` declares `testing.framework: "vitest"` with `testing.enforced: true`, run both gates from [build-wu.md §Step 5.5](../protocols/build-wu.md):
    - **Gate A:** Run `npx vitest run` (or whatever `testing.command` says) from the implementation repo root. Capture the full output. Non-zero exit → BLOCKER finding with the failing test list.
    - **Gate B:** Compute `git diff --name-only <swarm-base>...HEAD`, filter to source files (`.ts/.tsx/.js/.jsx` under `src/`, `app/`, `routes/`, `pages/`, `lib/`, `components/`, `api/` — exclude `*.test.*`, `*.spec.*`, `*.d.ts`, configs). For each remaining file, grep the test directories for an import of that module or a colocated `*.test.*` file. Any uncovered file → BLOCKER finding naming the file. The coder may rebut by flagging files as genuinely untestable (type-only, config glue) in the WU notes — accept those rebuttals when reasonable.
 

package/templates/protocols/end-of-session.md

@@ -67,7 +67,13 @@ Create `docs/build/sessions/YYYY-MM-DD-short-slug.md`. The entry includes:
 
 Add a row to `sessions/_index.md`.
 
-### 8. Verify nothing is lost
+### 8. Regenerate HTML companion views (if any visual register changed)
+
+If anything in `ui-ux/`, `design-system/`, `maps/`, or `architecture/` was edited this session, run `nuos-catalogue render` to refresh the companion HTML views (`_view.html` in each of those directories). These are generated artefacts — the markdown stays canonical — but they need to stay in sync so the operator's next review opens current views. Stage the refreshed `_view.html` files for the commit alongside the markdown.
+
+If none of those registers changed, skip this step.
+
+### 9. Verify nothing is lost
 
 Before committing, scan:
 
@@ -78,7 +84,7 @@ Before committing, scan:
 - Cross-references resolve (no dead links)
 - Dates are right
 
-### 9. Commit
+### 10. Commit
 
 Single commit. Message format: