@nusoft/nuos-build-catalogue 0.9.0 → 0.10.1

package/dist/commands/create.js

@@ -0,0 +1,341 @@
+/**
+ * Phase H part 3 — interactive create commands.
+ *
+ * Four commands: `wu create`, `decision create`, `question create`,
+ * `persona create`. Each walks the operator through the relevant
+ * register's protocol body (per `scripts/protocols/wu-new.md` etc.)
+ * and drives the workflow lifecycle to commit.
+ *
+ * Capture-builders are split out as pure functions so tests can verify
+ * the typed-payload shape without exercising readline. The interactive
+ * shell (`cmdWu*Create`) prompts, calls the builder, and drives the
+ * runtime.
+ */
+import { askUntilValid, validate } from './prompt.js';
+const BUILD_MAINTAINER = {
+    kind: 'staff',
+    id: 'build-maintainer',
+    role: 'build-maintainer',
+};
+// ---------------------------------------------------------------------------
+// Existing-numbers helper — pulls register's prior numbers from the store
+// ---------------------------------------------------------------------------
+export function existingNumbersForRegister(store, register) {
+    return store
+        .list()
+        .filter((r) => r.register === register)
+        .map((r) => r.number);
+}
+// ---------------------------------------------------------------------------
+// decision create
+// ---------------------------------------------------------------------------
+export async function cmdDecisionCreate(store, runtime, prompt) {
+    prompt.print('Creating a new decision (D-NNN).');
+    prompt.print('');
+    const title = await askUntilValid(prompt, 'Title (one short sentence — what was decided): ', (v) => validate.nonEmpty(v, 'title'));
+    const context = await askUntilValid(prompt, 'Context — why this decision was needed (multi-line):', (v) => validate.nonEmpty(v, 'context'), { multiline: true });
+    const decision = await askUntilValid(prompt, 'Decision — what was decided, in one or two sentences (multi-line):', (v) => validate.nonEmpty(v, 'decision'), { multiline: true });
+    const consequences = await askUntilValid(prompt, 'Consequences — what this commits us to and forecloses (multi-line):', (v) => validate.nonEmpty(v, 'consequences'), { multiline: true });
+    const captureAlternatives = await prompt.confirm('Capture alternatives considered?', true);
+    const alternativesConsidered = captureAlternatives
+        ? await prompt.askMultiline('Alternatives considered (multi-line):')
+        : undefined;
+    const metadata = {
+        existingDecisionNumbers: existingNumbersForRegister(store, 'decision'),
+        context,
+        decision,
+        consequences,
+        alternativesConsidered,
+    };
+    return await driveCreateLifecycle(runtime, 'decision.create', {
+        channel: 'typed_note',
+        content: title,
+        subjects: [{ kind: 'decision', id: 'd-pending' }],
+        metadata: metadata,
+    });
+}
+// ---------------------------------------------------------------------------
+// question create
+// ---------------------------------------------------------------------------
+export async function cmdQuestionCreate(store, runtime, prompt) {
+    prompt.print('Creating a new open question (Q-NNN).');
+    prompt.print('');
+    const title = await askUntilValid(prompt, 'The question — one sentence ending in "?": ', (v) => validate.nonEmpty(v, 'title'));
+    const whyItMatters = await askUntilValid(prompt, 'Why it matters — what is blocked, what choice depends on it (multi-line):', (v) => validate.nonEmpty(v, 'whyItMatters'), { multiline: true });
+    const captureOptions = await prompt.confirm('Sketch options under consideration?', true);
+    const options = captureOptions
+        ? await prompt.askMultiline('Options (multi-line):')
+        : undefined;
+    const captureEvidence = await prompt.confirm('Note what evidence would resolve this?', true);
+    const evidenceNeeded = captureEvidence
+        ? await prompt.askMultiline('Evidence needed (multi-line):')
+        : undefined;
+    const blocksCsv = (await prompt.ask('WUs this blocks (comma-separated WU handles, or empty): ')).trim();
+    const blocks = blocksCsv ? blocksCsv.split(',').map((s) => s.trim()).filter(Boolean) : [];
+    const metadata = {
+        existingQuestionNumbers: existingNumbersForRegister(store, 'open_question'),
+        whyItMatters,
+        options: options || undefined,
+        evidenceNeeded: evidenceNeeded || undefined,
+        blocks,
+    };
+    return await driveCreateLifecycle(runtime, 'open_question.create', {
+        channel: 'typed_note',
+        content: title,
+        subjects: [{ kind: 'open_question', id: 'q-pending' }],
+        metadata: metadata,
+    });
+}
+// ---------------------------------------------------------------------------
+// persona create
+// ---------------------------------------------------------------------------
+export async function cmdPersonaCreate(store, runtime, prompt) {
+    prompt.print('Creating a new persona (P-NNN). Per D046, walk the seven dimensions + acid-test.');
+    prompt.print('A persona is a design constraint, not a demographic snapshot. If a dimension');
+    prompt.print('does not change a future design decision, rewrite it until it does.');
+    prompt.print('');
+    const title = await askUntilValid(prompt, 'Persona name (e.g. "The DSL on call for 18 months"): ', (v) => validate.nonEmpty(v, 'title'));
+    prompt.print('');
+    prompt.print('Each of the next seven dimensions is multi-line input.');
+    prompt.print('');
+    const identity = await askDimension(prompt, '1. Identity — who they are in the context of THIS system');
+    const reality = await askDimension(prompt, '2. Reality — physical environment when they use the outcome');
+    const psychology = await askDimension(prompt, '3. Psychology — technical confidence, stress level, tolerance for confusion');
+    const trigger = await askDimension(prompt, '4. Trigger — what brings them to this outcome (a real-world event)');
+    const history = await askDimension(prompt, '5. History — what they have done before arriving here');
+    const success = await askDimension(prompt, '6. Success — what "done" looks like from THEIR perspective');
+    const constraints = await askDimension(prompt, '7. Constraints — what they cannot or will not do');
+    const acidTest = await askUntilValid(prompt, 'Acid-test refinement — the hardest legitimate combination of constraints (multi-line):', (v) => validate.nonEmpty(v, 'acidTest'), { multiline: true });
+    const metadata = {
+        existingPersonaNumbers: existingNumbersForRegister(store, 'persona'),
+        identity,
+        reality,
+        psychology,
+        trigger,
+        history,
+        success,
+        constraints,
+        acidTest,
+    };
+    return await driveCreateLifecycle(runtime, 'persona.create', {
+        channel: 'typed_note',
+        content: title,
+        subjects: [{ kind: 'persona', id: 'p-pending' }],
+        metadata: metadata,
+    });
+}
+async function askDimension(prompt, label) {
+    return askUntilValid(prompt, `${label} (multi-line):`, (v) => validate.nonEmpty(v, 'dimension'), { multiline: true });
+}
+// ---------------------------------------------------------------------------
+// wu create
+// ---------------------------------------------------------------------------
+export async function cmdWuCreate(store, runtime, prompt) {
+    prompt.print('Creating a new work unit (WU-NNN).');
+    prompt.print('Per D046, a WU carries the six-field outcome shape (persona / trigger / walkthrough');
+    prompt.print('/ acceptance criteria / contracts produced / contracts consumed). Infrastructure WUs');
+    prompt.print('(build, publish, hardening, refactor) skip persona/trigger/walkthrough.');
+    prompt.print('');
+    const title = await askUntilValid(prompt, 'Title (one short sentence — what does this WU deliver?): ', (v) => validate.nonEmpty(v, 'title'));
+    const kind = (await prompt.askChoice('Kind?', [
+        'feature',
+        'infrastructure',
+        'spike',
+        'remediation',
+    ]));
+    const phaseAnswer = (await prompt.ask('Phase tag (e.g. "0 — NuOS Foundation"; empty for none): ')).trim();
+    const phase = phaseAnswer || undefined;
+    const dependsCsv = (await prompt.ask('Depends on (comma-separated handles or empty): ')).trim();
+    const dependsOn = dependsCsv ? dependsCsv.split(',').map((s) => s.trim()).filter(Boolean) : [];
+    const blocksCsv = (await prompt.ask('Blocks (comma-separated handles or empty): ')).trim();
+    const blocks = blocksCsv ? blocksCsv.split(',').map((s) => s.trim()).filter(Boolean) : [];
+    const isInfrastructure = kind === 'infrastructure';
+    let personaRef;
+    let trigger;
+    let walkthrough;
+    if (isInfrastructure) {
+        personaRef = 'N/A — infrastructure WU';
+        trigger = 'N/A — infrastructure WU';
+        walkthrough = 'N/A — infrastructure WU';
+        prompt.print('(persona/trigger/walkthrough auto-marked N/A for infrastructure WU)');
+    }
+    else {
+        personaRef = (await prompt.ask('Persona ref (P-NNN handle, or leave empty to skip): ')).trim() || undefined;
+        trigger = await askUntilValid(prompt, 'Trigger — the real-world event that makes this outcome necessary (multi-line):', (v) => validate.nonEmpty(v, 'trigger'), { multiline: true });
+        walkthrough = await askUntilValid(prompt, 'Walkthrough — numbered steps from the persona\'s perspective; surface failure paths inline (multi-line):', (v) => validate.nonEmpty(v, 'walkthrough'), { multiline: true });
+    }
+    prompt.print('');
+    prompt.print('Acceptance criteria (5–10; each evaluable by inspection alone — auditor\'s test).');
+    prompt.print('Enter one per line; blank line ends.');
+    const acceptanceCriteria = [];
+    while (true) {
+        const ac = (await prompt.ask(`AC ${acceptanceCriteria.length + 1} (blank to finish): `)).trim();
+        if (!ac)
+            break;
+        acceptanceCriteria.push(ac);
+    }
+    prompt.print('');
+    prompt.print('Contracts produced — what this WU makes available to other WUs once it lands.');
+    prompt.print('One per line; blank line ends.');
+    const contractsProduced = [];
+    while (true) {
+        const c = (await prompt.ask(`Produced ${contractsProduced.length + 1}: `)).trim();
+        if (!c)
+            break;
+        contractsProduced.push(c);
+    }
+    prompt.print('');
+    prompt.print('Contracts consumed — what must already exist before this WU can run.');
+    prompt.print('One per line; blank line ends.');
+    const contractsConsumed = [];
+    while (true) {
+        const c = (await prompt.ask(`Consumed ${contractsConsumed.length + 1}: `)).trim();
+        if (!c)
+            break;
+        contractsConsumed.push(c);
+    }
+    const wantApproach = await prompt.confirm('Capture an Approach paragraph?', false);
+    const approach = wantApproach
+        ? await prompt.askMultiline('Approach (multi-line):')
+        : undefined;
+    const metadata = {
+        kind,
+        phase,
+        existingWUNumbers: existingNumbersForRegister(store, 'work_unit'),
+        dependsOn,
+        blocks,
+        personaRef,
+        trigger,
+        walkthrough,
+        acceptanceCriteria,
+        contractsProduced,
+        contractsConsumed,
+        approach,
+    };
+    return await driveCreateLifecycle(runtime, 'work_unit.create', {
+        channel: 'typed_note',
+        content: title,
+        subjects: [{ kind: 'work_unit', id: 'wu-pending' }],
+        metadata: metadata,
+    });
+}
+// ---------------------------------------------------------------------------
+// Lifecycle driver
+// ---------------------------------------------------------------------------
+async function driveCreateLifecycle(runtime, workflowType, capture) {
+    let workflow;
+    try {
+        workflow = await runtime.startWorkflow(workflowType, BUILD_MAINTAINER, capture);
+    }
+    catch (err) {
+        return {
+            output: `${workflowType} rejected at start: ${err.message}`,
+            exitCode: 1,
+        };
+    }
+    if (workflow.status !== 'waiting_for_confirmation') {
+        return {
+            output: `${workflowType} unexpected post-start status: ${workflow.status}`,
+            exitCode: 1,
+        };
+    }
+    workflow = await runtime.confirmIntent(workflow.id, BUILD_MAINTAINER.id);
+    if (workflow.status === 'waiting_for_approval') {
+        workflow = await runtime.approveIntent(workflow.id, BUILD_MAINTAINER.id);
+    }
+    if (workflow.status !== 'committing') {
+        return {
+            output: `${workflowType} unexpected pre-commit status: ${workflow.status}`,
+            exitCode: 1,
+        };
+    }
+    workflow = await runtime.commitIntent(workflow.id, BUILD_MAINTAINER.id);
+    if (workflow.status !== 'completed') {
+        return {
+            output: `${workflowType} commit failed: status=${workflow.status}`,
+            exitCode: 1,
+        };
+    }
+    const handle = workflow.writeIntent?.payload?.handle ?? 'unknown';
+    return {
+        output: `${workflowType} ✅ created ${handle}  (commit ${workflow.commitRef?.commitRef ?? '?'})`,
+        exitCode: 0,
+    };
+}
+export function buildDecisionCreateCapture(store, inputs) {
+    return {
+        channel: 'typed_note',
+        content: inputs.title,
+        subjects: [{ kind: 'decision', id: 'd-pending' }],
+        metadata: {
+            existingDecisionNumbers: existingNumbersForRegister(store, 'decision'),
+            context: inputs.context,
+            decision: inputs.decision,
+            consequences: inputs.consequences,
+            alternativesConsidered: inputs.alternativesConsidered,
+        },
+    };
+}
+export function buildQuestionCreateCapture(store, inputs) {
+    return {
+        channel: 'typed_note',
+        content: inputs.title,
+        subjects: [{ kind: 'open_question', id: 'q-pending' }],
+        metadata: {
+            existingQuestionNumbers: existingNumbersForRegister(store, 'open_question'),
+            whyItMatters: inputs.whyItMatters,
+            options: inputs.options,
+            evidenceNeeded: inputs.evidenceNeeded,
+            blocks: inputs.blocks,
+        },
+    };
+}
+export function buildPersonaCreateCapture(store, inputs) {
+    return {
+        channel: 'typed_note',
+        content: inputs.title,
+        subjects: [{ kind: 'persona', id: 'p-pending' }],
+        metadata: {
+            existingPersonaNumbers: existingNumbersForRegister(store, 'persona'),
+            identity: inputs.identity,
+            reality: inputs.reality,
+            psychology: inputs.psychology,
+            trigger: inputs.trigger,
+            history: inputs.history,
+            success: inputs.success,
+            constraints: inputs.constraints,
+            acidTest: inputs.acidTest,
+        },
+    };
+}
+export function buildWuCreateCapture(store, inputs) {
+    const isInfra = inputs.kind === 'infrastructure';
+    const personaRef = isInfra
+        ? 'N/A — infrastructure WU'
+        : inputs.personaRef;
+    const trigger = isInfra
+        ? 'N/A — infrastructure WU'
+        : inputs.trigger;
+    const walkthrough = isInfra
+        ? 'N/A — infrastructure WU'
+        : inputs.walkthrough;
+    return {
+        channel: 'typed_note',
+        content: inputs.title,
+        subjects: [{ kind: 'work_unit', id: 'wu-pending' }],
+        metadata: {
+            kind: inputs.kind,
+            phase: inputs.phase,
+            existingWUNumbers: existingNumbersForRegister(store, 'work_unit'),
+            dependsOn: inputs.dependsOn,
+            blocks: inputs.blocks,
+            personaRef,
+            trigger,
+            walkthrough,
+            acceptanceCriteria: inputs.acceptanceCriteria,
+            contractsProduced: inputs.contractsProduced,
+            contractsConsumed: inputs.contractsConsumed,
+            approach: inputs.approach,
+        },
+    };
+}

package/dist/commands/format.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared formatters for the read-side CLI commands.
+ *
+ * Two output modes per list/show pair: human-readable (default) for
+ * terminal use; JSON (`--json`) for piping into other tools. Tabular
+ * output uses a minimal per-line width-aware formatter to keep the
+ * dep graph small (no `cli-table3` etc.).
+ */
+import type { MigratedRecord, Register } from '../migrate/types.js';
+export interface ListFilter {
+    status?: string;
+    limit?: number;
+}
+export declare function filterRecords(records: readonly MigratedRecord[], register: Register, filter: ListFilter): MigratedRecord[];
+export declare function sortByHandle(records: readonly MigratedRecord[]): MigratedRecord[];
+export declare function formatListHuman(records: readonly MigratedRecord[]): string;
+export declare function formatListJson(records: readonly MigratedRecord[]): string;
+export declare function formatShowHuman(record: MigratedRecord): string;
+export declare function formatShowJson(record: MigratedRecord): string;

package/dist/commands/format.js

@@ -0,0 +1,89 @@
+/**
+ * Shared formatters for the read-side CLI commands.
+ *
+ * Two output modes per list/show pair: human-readable (default) for
+ * terminal use; JSON (`--json`) for piping into other tools. Tabular
+ * output uses a minimal per-line width-aware formatter to keep the
+ * dep graph small (no `cli-table3` etc.).
+ */
+const STATUS_FALLBACK = '—';
+export function filterRecords(records, register, filter) {
+    let result = records.filter((r) => r.register === register);
+    if (filter.status) {
+        const needle = filter.status.toLowerCase();
+        result = result.filter((r) => (r.status ?? '').toLowerCase().includes(needle));
+    }
+    result = sortByHandle(result);
+    if (filter.limit && filter.limit > 0) {
+        result = result.slice(0, filter.limit);
+    }
+    return result;
+}
+export function sortByHandle(records) {
+    return [...records].sort((a, b) => {
+        if (a.number !== b.number)
+            return a.number - b.number;
+        return a.handle.localeCompare(b.handle);
+    });
+}
+export function formatListHuman(records) {
+    if (records.length === 0)
+        return '(no records match)';
+    const widths = computeWidths(records);
+    const lines = [];
+    for (const r of records) {
+        const handle = r.handle.padEnd(widths.handle);
+        const status = (r.status ?? STATUS_FALLBACK).padEnd(widths.status);
+        lines.push(`  ${handle}  ${status}  ${r.title}`);
+    }
+    lines.push('');
+    lines.push(`  (${records.length} record${records.length === 1 ? '' : 's'})`);
+    return lines.join('\n');
+}
+export function formatListJson(records) {
+    return JSON.stringify(records.map((r) => ({
+        handle: r.handle,
+        number: r.number,
+        register: r.register,
+        title: r.title,
+        status: r.status,
+        slug: r.slug,
+        sourcePath: r.sourcePath,
+    })), null, 2);
+}
+export function formatShowHuman(record) {
+    return [
+        `# ${record.handle} — ${record.title}`,
+        '',
+        `register:        ${record.register}`,
+        `number:          ${record.number}`,
+        `status:          ${record.status ?? STATUS_FALLBACK}`,
+        `slug:            ${record.slug}`,
+        `source path:     ${record.sourcePath}`,
+        `file modified:   ${record.fileModifiedAt}`,
+        `migrated at:     ${record.migratedAt} (from ${record.migratedFrom})`,
+        '',
+        `--- markdown body (${record.rawMarkdown.length} chars) ---`,
+        truncateBody(record.rawMarkdown, 2000),
+    ].join('\n');
+}
+export function formatShowJson(record) {
+    return JSON.stringify(record, null, 2);
+}
+function computeWidths(records) {
+    let handle = 0;
+    let status = 0;
+    for (const r of records) {
+        if (r.handle.length > handle)
+            handle = r.handle.length;
+        const s = (r.status ?? STATUS_FALLBACK).length;
+        if (s > status)
+            status = s;
+    }
+    return { handle, status };
+}
+function truncateBody(body, max) {
+    if (body.length <= max)
+        return body;
+    return body.slice(0, max) + `\n…[truncated; use --json for full body]`;
+}

package/dist/commands/handlers.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Per-register read-side handlers (list + show).
+ *
+ * Pure-ish: these read from a `WorkflowStore` and produce strings. The
+ * CLI surface in `src/cli.ts` opens the store, calls the handler, and
+ * prints the result.
+ */
+import type { Register, MigratedRecord } from '../migrate/types.js';
+import type { WorkflowStore } from '../migrate/store.js';
+import { type ListFilter } from './format.js';
+export interface ListOptions extends ListFilter {
+    asJson?: boolean;
+}
+export interface ShowOptions {
+    asJson?: boolean;
+}
+export interface HandlerResult {
+    output: string;
+    exitCode: number;
+}
+export declare function listRegister(store: WorkflowStore, register: Register, options: ListOptions): HandlerResult;
+export declare function showRecord(store: WorkflowStore, register: Register, handle: string, options: ShowOptions): HandlerResult;
+/**
+ * Accept friendly variants like `111` (assumes work_unit), `wu-111`,
+ * `WU 111`, `D45`, `Q9` — and normalise to the stored handle form.
+ */
+export declare function normaliseHandle(register: Register, raw: string): string;
+export declare function registerCommand(register: Register): string;
+export declare function listAcrossRegisters(store: WorkflowStore): {
+    byRegister: Record<Register, number>;
+    total: number;
+};
+export declare function isRegister(value: string): value is Register;
+export declare function commandToRegister(command: string): Register | null;
+export type { MigratedRecord };

