@nusoft/nuos-build-catalogue 0.9.0 → 0.10.1

package/dist/commands/init.js

@@ -0,0 +1,289 @@
+/**
+ * `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 { mkdir, readFile, writeFile, copyFile, readdir, access } from 'node:fs/promises';
+import { existsSync, constants } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { askUntilValid, validate } from './prompt.js';
+const __filename = fileURLToPath(import.meta.url);
+const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..', '..');
+const TEMPLATES_ROOT = path.resolve(PACKAGE_ROOT, 'templates');
+const PROTOCOL_FILES = [
+    'start-of-session.md',
+    'end-of-session.md',
+    'wu-new.md',
+    'persona-new.md',
+];
+export async function cmdInit(prompt, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const today = new Date().toISOString().slice(0, 10);
+    // Refuse if docs/build/ already exists — this is a one-shot bootstrap.
+    if (existsSync(path.join(cwd, 'docs', 'build'))) {
+        return {
+            output: `nuos-catalogue init: docs/build/ already exists at ${cwd}. Refusing to clobber. If you want to refresh the protocols only, use \`nuos-catalogue install-protocols\` instead.`,
+            exitCode: 1,
+        };
+    }
+    // Verify templates are bundled with this CLI install.
+    if (!existsSync(TEMPLATES_ROOT)) {
+        return {
+            output: `nuos-catalogue init: bundled templates not found at ${TEMPLATES_ROOT}. The CLI install is incomplete; reinstall the package.`,
+            exitCode: 1,
+        };
+    }
+    // Gather inputs.
+    const projectDefault = path.basename(cwd);
+    let name = options.name;
+    let tagline = options.tagline;
+    let domain = options.domain;
+    let role = options.role;
+    if (!options.nonInteractive) {
+        prompt.print('Initialising a NuOS Build Method catalogue.');
+        prompt.print('');
+        if (!name) {
+            name = await askUntilValid(prompt, `Project name [${projectDefault}]: `, (v) => (v.trim().length === 0 ? null : null) // empty allowed; default applied below
+            );
+            if (!name.trim())
+                name = projectDefault;
+        }
+        if (!tagline) {
+            tagline = await askUntilValid(prompt, 'One-sentence tagline (what this project is): ', (v) => validate.nonEmpty(v, 'tagline'));
+        }
+        if (!domain) {
+            domain = (await prompt.ask('Domain (e.g. example.com; empty for none): ')).trim() || 'n/a';
+        }
+        if (!role) {
+            role = await prompt.askChoice('Project role?', ['consumer', 'standalone', 'harness']);
+        }
+        const confirm = await prompt.confirm(`About to create docs/build/, methodfile.json, .claude/commands/<protocols>, append to CLAUDE.md, update .gitignore, and run first migrate. Proceed?`, true);
+        if (!confirm) {
+            return { output: 'init cancelled by operator.', exitCode: 1 };
+        }
+    }
+    else {
+        if (!name)
+            name = projectDefault;
+        if (!tagline)
+            tagline = '';
+        if (!domain)
+            domain = 'n/a';
+        if (!role)
+            role = 'consumer';
+    }
+    const subs = {
+        '{{PROJECT_NAME}}': name,
+        '{{PROJECT_TAGLINE}}': tagline,
+        '{{PROJECT_DOMAIN}}': domain,
+        '{{PROJECT_ROLE}}': role,
+        '{{TODAY}}': today,
+    };
+    const log = [];
+    const log_line = (msg) => {
+        log.push(msg);
+        prompt.print(msg);
+    };
+    // Step 1: docs/build/ scaffold from starter-kit
+    log_line('  · creating docs/build/ from bundled starter-kit');
+    await copyDirWithSubstitution(path.join(TEMPLATES_ROOT, 'starter-kit', 'docs', 'build'), path.join(cwd, 'docs', 'build'), subs);
+    // Step 2: methodfile.json at repo root
+    log_line('  · writing methodfile.json at repo root');
+    const methodfileSrc = await readFile(path.join(TEMPLATES_ROOT, 'starter-kit', 'methodfile.json'), 'utf8');
+    await writeFile(path.join(cwd, 'methodfile.json'), substitute(methodfileSrc, subs), 'utf8');
+    // Step 3: copy protocols into .claude/commands/
+    const claudeCommandsDir = path.join(cwd, '.claude', 'commands');
+    await mkdir(claudeCommandsDir, { recursive: true });
+    for (const protocol of PROTOCOL_FILES) {
+        const dest = path.join(claudeCommandsDir, protocol);
+        const existed = existsSync(dest);
+        await copyFile(path.join(TEMPLATES_ROOT, 'protocols', protocol), dest);
+        log_line(`  · ${existed ? 'overwrote' : 'installed'} .claude/commands/${protocol}`);
+    }
+    // Step 4: CLAUDE.md
+    const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+    const catalogueSection = renderCatalogueSection(name);
+    if (existsSync(claudeMdPath)) {
+        const existing = await readFile(claudeMdPath, 'utf8');
+        if (existing.includes('## Build catalogue (NuOS Build Method)')) {
+            log_line('  · CLAUDE.md already mentions the catalogue; not appending');
+        }
+        else {
+            const trailing = existing.endsWith('\n') ? '' : '\n';
+            await writeFile(claudeMdPath, `${existing}${trailing}\n${catalogueSection}\n`, 'utf8');
+            log_line('  · appended Build catalogue section to CLAUDE.md');
+        }
+    }
+    else {
+        const stub = `# ${name} — Project Bootstrap\n\n${catalogueSection}\n`;
+        await writeFile(claudeMdPath, stub, 'utf8');
+        log_line('  · created CLAUDE.md with Build catalogue section');
+    }
+    // Step 5: .gitignore
+    const gitignorePath = path.join(cwd, '.gitignore');
+    await ensureGitignoreEntries(gitignorePath, log_line);
+    prompt.print('');
+    prompt.print(`✅ Catalogue initialised at ${path.join(cwd, 'docs/build')}`);
+    prompt.print('');
+    prompt.print('Next steps:');
+    prompt.print('  1. Set env vars in your shell profile so the CLI knows where this catalogue lives:');
+    prompt.print(`       export NUOS_CATALOGUE_BUILD_ROOT="${path.join(cwd, 'docs/build')}"`);
+    prompt.print(`       export NUOS_CATALOGUE_WORKFLOWS="${path.join(cwd, '.nuos-catalogue/workflows.json')}"`);
+    prompt.print('  2. Edit docs/build/STATE.md to describe the actual current state of this project.');
+    prompt.print('  3. File the first WU: `nuos-catalogue wu create`');
+    prompt.print('');
+    prompt.print('To refresh protocols only later (without re-running init): `nuos-catalogue install-protocols`');
+    return { output: '', exitCode: 0 };
+}
+export async function cmdInstallProtocols(prompt, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (!existsSync(TEMPLATES_ROOT)) {
+        return {
+            output: `nuos-catalogue install-protocols: bundled templates not found at ${TEMPLATES_ROOT}.`,
+            exitCode: 1,
+        };
+    }
+    const claudeCommandsDir = path.join(cwd, '.claude', 'commands');
+    await mkdir(claudeCommandsDir, { recursive: true });
+    const lines = [];
+    for (const protocol of PROTOCOL_FILES) {
+        const src = path.join(TEMPLATES_ROOT, 'protocols', protocol);
+        const dest = path.join(claudeCommandsDir, protocol);
+        let action = 'created';
+        if (existsSync(dest)) {
+            const [srcContent, destContent] = await Promise.all([
+                readFile(src, 'utf8'),
+                readFile(dest, 'utf8'),
+            ]);
+            action = srcContent === destContent ? 'unchanged' : 'updated';
+        }
+        if (action !== 'unchanged') {
+            await copyFile(src, dest);
+        }
+        lines.push(`  ${action.padEnd(10)} .claude/commands/${protocol}`);
+    }
+    prompt.print(`Refreshing protocols at ${claudeCommandsDir}:`);
+    for (const l of lines)
+        prompt.print(l);
+    return { output: '', exitCode: 0 };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function substitute(content, subs) {
+    let result = content;
+    for (const [key, value] of Object.entries(subs)) {
+        result = result.split(key).join(value);
+    }
+    return result;
+}
+async function copyDirWithSubstitution(src, dest, subs) {
+    await mkdir(dest, { recursive: true });
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryName = entry.name;
+        const srcPath = path.join(src, entryName);
+        const destPath = path.join(dest, entryName);
+        if (entry.isDirectory()) {
+            await copyDirWithSubstitution(srcPath, destPath, subs);
+        }
+        else if (entry.isFile()) {
+            const content = await readFile(srcPath, 'utf8');
+            await writeFile(destPath, substitute(content, subs), 'utf8');
+        }
+    }
+}
+async function ensureGitignoreEntries(gitignorePath, log_line) {
+    let existing = '';
+    try {
+        await access(gitignorePath, constants.F_OK);
+        existing = await readFile(gitignorePath, 'utf8');
+    }
+    catch {
+        // No .gitignore — we'll create one with just the catalogue rules.
+    }
+    const additions = [];
+    const hasUnanchoredBuild = /(?:^|\n)\s*build\/\s*(?:\n|$)/.test(existing);
+    const hasOverride = /!docs\/build\/(?:\*\*)?/.test(existing);
+    const hasNuosCatalogueIgnore = /^\s*\.nuos-catalogue\//m.test(existing);
+    if (hasUnanchoredBuild && !hasOverride) {
+        additions.push('', '# Override: docs/build/ is the NuOS Build Method catalogue, NOT a build artefact.', '# The unanchored `build/` rule above matches it; this negation pattern keeps the', '# catalogue tracked. Same gotcha caught at nuos Session 53.', '!docs/build/', '!docs/build/**');
+    }
+    if (!hasNuosCatalogueIgnore) {
+        additions.push('', '# NuOS Build Method catalogue — local workflow store (per nuos D047).', '# Markdown is canonical in Mode 1; the JSON store is regenerated by', '# `nuos-catalogue migrate` and does not need to live in git.', '.nuos-catalogue/');
+    }
+    if (additions.length === 0) {
+        log_line('  · .gitignore already has the catalogue entries; nothing to add');
+        return;
+    }
+    const trailing = existing.endsWith('\n') || existing.length === 0 ? '' : '\n';
+    const newContent = `${existing}${trailing}${additions.join('\n')}\n`;
+    await writeFile(gitignorePath, newContent, 'utf8');
+    log_line(existing.length === 0
+        ? '  · created .gitignore with catalogue rules'
+        : '  · appended catalogue rules to .gitignore');
+}
+function renderCatalogueSection(projectName) {
+    return `## Build catalogue (NuOS Build Method)
+
+This repo runs **the NuOS Build Method**. The catalogue lives at [docs/build/](docs/build/) and tracks work units, decisions, open questions, personas, sessions, and risks.
+
+### At the start of every session
+
+Run \`/start-of-session\` (or follow [docs/build/START-OF-SESSION.md](docs/build/START-OF-SESSION.md)).
+
+### At the end of every session
+
+Run \`/end-of-session\`. **Without it, work is lost.**
+
+### Daily use via the CLI
+
+Set these env vars in your shell profile so commands work without flags:
+
+\`\`\`bash
+export NUOS_CATALOGUE_BUILD_ROOT="$(pwd)/docs/build"
+export NUOS_CATALOGUE_WORKFLOWS="$(pwd)/.nuos-catalogue/workflows.json"
+\`\`\`
+
+Then:
+
+\`\`\`bash
+nuos-catalogue wu create                          # interactive — file a new WU
+nuos-catalogue wu list                            # what's in flight
+nuos-catalogue wu advance <handle> --to=in_progress
+nuos-catalogue wu tick <handle> --index=N --evidence="commit abc123"
+nuos-catalogue decision create
+nuos-catalogue question create
+nuos-catalogue regenerate                         # check store-vs-disk drift
+nuos-catalogue summary                            # totals by register
+\`\`\`
+
+To refresh the protocol bodies later (after a CLI upgrade):
+
+\`\`\`bash
+nuos-catalogue install-protocols
+\`\`\`
+
+### What never to do
+
+- Never make architectural decisions without recording them in \`docs/build/decisions/\`
+- Never start work outside the active work unit without recording why
+- Never skip end-of-session
+- Never modify a committed \`accepted\` decision file (use \`decision supersede\` instead)`;
+}

package/dist/commands/prompt.d.ts

@@ -0,0 +1,44 @@
+/**
+ * readline-based prompt helpers for interactive CLI commands.
+ *
+ * Built on node:readline/promises (no new deps). The prompt object
+ * carries an open readline interface; callers are responsible for
+ * closing it via `prompt.close()` when done. The pattern is:
+ *
+ *   const p = openPrompt();
+ *   try {
+ *     const title = await p.ask('Title: ');
+ *     // ...
+ *   } finally {
+ *     p.close();
+ *   }
+ *
+ * Tests substitute a mock implementation by injecting a Prompt object
+ * directly to the create handlers; the readline-backed openPrompt is
+ * only invoked from the CLI shell.
+ */
+export interface Prompt {
+    ask(question: string): Promise<string>;
+    askMultiline(question: string, sentinel?: string): Promise<string>;
+    askChoice(question: string, choices: string[]): Promise<string>;
+    confirm(question: string, defaultYes?: boolean): Promise<boolean>;
+    print(line: string): void;
+    close(): void;
+}
+export declare function openPrompt(): Prompt;
+/**
+ * Validation helpers that return `null` when valid, error string when not.
+ */
+export declare const validate: {
+    nonEmpty(value: string, fieldName: string): string | null;
+    matches(value: string, pattern: RegExp, fieldName: string, hint?: string): string | null;
+};
+/**
+ * Repeatedly ask a question until validation passes. Validators can
+ * return null (valid) or an error string (invalid; will be shown and
+ * the question re-asked).
+ */
+export declare function askUntilValid(p: Prompt, question: string, validator: (value: string) => string | null, options?: {
+    multiline?: boolean;
+    sentinel?: string;
+}): Promise<string>;

package/dist/commands/prompt.js

@@ -0,0 +1,100 @@
+/**
+ * readline-based prompt helpers for interactive CLI commands.
+ *
+ * Built on node:readline/promises (no new deps). The prompt object
+ * carries an open readline interface; callers are responsible for
+ * closing it via `prompt.close()` when done. The pattern is:
+ *
+ *   const p = openPrompt();
+ *   try {
+ *     const title = await p.ask('Title: ');
+ *     // ...
+ *   } finally {
+ *     p.close();
+ *   }
+ *
+ * Tests substitute a mock implementation by injecting a Prompt object
+ * directly to the create handlers; the readline-backed openPrompt is
+ * only invoked from the CLI shell.
+ */
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+export function openPrompt() {
+    const rl = createInterface({ input: stdin, output: stdout });
+    return {
+        async ask(question) {
+            return (await rl.question(question)).trim();
+        },
+        async askMultiline(question, sentinel = '.') {
+            stdout.write(`${question}\n  (end with a single line containing only "${sentinel}")\n`);
+            const lines = [];
+            while (true) {
+                const line = await rl.question('');
+                if (line.trim() === sentinel)
+                    break;
+                lines.push(line);
+            }
+            return lines.join('\n').trim();
+        },
+        async askChoice(question, choices) {
+            const numbered = choices.map((c, i) => `  ${i + 1}. ${c}`).join('\n');
+            while (true) {
+                const answer = (await rl.question(`${question}\n${numbered}\nChoose (1–${choices.length}): `)).trim();
+                const idx = parseInt(answer, 10);
+                if (Number.isInteger(idx) && idx >= 1 && idx <= choices.length) {
+                    return choices[idx - 1];
+                }
+                // Allow typing the choice text directly.
+                const direct = choices.find((c) => c.toLowerCase() === answer.toLowerCase());
+                if (direct)
+                    return direct;
+                stdout.write(`(unrecognised — try a number 1–${choices.length} or the choice text)\n`);
+            }
+        },
+        async confirm(question, defaultYes = true) {
+            const suffix = defaultYes ? '[Y/n]' : '[y/N]';
+            const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
+            if (answer === '')
+                return defaultYes;
+            return answer === 'y' || answer === 'yes';
+        },
+        print(line) {
+            stdout.write(`${line}\n`);
+        },
+        close() {
+            rl.close();
+        },
+    };
+}
+/**
+ * Validation helpers that return `null` when valid, error string when not.
+ */
+export const validate = {
+    nonEmpty(value, fieldName) {
+        if (value.trim().length === 0)
+            return `${fieldName} must be non-empty`;
+        return null;
+    },
+    matches(value, pattern, fieldName, hint) {
+        if (!pattern.test(value)) {
+            return `${fieldName} did not match expected pattern${hint ? ` (${hint})` : ''}`;
+        }
+        return null;
+    },
+};
+/**
+ * Repeatedly ask a question until validation passes. Validators can
+ * return null (valid) or an error string (invalid; will be shown and
+ * the question re-asked).
+ */
+export async function askUntilValid(p, question, validator, options = {}) {
+    while (true) {
+        const value = options.multiline
+            ? await p.askMultiline(question, options.sentinel)
+            : await p.ask(question);
+        const error = validator(value);
+        if (!error)
+            return value;
+        p.print(`(${error})`);
+    }
+}

package/dist/commands/write.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Phase H part 2 — flag-driven write commands.
+ *
+ * Each handler:
+ *   1. Validates the flags
+ *   2. Looks up the target record from the store
+ *   3. Builds a typed `CaptureInput` for the relevant workflow
+ *   4. Drives the NuFlow lifecycle through the runtime
+ *   5. Reports the result
+ *
+ * No interactive prompts; flag-driven only. Interactive `create`
+ * commands are deferred (Phase H part 3).
+ */
+import type { NuFlowRuntime } from '@nusoft/nuflow';
+import type { WorkflowStore } from '../migrate/store.js';
+export interface WriteHandlerResult {
+    output: string;
+    exitCode: number;
+}
+export declare function cmdWuAdvance(store: WorkflowStore, runtime: NuFlowRuntime, args: {
+    handle?: string;
+    to?: string;
+    reason?: string;
+}): Promise<WriteHandlerResult>;
+export declare function cmdWuTick(store: WorkflowStore, runtime: NuFlowRuntime, args: {
+    handle?: string;
+    index?: number;
+    evidence?: string;
+}): Promise<WriteHandlerResult>;
+export declare function cmdDecisionSupersede(store: WorkflowStore, runtime: NuFlowRuntime, args: {
+    target?: string;
+    by?: string;
+    reason?: string;
+}): Promise<WriteHandlerResult>;
+export declare function cmdQuestionResolve(store: WorkflowStore, runtime: NuFlowRuntime, args: {
+    qHandle?: string;
+    by?: string;
+    reason?: string;
+}): Promise<WriteHandlerResult>;