@nusoft/nuos-build-catalogue 0.10.1 → 0.11.0

package/dist/cli.js

@@ -12,20 +12,22 @@
  */
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { selectEmbedderFromEnv } from './embedder/select.js';
-import { openStore } from './store/open.js';
-import { runIndex } from './indexer/upsert.js';
-import { runSearch } from './search/query.js';
-import { formatHumanReadable, formatJson } from './search/format.js';
+// Static imports — these don't pull in NuVector / NuFlow transitively.
+// init / migrate / regenerate / summary / list / show / install-protocols all
+// work without those native deps being installed.
 import { runMigrate } from './migrate/run.js';
 import { openWorkflowStore } from './migrate/store.js';
 import { listRegister, showRecord, commandToRegister, listAcrossRegisters, } from './commands/handlers.js';
 import { runRegenerate } from './regenerate/check.js';
-import { createBuildCatalogueRuntime } from './runtime/runtime.js';
-import { cmdWuAdvance, cmdWuTick, cmdDecisionSupersede, cmdQuestionResolve, } from './commands/write.js';
-import { cmdWuCreate, cmdDecisionCreate, cmdQuestionCreate, cmdPersonaCreate, } from './commands/create.js';
 import { openPrompt } from './commands/prompt.js';
 import { cmdInit, cmdInstallProtocols } from './commands/init.js';
+// Dynamic imports below — index / search / write commands / create commands
+// load NuVector or NuFlow transitively. Loading them at module-parse time
+// would crash on platforms where the NuVector native binary isn't resolved
+// (e.g. fresh npx installs before @nusoft/nuvector ships its platform-specific
+// binaries as optionalDependencies). Lazy-load so the lightweight commands
+// (init, migrate, etc.) work universally; the heavyweight commands degrade
+// gracefully when their deps are missing.
 const __filename = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..');
 // Defaults resolve in this order: env var > flag-supplied > package-relative