package/dist/commands/handlers.js

@@ -0,0 +1,132 @@
+/**
+ * Per-register read-side handlers (list + show).
+ *
+ * Pure-ish: these read from a `WorkflowStore` and produce strings. The
+ * CLI surface in `src/cli.ts` opens the store, calls the handler, and
+ * prints the result.
+ */
+import { filterRecords, formatListHuman, formatListJson, formatShowHuman, formatShowJson, } from './format.js';
+export function listRegister(store, register, options) {
+    const all = store.list();
+    const matches = filterRecords(all, register, options);
+    const output = options.asJson ? formatListJson(matches) : formatListHuman(matches);
+    return { output, exitCode: 0 };
+}
+export function showRecord(store, register, handle, options) {
+    const normalised = normaliseHandle(register, handle);
+    const record = store.get(normalised);
+    if (!record) {
+        return {
+            output: `no ${register} record with handle "${normalised}" — try \`nuos-catalogue ${registerCommand(register)} list\``,
+            exitCode: 1,
+        };
+    }
+    if (record.register !== register) {
+        return {
+            output: `handle ${normalised} resolves to a ${record.register}, not a ${register}`,
+            exitCode: 1,
+        };
+    }
+    const output = options.asJson ? formatShowJson(record) : formatShowHuman(record);
+    return { output, exitCode: 0 };
+}
+/**
+ * Accept friendly variants like `111` (assumes work_unit), `wu-111`,
+ * `WU 111`, `D45`, `Q9` — and normalise to the stored handle form.
+ */
+export function normaliseHandle(register, raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return trimmed;
+    // If already in canonical form, accept verbatim.
+    if (matchesCanonical(register, trimmed))
+        return trimmed;
+    // Tolerate "WU 111" → "wu-111".
+    const wu = /^WU\s*0?(\d{1,4})([a-z]?)$/i.exec(trimmed);
+    if (wu && register === 'work_unit') {
+        const num = wu[1].padStart(3, '0');
+        return `wu-${num}${(wu[2] ?? '').toLowerCase()}`;
+    }
+    // Tolerate plain integers when the register is unambiguous.
+    const intOnly = /^(\d{1,4})([a-z]?)$/i.exec(trimmed);
+    if (intOnly) {
+        const num = intOnly[1].padStart(3, '0');
+        const suffix = (intOnly[2] ?? '').toLowerCase();
+        switch (register) {
+            case 'work_unit':
+                return `wu-${num}${suffix}`;
+            case 'decision':
+                return `D${num}`;
+            case 'open_question':
+                return `Q${num}`;
+            case 'persona':
+                return `P${num}`;
+        }
+    }
+    // Tolerate D45 / Q9 / P1 (under-padded) forms.
+    const letter = /^([DQP])(\d{1,4})$/i.exec(trimmed);
+    if (letter) {
+        const prefix = letter[1].toUpperCase();
+        const num = letter[2].padStart(3, '0');
+        return `${prefix}${num}`;
+    }
+    // Fallback: return verbatim. The store lookup will return null and the
+    // CLI surfaces a helpful error.
+    return trimmed;
+}
+function matchesCanonical(register, handle) {
+    switch (register) {
+        case 'work_unit':
+            return /^wu-\d{3,}[a-z]?$/.test(handle);
+        case 'decision':
+            return /^D\d{3,}$/.test(handle);
+        case 'open_question':
+            return /^Q\d{3,}$/.test(handle);
+        case 'persona':
+            return /^P\d{3,}$/.test(handle);
+    }
+}
+export function registerCommand(register) {
+    switch (register) {
+        case 'work_unit':
+            return 'wu';
+        case 'decision':
+            return 'decision';
+        case 'open_question':
+            return 'question';
+        case 'persona':
+            return 'persona';
+    }
+}
+export function listAcrossRegisters(store) {
+    const byRegister = {
+        work_unit: 0,
+        decision: 0,
+        open_question: 0,
+        persona: 0,
+    };
+    let total = 0;
+    for (const r of store.list()) {
+        byRegister[r.register] += 1;
+        total += 1;
+    }
+    return { byRegister, total };
+}
+// Convenience guard for the CLI dispatcher.
+export function isRegister(value) {
+    return value === 'work_unit' || value === 'decision' || value === 'open_question' || value === 'persona';
+}
+export function commandToRegister(command) {
+    switch (command) {
+        case 'wu':
+            return 'work_unit';
+        case 'decision':
+            return 'decision';
+        case 'question':
+            return 'open_question';
+        case 'persona':
+            return 'persona';
+        default:
+            return null;
+    }
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `nuos-catalogue init` — bootstrap a new project's catalogue.
+ *
+ * Single command that does what was previously a six-step manual scaffold:
+ *   1. mkdir docs/build/ + copy starter-kit content
+ *   2. Substitute {{PROJECT_NAME}} / {{PROJECT_TAGLINE}} / {{TODAY}} in
+ *      STATE.md and methodfile.json
+ *   3. Copy the four protocols into .claude/commands/ (preserving
+ *      existing files)
+ *   4. Append a "Build catalogue (NuOS Build Method)" section to
+ *      CLAUDE.md (creating it if missing; preserving existing content)
+ *   5. Update .gitignore: !docs/build/ override (if `build/` is present
+ *      anywhere, the catalogue would otherwise be silently ignored —
+ *      same gotcha caught at nuos Session 53); ignore .nuos-catalogue/
+ *      per D047
+ *   6. Run a first migrate to verify
+ *
+ * Companion command: `install-protocols` refreshes just step 3 from the
+ * canonical bodies bundled in this CLI package.
+ */
+import type { Prompt } from './prompt.js';
+export interface InitOptions {
+    /** Target project root (default: cwd). */
+    cwd?: string;
+    /** Pre-supplied values; if any are missing, the prompt fills them in. */
+    name?: string;
+    tagline?: string;
+    domain?: string;
+    role?: string;
+    /** When true, runs all steps without prompts (uses defaults / supplied values). */
+    nonInteractive?: boolean;
+}
+export interface InitResult {
+    output: string;
+    exitCode: number;
+}
+export declare function cmdInit(prompt: Prompt, options?: InitOptions): Promise<InitResult>;
+export interface InstallProtocolsOptions {
+    cwd?: string;
+}
+export declare function cmdInstallProtocols(prompt: Prompt, options?: InstallProtocolsOptions): Promise<InitResult>;