@nusoft/nuos-build-catalogue 0.9.0 → 0.10.1

package/dist/runtime/markdown-render.js

@@ -0,0 +1,209 @@
+/**
+ * Per-register markdown renderers — Phase H part 3.
+ *
+ * Each renderer takes a typed workflow payload (from the build-catalogue
+ * pack) and produces a markdown body in the catalogue's house style.
+ * The renderers match the conventions used in the live catalogue:
+ *
+ *   - WU files: `# WU NNN — Title` + `**Status:** ...` + sections for
+ *     outcome / dependencies / contracts produced/consumed / acceptance
+ *     criteria / etc.
+ *   - Decision files: `# DNNN — Title` + `**Status:** ...` +
+ *     Context / Decision / Rationale / Alternatives / Consequences.
+ *   - Open question files: `# QNNN — Title` + `**Status:** ...` +
+ *     Why it matters / Options / Evidence needed / Blocks.
+ *   - Persona files: `# PNNN — Title` + seven dimensions + acid-test.
+ *
+ * The renderers are deliberately conservative: they produce markdown
+ * that matches the live convention closely so future hand-edits don't
+ * collide with the renderer's output. Round-trip with the migration
+ * runner: render → write → migrate → store record's rawMarkdown ==
+ * what we just rendered.
+ */
+const INFRASTRUCTURE_MARKER = 'N/A — infrastructure WU';
+export function renderWorkUnit(payload) {
+    const lines = [];
+    lines.push(`# WU ${formatWuNumber(payload)} — ${payload.title}`);
+    lines.push('');
+    lines.push(`**Status:** 🔵 proposed`);
+    if (payload.phase) {
+        lines.push(`**Phase:** ${payload.phase}`);
+    }
+    lines.push(`**Kind:** ${payload.kind}`);
+    if (payload.dependsOn.length > 0) {
+        lines.push(`**Depends on:** ${[...payload.dependsOn].join(', ')}`);
+    }
+    if (payload.blocks.length > 0) {
+        lines.push(`**Blocks:** ${[...payload.blocks].join(', ')}`);
+    }
+    lines.push('');
+    lines.push('## Outcome');
+    lines.push('');
+    const outcome = payload.outcome;
+    if (outcome.personaRef && outcome.personaRef !== INFRASTRUCTURE_MARKER) {
+        lines.push(`**Persona:** ${outcome.personaRef}`);
+        lines.push('');
+    }
+    if (outcome.trigger && outcome.trigger !== INFRASTRUCTURE_MARKER) {
+        lines.push(`**Trigger.** ${outcome.trigger}`);
+        lines.push('');
+    }
+    if (outcome.walkthrough && outcome.walkthrough !== INFRASTRUCTURE_MARKER) {
+        lines.push(`**Walkthrough.**`);
+        lines.push('');
+        lines.push(outcome.walkthrough);
+        lines.push('');
+    }
+    if (outcome.personaRef === INFRASTRUCTURE_MARKER &&
+        outcome.trigger === INFRASTRUCTURE_MARKER &&
+        outcome.walkthrough === INFRASTRUCTURE_MARKER) {
+        lines.push(`**Persona / Trigger / Walkthrough:** \`N/A — infrastructure WU\``);
+        lines.push('');
+    }
+    if (payload.approach) {
+        lines.push('## Approach');
+        lines.push('');
+        lines.push(payload.approach);
+        lines.push('');
+    }
+    lines.push('## Acceptance criteria');
+    lines.push('');
+    if (outcome.acceptanceCriteria.length === 0) {
+        lines.push('(to be filled in)');
+    }
+    else {
+        for (const ac of outcome.acceptanceCriteria) {
+            const tick = ac.met ? 'x' : ' ';
+            lines.push(`- [${tick}] ${ac.text}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Contracts produced');
+    lines.push('');
+    if (outcome.contractsProduced.length === 0) {
+        lines.push('(none)');
+    }
+    else {
+        for (const c of outcome.contractsProduced)
+            lines.push(`- ${c}`);
+    }
+    lines.push('');
+    lines.push('## Contracts consumed');
+    lines.push('');
+    if (outcome.contractsConsumed.length === 0) {
+        lines.push('(none)');
+    }
+    else {
+        for (const c of outcome.contractsConsumed)
+            lines.push(`- ${c}`);
+    }
+    lines.push('');
+    lines.push('## Notes / log');
+    lines.push('');
+    lines.push('(Empty until work starts.)');
+    lines.push('');
+    return lines.join('\n');
+}
+function formatWuNumber(payload) {
+    return String(payload.number).padStart(3, '0');
+}
+export function renderDecision(payload) {
+    const lines = [];
+    lines.push(`# ${payload.handle} — ${payload.title}`);
+    lines.push('');
+    lines.push(`**Date:** ${new Date().toISOString().slice(0, 10)}`);
+    lines.push(`**Status:** ${payload.status}`);
+    lines.push('');
+    lines.push('## Context');
+    lines.push('');
+    lines.push(payload.context);
+    lines.push('');
+    lines.push('## Decision');
+    lines.push('');
+    lines.push(payload.decision);
+    lines.push('');
+    lines.push('## Consequences');
+    lines.push('');
+    lines.push(payload.consequences);
+    lines.push('');
+    if (payload.alternativesConsidered) {
+        lines.push('## Alternatives considered');
+        lines.push('');
+        lines.push(payload.alternativesConsidered);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function renderOpenQuestion(payload) {
+    const lines = [];
+    lines.push(`# ${payload.handle} — ${payload.title}`);
+    lines.push('');
+    lines.push(`**Status:** ${payload.status}`);
+    lines.push(`**Raised:** ${new Date().toISOString().slice(0, 10)}`);
+    if (payload.blocks.length > 0) {
+        lines.push(`**Blocks:** ${[...payload.blocks].join(', ')}`);
+    }
+    lines.push('');
+    lines.push('## Why it matters');
+    lines.push('');
+    lines.push(payload.whyItMatters);
+    lines.push('');
+    if (payload.options) {
+        lines.push('## Options under consideration');
+        lines.push('');
+        lines.push(payload.options);
+        lines.push('');
+    }
+    if (payload.evidenceNeeded) {
+        lines.push('## What evidence would resolve this');
+        lines.push('');
+        lines.push(payload.evidenceNeeded);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function renderPersona(payload) {
+    const lines = [];
+    lines.push(`# ${payload.handle} — ${payload.title}`);
+    lines.push('');
+    lines.push(`**Created:** ${new Date().toISOString().slice(0, 10)}`);
+    lines.push(`**Status:** 🟢 active`);
+    lines.push('');
+    lines.push('## 1. Identity');
+    lines.push('');
+    lines.push(payload.identity);
+    lines.push('');
+    lines.push('## 2. Reality');
+    lines.push('');
+    lines.push(payload.reality);
+    lines.push('');
+    lines.push('## 3. Psychology');
+    lines.push('');
+    lines.push(payload.psychology);
+    lines.push('');
+    lines.push('## 4. Trigger');
+    lines.push('');
+    lines.push(payload.trigger);
+    lines.push('');
+    lines.push('## 5. History');
+    lines.push('');
+    lines.push(payload.history);
+    lines.push('');
+    lines.push('## 6. Success');
+    lines.push('');
+    lines.push(payload.success);
+    lines.push('');
+    lines.push('## 7. Constraints');
+    lines.push('');
+    lines.push(payload.constraints);
+    lines.push('');
+    lines.push('## Acid-test refinement');
+    lines.push('');
+    lines.push(payload.acidTest);
+    lines.push('');
+    lines.push('## Used by WUs');
+    lines.push('');
+    lines.push('(none yet — populated as WUs cite this persona)');
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/runtime/mis-adapter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `BuildCatalogueMisAdapter` — implements `@nusoft/nuflow`'s
+ * `MisWriteAdapter` for the build catalogue's write commands.
+ *
+ * Translates a typed `WriteIntent` from the build-catalogue pack into
+ * markdown edits + JSON workflow-store updates. The store and the
+ * markdown file stay in sync by always writing both at commit time.
+ *
+ * **Per-intent behaviour:**
+ *
+ * - `work_unit.advance_status`: replace the WU's status line in
+ *   markdown; append a Build catalogue history entry naming the
+ *   transition + reason; update the store record's `rawMarkdown`.
+ *
+ * - `work_unit.tick_acceptance_criterion`: append a Build catalogue
+ *   history entry naming the criterion index + evidence (no AC-list
+ *   parsing in v0.4; the maintainer hand-edits the AC list if they
+ *   want, the workflow record is canonical).
+ *
+ * - `decision.supersede`: edit BOTH the target's status line (`accepted
+ *   → superseded by D-NNN`) AND append a history entry to the
+ *   superseding decision noting what it supersedes.
+ *
+ * - `open_question.resolve`: edit the question's status line
+ *   (`active → resolved by D-NNN`) and append a history entry to the
+ *   resolving decision.
+ */
+import type { MisWriteAdapter } from '@nusoft/nuflow';
+import type { WorkflowStore } from '../migrate/store.js';
+export interface BuildCatalogueMisAdapterConfig {
+    store: WorkflowStore;
+    /** Absolute path to `nuos/docs/build/`. */
+    catalogueRoot: string;
+}
+export declare function createBuildCatalogueMisAdapter(config: BuildCatalogueMisAdapterConfig): MisWriteAdapter;

package/dist/runtime/mis-adapter.js

@@ -0,0 +1,364 @@
+/**
+ * `BuildCatalogueMisAdapter` — implements `@nusoft/nuflow`'s
+ * `MisWriteAdapter` for the build catalogue's write commands.
+ *
+ * Translates a typed `WriteIntent` from the build-catalogue pack into
+ * markdown edits + JSON workflow-store updates. The store and the
+ * markdown file stay in sync by always writing both at commit time.
+ *
+ * **Per-intent behaviour:**
+ *
+ * - `work_unit.advance_status`: replace the WU's status line in
+ *   markdown; append a Build catalogue history entry naming the
+ *   transition + reason; update the store record's `rawMarkdown`.
+ *
+ * - `work_unit.tick_acceptance_criterion`: append a Build catalogue
+ *   history entry naming the criterion index + evidence (no AC-list
+ *   parsing in v0.4; the maintainer hand-edits the AC list if they
+ *   want, the workflow record is canonical).
+ *
+ * - `decision.supersede`: edit BOTH the target's status line (`accepted
+ *   → superseded by D-NNN`) AND append a history entry to the
+ *   superseding decision noting what it supersedes.
+ *
+ * - `open_question.resolve`: edit the question's status line
+ *   (`active → resolved by D-NNN`) and append a history entry to the
+ *   resolving decision.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { replaceStatusLine, insertStatusLine, appendChangeLog, } from './markdown-edit.js';
+import { tickAcceptanceCriterion, parseAcceptanceCriteria } from './ac-parse.js';
+import { renderWorkUnit, renderDecision, renderOpenQuestion, renderPersona, } from './markdown-render.js';
+export function createBuildCatalogueMisAdapter(config) {
+    const { store, catalogueRoot } = config;
+    const adapter = {
+        canCommit(intent) {
+            // Create intents have placeholder subjects (e.g. wu-pending) that
+            // the workflow has rewritten to the real handle inside the typed
+            // payload. Skip the existence check for create intents.
+            if (isCreateIntent(intent.type))
+                return { allowed: true };
+            // For mutation intents, verify all subjects resolve to records
+            // the store knows about. The build-catalogue pack ensures handles
+            // are well-formed; the adapter ensures they exist.
+            for (const subject of intent.subjects) {
+                if (!store.has(subject.id)) {
+                    return {
+                        allowed: false,
+                        reason: `BuildCatalogueMisAdapter: no record for subject ${subject.kind}:${subject.id}`,
+                    };
+                }
+            }
+            return { allowed: true };
+        },
+        async commit(intent) {
+            switch (intent.type) {
+                case 'work_unit.create':
+                    await commitCreateRecord(store, catalogueRoot, intent, 'work_unit');
+                    break;
+                case 'decision.create':
+                    await commitCreateRecord(store, catalogueRoot, intent, 'decision');
+                    break;
+                case 'open_question.create':
+                    await commitCreateRecord(store, catalogueRoot, intent, 'open_question');
+                    break;
+                case 'persona.create':
+                    await commitCreateRecord(store, catalogueRoot, intent, 'persona');
+                    break;
+                case 'work_unit.advance_status':
+                    await commitAdvanceStatus(store, catalogueRoot, intent);
+                    break;
+                case 'work_unit.tick_acceptance_criterion':
+                    await commitTickAC(store, catalogueRoot, intent);
+                    break;
+                case 'decision.supersede':
+                    await commitSupersede(store, catalogueRoot, intent);
+                    break;
+                case 'open_question.resolve':
+                    await commitResolveQuestion(store, catalogueRoot, intent);
+                    break;
+                default:
+                    throw new Error(`BuildCatalogueMisAdapter: intent type ${intent.type} is not handled by the build-catalogue pack`);
+            }
+            // Persist the workflow store after the operation so the next
+            // CLI invocation sees the change.
+            await store.flush();
+            return {
+                commitRef: `cmt_${intent.intentId}`,
+                recordType: intent.type,
+                recordId: intent.subjects[0]?.id ?? 'unknown',
+                committedAt: new Date().toISOString(),
+            };
+        },
+    };
+    return adapter;
+}
+function isCreateIntent(intentType) {
+    return (intentType === 'work_unit.create' ||
+        intentType === 'decision.create' ||
+        intentType === 'open_question.create' ||
+        intentType === 'persona.create');
+}
+// ---------------------------------------------------------------------------
+// Per-intent commit handlers
+// ---------------------------------------------------------------------------
+async function commitCreateRecord(store, catalogueRoot, intent, register) {
+    let rendered;
+    let handle;
+    let number;
+    let slug;
+    let title;
+    let registerDir;
+    switch (register) {
+        case 'work_unit': {
+            const payload = intent.payload;
+            rendered = renderWorkUnit(payload);
+            handle = payload.handle;
+            number = payload.number;
+            slug = payload.slug;
+            title = payload.title;
+            registerDir = 'work-units';
+            break;
+        }
+        case 'decision': {
+            const payload = intent.payload;
+            rendered = renderDecision(payload);
+            handle = payload.handle;
+            number = payload.number;
+            slug = payload.slug;
+            title = payload.title;
+            registerDir = 'decisions';
+            break;
+        }
+        case 'open_question': {
+            const payload = intent.payload;
+            rendered = renderOpenQuestion(payload);
+            handle = payload.handle;
+            number = payload.number;
+            slug = payload.slug;
+            title = payload.title;
+            registerDir = 'open-questions';
+            break;
+        }
+        case 'persona': {
+            const payload = intent.payload;
+            rendered = renderPersona(payload);
+            handle = payload.handle;
+            number = payload.number;
+            slug = payload.slug;
+            title = payload.title;
+            registerDir = 'personas';
+            break;
+        }
+    }
+    // Filename pattern matches the migration parser:
+    //   work-units use just the number prefix (e.g. 200-foo.md)
+    //   decisions/questions/personas use the handle as prefix (D200-foo.md, Q200-foo.md, P200-foo.md)
+    const filename = register === 'work_unit'
+        ? `${String(number).padStart(3, '0')}-${slug}.md`
+        : `${handle}-${slug}.md`;
+    const relativeSourcePath = `${registerDir}/${filename}`;
+    const absolutePath = path.join(catalogueRoot, relativeSourcePath);
+    // Ensure the register dir exists (e.g. personas/ may not exist yet).
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, rendered, 'utf8');
+    const now = new Date().toISOString();
+    const record = {
+        handle,
+        number,
+        register,
+        title,
+        status: register === 'persona' ? '🟢 active' : initialStatusForRegister(register),
+        slug,
+        sourcePath: relativeSourcePath,
+        rawMarkdown: rendered,
+        fileModifiedAt: now,
+        migratedAt: now,
+        migratedFrom: 'markdown',
+    };
+    store.put(record);
+}
+function initialStatusForRegister(register) {
+    switch (register) {
+        case 'work_unit':
+            return '🔵 proposed';
+        case 'decision':
+            return 'proposed';
+        case 'open_question':
+            return 'active';
+        case 'persona':
+            return '🟢 active';
+    }
+}
+async function commitAdvanceStatus(store, catalogueRoot, intent) {
+    const payload = intent.payload;
+    const record = store.get(payload.targetHandle);
+    if (!record) {
+        throw new Error(`commitAdvanceStatus: no record for ${payload.targetHandle}`);
+    }
+    // Map workflow status names to user-facing markdown status text.
+    const statusEmoji = mapStatusToEmojiText(payload.toStatus);
+    const replaced = replaceStatusLine(record.rawMarkdown, statusEmoji);
+    let updatedMarkdown = replaced.replaced
+        ? replaced.updated
+        : insertStatusLine(record.rawMarkdown, statusEmoji);
+    updatedMarkdown = appendChangeLog(updatedMarkdown, {
+        isoTimestamp: new Date().toISOString(),
+        summary: `Status advanced ${payload.fromStatus} → ${payload.toStatus}.`,
+        details: payload.reason,
+        reference: `intent ${intent.intentId}`,
+    });
+    // Also update the structured `status` field on the record so the next
+    // workflow invocation reads the current state, not the stale migrated value.
+    await persist(store, catalogueRoot, record, updatedMarkdown, { status: statusEmoji });
+}
+async function commitTickAC(store, catalogueRoot, intent) {
+    const payload = intent.payload;
+    const record = store.get(payload.targetHandle);
+    if (!record) {
+        throw new Error(`commitTickAC: no record for ${payload.targetHandle}`);
+    }
+    // Try to flip the AC line in the markdown. If parsing succeeds we get
+    // the structural tick; otherwise we fall back to the audit-log-only
+    // approach (older/atypical AC shapes the parser doesn't recognise).
+    let workingMarkdown = record.rawMarkdown;
+    let acText = payload.criterionText;
+    let structuralTick = false;
+    try {
+        const acs = parseAcceptanceCriteria(record.rawMarkdown);
+        if (acs.length === 0) {
+            // No AC section recognised — audit-log-only.
+        }
+        else if (payload.criterionIndex >= acs.length) {
+            throw new Error(`commitTickAC: criterion index ${payload.criterionIndex} out of range (${record.handle} has ${acs.length} parsed AC entries)`);
+        }
+        else {
+            acText = acText ?? acs[payload.criterionIndex].text;
+            workingMarkdown = tickAcceptanceCriterion(record.rawMarkdown, payload.criterionIndex);
+            structuralTick = true;
+        }
+    }
+    catch (err) {
+        // Re-throw out-of-range errors; tolerate parse failures.
+        if (err instanceof Error && err.message.includes('out of range')) {
+            throw err;
+        }
+    }
+    const summary = acText
+        ? `Acceptance criterion ${payload.criterionIndex + 1} ticked: "${acText}".`
+        : `Acceptance criterion at index ${payload.criterionIndex} ticked.`;
+    const updatedMarkdown = appendChangeLog(workingMarkdown, {
+        isoTimestamp: new Date().toISOString(),
+        summary: structuralTick ? summary : `${summary} (audit-log-only — AC list not recognised)`,
+        details: `Evidence: ${payload.evidence}`,
+        reference: `intent ${intent.intentId}`,
+    });
+    await persist(store, catalogueRoot, record, updatedMarkdown);
+}
+async function commitSupersede(store, catalogueRoot, intent) {
+    const payload = intent.payload;
+    const target = store.get(payload.targetHandle);
+    const superseding = store.get(payload.supersedingHandle);
+    if (!target)
+        throw new Error(`commitSupersede: no record for target ${payload.targetHandle}`);
+    if (!superseding) {
+        throw new Error(`commitSupersede: no record for superseding ${payload.supersedingHandle}`);
+    }
+    // Target: status accepted → superseded by D-NNN
+    const targetStatus = `superseded by ${payload.supersedingHandle}`;
+    const targetReplaced = replaceStatusLine(target.rawMarkdown, targetStatus);
+    let targetMarkdown = targetReplaced.replaced
+        ? targetReplaced.updated
+        : insertStatusLine(target.rawMarkdown, targetStatus);
+    targetMarkdown = appendChangeLog(targetMarkdown, {
+        isoTimestamp: new Date().toISOString(),
+        summary: `Superseded by ${payload.supersedingHandle}.`,
+        details: payload.reason,
+        reference: `intent ${intent.intentId}`,
+    });
+    await persist(store, catalogueRoot, target, targetMarkdown, { status: targetStatus });
+    // Superseding: append a Build catalogue history entry naming what it supersedes.
+    const supersedingMarkdown = appendChangeLog(superseding.rawMarkdown, {
+        isoTimestamp: new Date().toISOString(),
+        summary: `Supersedes ${payload.targetHandle}.`,
+        details: payload.reason,
+        reference: `intent ${intent.intentId}`,
+    });
+    await persist(store, catalogueRoot, superseding, supersedingMarkdown);
+}
+async function commitResolveQuestion(store, catalogueRoot, intent) {
+    const payload = intent.payload;
+    const question = store.get(payload.targetHandle);
+    const decision = store.get(payload.resolvingDecisionHandle);
+    if (!question) {
+        throw new Error(`commitResolveQuestion: no record for question ${payload.targetHandle}`);
+    }
+    if (!decision) {
+        throw new Error(`commitResolveQuestion: no record for resolving decision ${payload.resolvingDecisionHandle}`);
+    }
+    const questionStatus = `resolved by ${payload.resolvingDecisionHandle}`;
+    const questionReplaced = replaceStatusLine(question.rawMarkdown, questionStatus);
+    let questionMarkdown = questionReplaced.replaced
+        ? questionReplaced.updated
+        : insertStatusLine(question.rawMarkdown, questionStatus);
+    questionMarkdown = appendChangeLog(questionMarkdown, {
+        isoTimestamp: new Date().toISOString(),
+        summary: `Resolved by ${payload.resolvingDecisionHandle}.`,
+        details: payload.reason,
+        reference: `intent ${intent.intentId}`,
+    });
+    await persist(store, catalogueRoot, question, questionMarkdown, { status: questionStatus });
+    const decisionMarkdown = appendChangeLog(decision.rawMarkdown, {
+        isoTimestamp: new Date().toISOString(),
+        summary: `Resolves ${payload.targetHandle}.`,
+        details: payload.reason,
+        reference: `intent ${intent.intentId}`,
+    });
+    await persist(store, catalogueRoot, decision, decisionMarkdown);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function persist(store, catalogueRoot, record, newRawMarkdown, fieldUpdates = {}) {
+    const sourceAbsolute = path.join(catalogueRoot, record.sourcePath);
+    await writeFile(sourceAbsolute, newRawMarkdown, 'utf8');
+    const updatedRecord = {
+        ...record,
+        rawMarkdown: newRawMarkdown,
+        fileModifiedAt: new Date().toISOString(),
+        // Note: migratedAt is preserved (it's the original migration time);
+        // fileModifiedAt is updated to track the latest write.
+        ...(fieldUpdates.status !== undefined ? { status: fieldUpdates.status } : {}),
+    };
+    store.put(updatedRecord);
+}
+function mapStatusToEmojiText(workflowStatus) {
+    // The build-catalogue pack uses internal status enum strings
+    // (proposed/ready/in_progress/in_review/completed/superseded/...).
+    // The catalogue's markdown convention uses emoji-prefixed forms.
+    // Map them here so workflows speak in their typed enum but the
+    // markdown reads in the human convention.
+    switch (workflowStatus) {
+        case 'proposed':
+            return '🔵 proposed';
+        case 'ready':
+            return '🟢 ready';
+        case 'in_progress':
+            return '🟡 in_progress';
+        case 'in_review':
+            return '🟣 in_review';
+        case 'completed':
+            return '✅ completed';
+        case 'superseded':
+            return '🟣 superseded';
+        case 'cancelled':
+            return '⚫ cancelled';
+        case 'deferred-with-trigger':
+            return '🔵 deferred-with-trigger';
+        case 'blocked-on-question':
+            return '🔴 blocked-on-question';
+        default:
+            return workflowStatus;
+    }
+}

package/dist/runtime/runtime.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Build-catalogue NuFlow runtime factory.
+ *
+ * Wires the NuFlow runtime with stub memory adapters + the build-
+ * catalogue MIS adapter + the build-catalogue workflow pack, ready to
+ * accept the four flag-driven write commands of Phase H part 2.
+ *
+ * Memory adapters are stubs — the build catalogue's "memory" is the
+ * JSON workflow store, not NuVector retrieval. The runtime's
+ * `MemoryContextAdapter` and `WorkflowMemoryAdapter` are wired with
+ * no-op implementations because the workflows in this pack do not
+ * use them.
+ */
+import { type NuFlowRuntime } from '@nusoft/nuflow';
+import type { WorkflowStore } from '../migrate/store.js';
+export interface CreateBuildCatalogueRuntimeConfig {
+    store: WorkflowStore;
+    catalogueRoot: string;
+}
+export declare function createBuildCatalogueRuntime(config: CreateBuildCatalogueRuntimeConfig): NuFlowRuntime;

package/dist/runtime/runtime.js

@@ -0,0 +1,39 @@
+/**
+ * Build-catalogue NuFlow runtime factory.
+ *
+ * Wires the NuFlow runtime with stub memory adapters + the build-
+ * catalogue MIS adapter + the build-catalogue workflow pack, ready to
+ * accept the four flag-driven write commands of Phase H part 2.
+ *
+ * Memory adapters are stubs — the build catalogue's "memory" is the
+ * JSON workflow store, not NuVector retrieval. The runtime's
+ * `MemoryContextAdapter` and `WorkflowMemoryAdapter` are wired with
+ * no-op implementations because the workflows in this pack do not
+ * use them.
+ */
+import { createNuFlowRuntime } from '@nusoft/nuflow';
+import { nuosBuildCataloguePack } from '@nusoft/nuflow-pack-nuos-build-catalogue';
+import { createBuildCatalogueMisAdapter } from './mis-adapter.js';
+export function createBuildCatalogueRuntime(config) {
+    const runtime = createNuFlowRuntime({
+        memoryContextAdapter: {
+            retrieve: async () => ({
+                items: [],
+                retrievalId: `r_${Date.now()}`,
+                retrievedAt: new Date().toISOString(),
+                totalCandidates: 0,
+            }),
+        },
+        workflowMemoryAdapter: {
+            remember: async (record) => ({ ref: record.id }),
+        },
+        misWriteAdapter: createBuildCatalogueMisAdapter({
+            store: config.store,
+            catalogueRoot: config.catalogueRoot,
+        }),
+        policyGates: [],
+        tenant: 'nuos-build-catalogue',
+    });
+    nuosBuildCataloguePack.register(runtime);
+    return runtime;
+}

package/dist/search/format.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Output formatter — human-readable table or JSON.
+ */
+import type { SearchHit } from './query.js';
+export declare function formatHumanReadable(hits: SearchHit[]): string;
+export declare function formatJson(hits: SearchHit[]): string;