@@ -65,6 +67,9 @@ async function cmdIndex(flags) {
     const catalogueRoot = String(flags['catalogue'] ?? DEFAULT_CATALOGUE_ROOT);
     const indexPath = String(flags['index'] ?? DEFAULT_INDEX_PATH);
     const hashPath = String(flags['hash-file'] ?? DEFAULT_HASH_PATH);
+    const { selectEmbedderFromEnv } = await import('./embedder/select.js');
+    const { openStore } = await import('./store/open.js');
+    const { runIndex } = await import('./indexer/upsert.js');
     const embedder = await selectEmbedderFromEnv();
     const store = await openStore({ storagePath: indexPath, dimensions: embedder.dimensions });
     console.log(`indexing ${catalogueRoot}`);
@@ -95,6 +100,10 @@ async function cmdSearch(positional, flags) {
         process.exit(2);
     }
     const indexPath = String(flags['index'] ?? DEFAULT_INDEX_PATH);
+    const { selectEmbedderFromEnv } = await import('./embedder/select.js');
+    const { openStore } = await import('./store/open.js');
+    const { runSearch } = await import('./search/query.js');
+    const { formatHumanReadable, formatJson } = await import('./search/format.js');
     const embedder = await selectEmbedderFromEnv();
     const store = await openStore({ storagePath: indexPath, dimensions: embedder.dimensions });
     const limit = flags['limit'] ? Number(flags['limit']) : 10;
@@ -190,6 +199,8 @@ async function cmdRegisterDispatch(command, positional, flags) {
                 console.error(`'advance' is a wu subcommand only`);
                 process.exit(2);
             }
+            const { createBuildCatalogueRuntime } = await import('./runtime/runtime.js');
+            const { cmdWuAdvance } = await import('./commands/write.js');
             const runtime = createBuildCatalogueRuntime({ store, catalogueRoot: buildRoot });
             const result = await cmdWuAdvance(store, runtime, {
                 handle: positional[1],
@@ -205,6 +216,8 @@ async function cmdRegisterDispatch(command, positional, flags) {
                 console.error(`'tick' is a wu subcommand only`);
                 process.exit(2);
             }
+            const { createBuildCatalogueRuntime } = await import('./runtime/runtime.js');
+            const { cmdWuTick } = await import('./commands/write.js');
             const runtime = createBuildCatalogueRuntime({ store, catalogueRoot: buildRoot });
             const result = await cmdWuTick(store, runtime, {
                 handle: positional[1],
@@ -220,6 +233,8 @@ async function cmdRegisterDispatch(command, positional, flags) {
                 console.error(`'supersede' is a decision subcommand only`);
                 process.exit(2);
             }
+            const { createBuildCatalogueRuntime } = await import('./runtime/runtime.js');
+            const { cmdDecisionSupersede } = await import('./commands/write.js');
             const runtime = createBuildCatalogueRuntime({ store, catalogueRoot: buildRoot });
             const result = await cmdDecisionSupersede(store, runtime, {
                 target: positional[1],
@@ -235,6 +250,8 @@ async function cmdRegisterDispatch(command, positional, flags) {
                 console.error(`'resolve' is a question subcommand only`);
                 process.exit(2);
             }
+            const { createBuildCatalogueRuntime } = await import('./runtime/runtime.js');
+            const { cmdQuestionResolve } = await import('./commands/write.js');
             const runtime = createBuildCatalogueRuntime({ store, catalogueRoot: buildRoot });
             const result = await cmdQuestionResolve(store, runtime, {
                 qHandle: positional[1],
@@ -246,6 +263,8 @@ async function cmdRegisterDispatch(command, positional, flags) {
             break;
         }
         case 'create': {
+            const { createBuildCatalogueRuntime } = await import('./runtime/runtime.js');
+            const { cmdWuCreate, cmdDecisionCreate, cmdQuestionCreate, cmdPersonaCreate, } = await import('./commands/create.js');
             const runtime = createBuildCatalogueRuntime({ store, catalogueRoot: buildRoot });
             const prompt = openPrompt();
             try {

package/dist/commands/init.d.ts

@@ -5,8 +5,15 @@
  *   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)
+ *   3. Fan the four protocols out to ALL THREE supported AI coding tools:
+ *      Claude Code (.claude/commands/<n>.md), OpenCode
+ *      (.opencode/commands/<n>.md), and Codex CLI
+ *      (.agents/skills/<n>/SKILL.md). Each tool reads commands from a
+ *      different path with slightly different frontmatter; the body is
+ *      identical across all three. We write to all three by default — the
+ *      files are tiny and harmless if a tool is unused. A consumer of
+ *      this catalogue on any of the three tools gets working slash
+ *      commands without extra configuration.
  *   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
@@ -16,7 +23,8 @@
  *   6. Run a first migrate to verify
  *
  * Companion command: `install-protocols` refreshes just step 3 from the
- * canonical bodies bundled in this CLI package.
+ * canonical bodies bundled in this CLI package, also fanning out to all
+ * three tool paths.
  */
 import type { Prompt } from './prompt.js';
 export interface InitOptions {

package/dist/commands/init.js

@@ -5,8 +5,15 @@
  *   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)
+ *   3. Fan the four protocols out to ALL THREE supported AI coding tools:
+ *      Claude Code (.claude/commands/<n>.md), OpenCode
+ *      (.opencode/commands/<n>.md), and Codex CLI
+ *      (.agents/skills/<n>/SKILL.md). Each tool reads commands from a
+ *      different path with slightly different frontmatter; the body is
+ *      identical across all three. We write to all three by default — the
+ *      files are tiny and harmless if a tool is unused. A consumer of
+ *      this catalogue on any of the three tools gets working slash
+ *      commands without extra configuration.
  *   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
@@ -16,9 +23,10 @@
  *   6. Run a first migrate to verify
  *
  * Companion command: `install-protocols` refreshes just step 3 from the
- * canonical bodies bundled in this CLI package.
+ * canonical bodies bundled in this CLI package, also fanning out to all
+ * three tool paths.
  */
-import { mkdir, readFile, writeFile, copyFile, readdir, access } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, readdir, access } from 'node:fs/promises';
 import { existsSync, constants } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -32,6 +40,41 @@ const PROTOCOL_FILES = [
     'wu-new.md',
     'persona-new.md',
 ];
+/**
+ * One-line descriptions used in the frontmatter of installed protocol
+ * files. Tools surface this text in their command list, so it should
+ * read as an imperative summary.
+ */
+const PROTOCOL_DESCRIPTIONS = {
+    'start-of-session': 'Read STATE, last session log, active WU; surface next action',
+    'end-of-session': 'Write session log, update STATE + indices, move ✅ WUs to done/, commit',
+    'wu-new': 'Create a new work unit with the six-field outcome shape (per D046)',
+    'persona-new': 'Create a new P-NNN persona with the seven dimensions and acid-test (per D046)',
+};
+const TOOLS = {
+    claude: {
+        label: 'Claude Code',
+        destPath: (slug) => path.join('.claude', 'commands', `${slug}.md`),
+        render: (slug, body) => withFrontmatter({ description: PROTOCOL_DESCRIPTIONS[slug] ?? '' }, body),
+    },
+    opencode: {
+        label: 'OpenCode',
+        destPath: (slug) => path.join('.opencode', 'commands', `${slug}.md`),
+        render: (slug, body) => withFrontmatter({ description: PROTOCOL_DESCRIPTIONS[slug] ?? '' }, body),
+    },
+    codex: {
+        label: 'Codex CLI',
+        destPath: (slug) => path.join('.agents', 'skills', slug, 'SKILL.md'),
+        render: (slug, body) => withFrontmatter({ name: slug, description: PROTOCOL_DESCRIPTIONS[slug] ?? '' }, body),
+    },
+};
+function withFrontmatter(fields, body) {
+    const lines = ['---'];
+    for (const [k, v] of Object.entries(fields))
+        lines.push(`${k}: ${v}`);
+    lines.push('---', '', '');
+    return lines.join('\n') + body;
+}
 export async function cmdInit(prompt, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const today = new Date().toISOString().slice(0, 10);
@@ -107,14 +150,20 @@ export async function cmdInit(prompt, options = {}) {
     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 3: fan protocols out to all three supported AI coding tools.
+    // Each tool reads project-level commands from its own path; we install
+    // to all three by default so users on any of Claude Code / OpenCode /
+    // Codex CLI get working slash commands without extra configuration.
+    for (const protocolFile of PROTOCOL_FILES) {
+        const slug = path.basename(protocolFile, '.md');
+        const body = await readFile(path.join(TEMPLATES_ROOT, 'protocols', protocolFile), 'utf8');
+        for (const tool of Object.values(TOOLS)) {
+            const dest = path.join(cwd, tool.destPath(slug));
+            const existed = existsSync(dest);
+            await mkdir(path.dirname(dest), { recursive: true });
+            await writeFile(dest, tool.render(slug, body), 'utf8');
+            log_line(`  · ${existed ? 'overwrote' : 'installed'} ${tool.destPath(slug)} (${tool.label})`);
+        }
     }
     // Step 4: CLAUDE.md
     const claudeMdPath = path.join(cwd, 'CLAUDE.md');
@@ -159,26 +208,26 @@ export async function cmdInstallProtocols(prompt, options = {}) {
             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);
+    for (const protocolFile of PROTOCOL_FILES) {
+        const slug = path.basename(protocolFile, '.md');
+        const body = await readFile(path.join(TEMPLATES_ROOT, 'protocols', protocolFile), 'utf8');
+        for (const tool of Object.values(TOOLS)) {
+            const dest = path.join(cwd, tool.destPath(slug));
+            const rendered = tool.render(slug, body);
+            let action = 'created';
+            if (existsSync(dest)) {
+                const destContent = await readFile(dest, 'utf8');
+                action = destContent === rendered ? 'unchanged' : 'updated';
+            }
+            if (action !== 'unchanged') {
+                await mkdir(path.dirname(dest), { recursive: true });
+                await writeFile(dest, rendered, 'utf8');
+            }
+            lines.push(`  ${action.padEnd(10)} ${tool.destPath(slug)}`);
         }
-        lines.push(`  ${action.padEnd(10)} .claude/commands/${protocol}`);
     }
-    prompt.print(`Refreshing protocols at ${claudeCommandsDir}:`);
+    prompt.print(`Refreshing protocols (Claude Code / OpenCode / Codex CLI):`);
     for (const l of lines)
         prompt.print(l);
     return { output: '', exitCode: 0 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {