@nusoft/nuos-build-catalogue 0.25.0 → 0.27.0

package/dist/cli.js

@@ -424,6 +424,12 @@ Usage:
 
   nuos-catalogue plan      status    show planning progress across the 5-phase arc
 
+  nuos-catalogue mode                    print the current operator mode
+  nuos-catalogue mode <name>             set operator mode: coaching | standard | developer
+
+  nuos-catalogue render                  regenerate HTML companion views for visual registers
+  nuos-catalogue render <register>       just one register: surfaces | design-system | maps | architecture
+
   nuos-catalogue swarm     status    [--limit=N]  list recent /build-wu runs
   nuos-catalogue swarm     cost      aggregate cost across swarm runs
 
@@ -557,6 +563,24 @@ async function main() {
             console.error('available: plan status');
             process.exit(1);
         }
+        case 'mode': {
+            const { cmdMode } = await import('./commands/mode.js');
+            const code = await cmdMode({ cwd: process.cwd(), mode: args.positional[0] });
+            if (code !== 0)
+                process.exit(code);
+            break;
+        }
+        case 'render': {
+            const { cmdRender } = await import('./commands/render.js');
+            const code = await cmdRender({
+                cwd: process.cwd(),
+                positional: args.positional[0],
+                buildRootFlag: args.flags['build-root'],
+            });
+            if (code !== 0)
+                process.exit(code);
+            break;
+        }
         case 'swarm': {
             const sub = args.positional[0];
             const { cmdSwarmStatus, cmdSwarmCost } = await import('./commands/swarm.js');

package/dist/commands/init.js

@@ -517,43 +517,21 @@ async function ensureGitignoreEntries(gitignorePath, log_line) {
         ? '  · created .gitignore with catalogue rules'
         : '  · appended catalogue rules to .gitignore');
 }
-function renderCatalogueSection(projectName) {
+function renderCatalogueSection(_projectName) {
     return `## Build catalogue (NuOS Build Method)
 
-This project uses the **NuOS Build Method catalogue** at [docs/build/](docs/build/). It is the project's memory — who it's for, what's been built, what's been decided, what's still unknown, what's at risk. Eleven registers in plain Markdown. The catalogue stays current through two protocols that bookend every session.
+This project's memory lives at [docs/build/](docs/build/) — eleven registers in plain Markdown, kept current by two bookend protocols.
 
-**Start here** if you're new:
+- Run \`/start-of-session\` to begin every session, \`/end-of-session\` to close every session.
+- A brand-new project: \`/start-of-session\` detects the empty catalogue and routes through 5 planning phases (Orientation → Architecture → UI/UX + Design System → Maps → Initial Work Units) before building.
+- Onboarding: [docs/build/WELCOME.md](docs/build/WELCOME.md) (5 min); every term defined in [docs/build/GLOSSARY.md](docs/build/GLOSSARY.md).
 
-- [docs/build/WELCOME.md](docs/build/WELCOME.md) — what this catalogue is, in 5 minutes
-- [docs/build/GLOSSARY.md](docs/build/GLOSSARY.md) — every term defined once
+### Rules
 
-### Three commands
+- **Never close without \`/end-of-session\`** — work not written down is lost.
+- **Never edit an accepted decision file** — file a superseding decision instead (pre-commit hook blocks silent edits).
+- **Never make an architectural decision in conversation without filing it to \`docs/build/decisions/\` first** — drift kills the catalogue.
 
-That's it. Everything else is automatic.
-
-\`\`\`text
-/start-of-session       — every time you begin working
-/end-of-session         — every time you stop
-\`\`\`
-
-(\`init\` runs once at the start; you've already done that.)
-
-If this is a brand-new project, \`/start-of-session\` will detect the empty catalogue and walk you through 5 short planning phases (Orientation, Architecture, UI/UX + Design System, Maps, Initial Work Units) before any building starts. Each phase is its own session. Take them in order; pause whenever you need to.
-
-### The principle that makes it work
-
-**Project memory never drifts from project reality.** Every decision made in conversation gets saved before the session ends. Every change to an existing piece flows through a protocol. The pre-commit hook blocks silent edits to accepted decisions; the post-commit hook auto-refreshes the search index after every commit. What the AI finds when you ask "what did we decide about X?" is always current.
-
-### What never to do
-
-- **Never close a session without \`/end-of-session\`.** Work that isn't written down is work that's lost.
-- **Never edit an accepted decision file.** If something changes, file a new decision that supersedes the old one. The pre-commit hook will block silent edits.
-- **Never make an architectural decision in conversation without filing it.** If you and the AI agree on "let's go with X", file it as a decision *before moving on*. Drift is the failure mode that makes the catalogue worthless.
-
-### If you need more
-
-- All registers and their templates live under [docs/build/](docs/build/)
-- The full CLI surface (creating work units / decisions / personas / questions / contracts / surfaces from the command line) is documented at [docs/build/WELCOME.md](docs/build/WELCOME.md)
-- To refresh protocols and hooks later (after a CLI upgrade): \`npx @nusoft/nuos-build-catalogue install-protocols\`
+Refresh protocols + hooks after a CLI upgrade with \`npx @nusoft/nuos-build-catalogue install-protocols\`.
 `;
 }

package/dist/commands/mode.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `nuos-catalogue mode` — read or set the operator mode in methodfile.json.
+ *
+ *   nuos-catalogue mode                  → prints the current mode
+ *   nuos-catalogue mode <name>           → sets the mode and stamps modeSelectedAt
+ *
+ * Valid names: coaching, standard, developer.
+ *
+ * The mode shapes the *tone* of every operator-facing protocol — see
+ * docs/build/OPERATOR-MODES.md for what each mode means. The picker
+ * normally runs once at first /start-of-session; this CLI command exists
+ * so the operator can change their mind without hand-editing JSON.
+ */
+export declare const VALID_MODES: readonly ["coaching", "standard", "developer"];
+export type OperatorMode = (typeof VALID_MODES)[number];
+export declare function isOperatorMode(v: unknown): v is OperatorMode;
+export interface ModeOptions {
+    cwd?: string;
+    /** When omitted, the command prints the current mode and exits 0. */
+    mode?: string;
+    /** Override "now" — used by tests for deterministic timestamps. */
+    now?: () => string;
+}
+export declare function cmdMode(options?: ModeOptions): Promise<number>;

package/dist/commands/mode.js

@@ -0,0 +1,82 @@
+/**
+ * `nuos-catalogue mode` — read or set the operator mode in methodfile.json.
+ *
+ *   nuos-catalogue mode                  → prints the current mode
+ *   nuos-catalogue mode <name>           → sets the mode and stamps modeSelectedAt
+ *
+ * Valid names: coaching, standard, developer.
+ *
+ * The mode shapes the *tone* of every operator-facing protocol — see
+ * docs/build/OPERATOR-MODES.md for what each mode means. The picker
+ * normally runs once at first /start-of-session; this CLI command exists
+ * so the operator can change their mind without hand-editing JSON.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+export const VALID_MODES = ['coaching', 'standard', 'developer'];
+export function isOperatorMode(v) {
+    return typeof v === 'string' && VALID_MODES.includes(v);
+}
+export async function cmdMode(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const methodfilePath = path.join(cwd, 'methodfile.json');
+    if (!existsSync(methodfilePath)) {
+        console.error(`No methodfile.json found at ${cwd}.`);
+        console.error('Run `nuos-catalogue init` first to set up a catalogue.');
+        return 1;
+    }
+    let raw;
+    try {
+        raw = await readFile(methodfilePath, 'utf8');
+    }
+    catch (err) {
+        console.error(`Couldn't read methodfile.json: ${err.message}`);
+        return 1;
+    }
+    let mf;
+    try {
+        mf = JSON.parse(raw);
+    }
+    catch (err) {
+        console.error(`methodfile.json is not valid JSON: ${err.message}`);
+        return 1;
+    }
+    const operator = mf.operator ?? {};
+    const current = operator.mode;
+    if (options.mode === undefined) {
+        if (isOperatorMode(current)) {
+            console.log(current);
+            return 0;
+        }
+        console.log('(unset)');
+        console.log('');
+        console.log('Run `nuos-catalogue mode <coaching|standard|developer>` to set,');
+        console.log('or just start /start-of-session and the picker will run automatically.');
+        return 0;
+    }
+    if (!isOperatorMode(options.mode)) {
+        console.error(`unknown mode: ${options.mode}`);
+        console.error(`valid modes: ${VALID_MODES.join(', ')}`);
+        return 1;
+    }
+    const today = (options.now ?? (() => new Date().toISOString().slice(0, 10)))();
+    const updated = {
+        ...mf,
+        operator: {
+            ...operator,
+            mode: options.mode,
+            modeSelectedAt: today,
+        },
+    };
+    // Preserve a trailing newline to match the JSON convention in the rest of the
+    // project (every other written file ends with a newline; tooling like git diff
+    // is happier that way).
+    const trailingNewline = raw.endsWith('\n') ? '\n' : '';
+    await writeFile(methodfilePath, JSON.stringify(updated, null, 2) + trailingNewline, 'utf8');
+    const previous = isOperatorMode(current) ? current : '(unset)';
+    console.log(`Operator mode: ${previous} → ${options.mode}`);
+    console.log(`Tone for every operator-facing protocol now matches '${options.mode}'.`);
+    console.log(`See docs/build/OPERATOR-MODES.md for what that means in practice.`);
+    return 0;
+}

package/dist/commands/render.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `nuos-catalogue render [register]` — regenerate the HTML companion views
+ * for the visual registers (ui-ux, design-system, maps, architecture).
+ *
+ *   nuos-catalogue render                  # render all four
+ *   nuos-catalogue render surfaces         # render just ui-ux/_view.html
+ *   nuos-catalogue render design-system    # render just design-system/_view.html
+ *   nuos-catalogue render maps             # render just maps/_view.html
+ *   nuos-catalogue render architecture     # render just architecture/_view.html
+ *
+ * Companion HTML files are *generated artefacts*. The canonical source for
+ * every register stays markdown — every agent (architect, coder, reviewer)
+ * reads markdown. The HTML exists so the operator can review inherently visual
+ * artefacts in their natural medium.
+ */
+export interface RenderCommandOptions {
+    cwd?: string;
+    /** Optional register name (`surfaces`, `design-system`, `maps`, `architecture`). */
+    positional?: string;
+    /** Override for --build-root flag. */
+    buildRootFlag?: string | boolean;
+    /** Override "now" for deterministic test output. */
+    now?: () => Date;
+}
+export declare function cmdRender(options?: RenderCommandOptions): Promise<number>;

package/dist/commands/render.js

@@ -0,0 +1,40 @@
+/**
+ * `nuos-catalogue render [register]` — regenerate the HTML companion views
+ * for the visual registers (ui-ux, design-system, maps, architecture).
+ *
+ *   nuos-catalogue render                  # render all four
+ *   nuos-catalogue render surfaces         # render just ui-ux/_view.html
+ *   nuos-catalogue render design-system    # render just design-system/_view.html
+ *   nuos-catalogue render maps             # render just maps/_view.html
+ *   nuos-catalogue render architecture     # render just architecture/_view.html
+ *
+ * Companion HTML files are *generated artefacts*. The canonical source for
+ * every register stays markdown — every agent (architect, coder, reviewer)
+ * reads markdown. The HTML exists so the operator can review inherently visual
+ * artefacts in their natural medium.
+ */
+import path from 'node:path';
+import { resolveBuildRoot } from '../path-resolution.js';
+import { RENDERABLE_REGISTERS, runRender } from '../render/run.js';
+export async function cmdRender(options = {}) {
+    const buildRoot = resolveBuildRoot(options.buildRootFlag, { cwd: options.cwd ?? process.cwd() });
+    let only;
+    if (options.positional && options.positional !== 'all') {
+        if (!RENDERABLE_REGISTERS.includes(options.positional)) {
+            console.error(`unknown register: ${options.positional}`);
+            console.error(`available: ${RENDERABLE_REGISTERS.join(', ')}`);
+            return 1;
+        }
+        only = [options.positional];
+    }
+    const report = await runRender({ buildRoot, only, now: options.now });
+    for (const r of report.results) {
+        const status = r.written ? '✓' : '·';
+        const rel = path.relative(process.cwd(), r.outPath);
+        console.log(`  ${status} ${r.register.padEnd(16)} ${r.detail.padEnd(20)} ${r.written ? rel : ''}`);
+    }
+    const writtenCount = report.results.filter((r) => r.written).length;
+    console.log('');
+    console.log(`${writtenCount}/${report.results.length} register${report.results.length === 1 ? '' : 's'} rendered.`);
+    return 0;
+}

package/dist/render/architecture.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Render the `architecture/` register as a module gallery with cross-links.
+ *
+ * Each module becomes a card showing its responsibility (one paragraph), the
+ * personas/modules it depends on, and the contracts it owns. The cards link
+ * to each other where dependencies are named, so the operator can navigate the
+ * module graph visually instead of by grep.
+ */
+export interface ArchitectureRenderResult {
+    written: boolean;
+    outPath: string;
+    moduleCount: number;
+}
+export declare function renderArchitecture(opts: {
+    buildRoot: string;
+    projectName: string;
+    generatedAt: string;
+}): Promise<ArchitectureRenderResult>;

package/dist/render/architecture.js

@@ -0,0 +1,74 @@
+/**
+ * Render the `architecture/` register as a module gallery with cross-links.
+ *
+ * Each module becomes a card showing its responsibility (one paragraph), the
+ * personas/modules it depends on, and the contracts it owns. The cards link
+ * to each other where dependencies are named, so the operator can navigate the
+ * module graph visually instead of by grep.
+ */
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseSections, isPlaceholder } from './parser.js';
+import { pageWrapper, card, emptyState, escapeHtml, renderProse, } from './html.js';
+const SKIP_FILES = new Set(['_index.md', 'module-template.md']);
+export async function renderArchitecture(opts) {
+    const dir = path.join(opts.buildRoot, 'architecture');
+    const outPath = path.join(dir, '_view.html');
+    if (!existsSync(dir)) {
+        return { written: false, outPath, moduleCount: 0 };
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    const modules = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        if (SKIP_FILES.has(entry.name))
+            continue;
+        const md = await readFile(path.join(dir, entry.name), 'utf8');
+        if (isPlaceholder(md))
+            continue;
+        const titleMatch = md.match(/^#\s+(.+)$/m);
+        modules.push({
+            file: entry.name,
+            slug: entry.name.replace(/\.md$/, ''),
+            title: titleMatch ? titleMatch[1].trim() : entry.name,
+            sections: parseSections(md),
+        });
+    }
+    modules.sort((a, b) => a.title.localeCompare(b.title));
+    const body = modules.length === 0
+        ? card('No modules filed yet', emptyState('Phase B of planning produces this content.'))
+        : [renderModuleIndex(modules), ...modules.map(renderModuleCard)].join('');
+    const html = pageWrapper({
+        title: 'Architecture',
+        projectName: opts.projectName,
+        generatedAt: opts.generatedAt,
+        sourceNote: '<code>docs/build/architecture/</code>',
+        body,
+    });
+    await mkdir(dir, { recursive: true });
+    await writeFile(outPath, html, 'utf8');
+    return { written: true, outPath, moduleCount: modules.length };
+}
+function renderModuleIndex(modules) {
+    const items = modules
+        .map((m) => `<li><a href="#${escapeHtml(m.slug)}">${escapeHtml(m.title)}</a></li>`)
+        .join('');
+    return card('Modules', `<ul class="sitemap-list">${items}</ul>`);
+}
+function renderModuleCard(m) {
+    const sectionBlocks = [];
+    for (const [heading, body] of m.sections) {
+        if (heading === '' || heading.toLowerCase() === 'notes')
+            continue;
+        const rendered = body.trim() ? renderProse(body) : '';
+        if (!rendered)
+            continue;
+        sectionBlocks.push(`<h4>${escapeHtml(heading)}</h4>${rendered}`);
+    }
+    return `<section id="${escapeHtml(m.slug)}" class="card">
+    <h3>${escapeHtml(m.title)}</h3>
+    <div class="card__body">${sectionBlocks.join('')}</div>
+  </section>`;
+}

package/dist/render/design-system.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Render the `design-system/` register as an interactive companion gallery.
+ *
+ * What gets rendered:
+ *   - Colour tokens — as visual swatches with the hex value beside the name.
+ *   - Type scale — each step rendered at its declared px size with its line-height
+ *     and weight applied so the operator sees the real shape, not a description.
+ *   - Spacing scale — rendered as horizontal bars at the actual pixel widths.
+ *   - Radius & elevation — small boxes showing the corner radius applied.
+ *   - Motion — table only (no animation; would push complexity past MVP scope).
+ *   - Components + patterns — name list with first-paragraph summary.
+ *   - Voice + accessibility — first-paragraph summary blocks.
+ *
+ * Token files use GFM tables with a `Token` column and a value column. The parser
+ * looks for either a `Hex` / `Value` / `Size` / `Used for` column shape and falls
+ * back to "list the table verbatim" when the shape isn't recognised.
+ */
+export interface DesignSystemRenderResult {
+    written: boolean;
+    outPath: string;
+}
+export declare function renderDesignSystem(opts: {
+    buildRoot: string;
+    projectName: string;
+    generatedAt: string;
+}): Promise<DesignSystemRenderResult>;