rcf-lite 0.13.0 → 0.14.0

package/src/cli/blueprint.js

@@ -25,6 +25,7 @@ import {
   supersedeBlueprintTopic,
 } from '../blueprint/index.js';
 import { conflictReportJson, renderConflictReport } from '../blueprint/conflicts.js';
+import { handleLibraryVerb, LIBRARY_HELP } from './blueprint-library.js';
 
 export const HELP = `Usage: rcf define blueprint <verb> [options]
 
@@ -65,6 +66,11 @@ Verbs:
   diff <topic>           Side-by-side view of every applied blueprint's
                          scope:global ADR on <topic>: id, path, title,
                          status, decision. Read-only.
+  library <verb>         Manage external blueprint libraries. Sub-verbs:
+                         add, list, remove, refresh. See
+                         'rcf define blueprint library --help' for the
+                         full surface. Phase 2b covers local sources;
+                         network fetchers land in Phase 2c.
 
 Options:
   --namespace <slug>     Override the blueprint's default namespace
@@ -106,6 +112,11 @@ const OPTION_SPEC = {
   resolve: { type: 'string', multiple: true },
   reason: { type: 'string' },
   incoming: { type: 'string' },
+  // library-verb flags (parsed centrally so strict:true doesn't refuse
+  // them when the operator types `rcf define blueprint library add`).
+  prefix: { type: 'string' },
+  'i-have-reviewed': { type: 'boolean' },
+  'no-review': { type: 'boolean' },
   json: { type: 'boolean' },
   'dry-run': { type: 'boolean' },
   quiet: { type: 'boolean' },
@@ -131,13 +142,25 @@ export async function main(argv, deps = {}) {
     stderr.write(HELP);
     return 2;
   }
-  if (parsed.values.help || parsed.positionals.length === 0) {
+  const firstPositional = parsed.positionals[0];
+  // `rcf define blueprint library --help` routes into the library
+  // handler so the sub-verb HELP block is what the operator sees.
+  // Every other --help (and empty argv) prints the top-level HELP.
+  if (firstPositional !== 'library' && (parsed.values.help || parsed.positionals.length === 0)) {
     stdout.write(HELP);
     return 0;
   }
   const verb = parsed.positionals[0];
   const rest = parsed.positionals.slice(1);
 
+  // `library` sub-verbs manage the external-library registry; they
+  // never walk the RCF tree, and delegating early keeps the option
+  // parser from consuming `--i-have-reviewed` (a library-add-only flag)
+  // against a `library` add invocation.
+  if (verb === 'library') {
+    return handleLibraryVerb(parsed, rest, { stdout, stderr, cwd, now, stdin: deps.stdin });
+  }
+
   const projectRoot = await findProjectRoot(cwd);
   if (!projectRoot) {
     stderr.write('[error] no rcf/ tree found in this directory or any ancestor.\n');
@@ -156,7 +179,7 @@ export async function main(argv, deps = {}) {
       return 2;
     }
     const rawSource = rest[0];
-    const resolved = await resolveBlueprintSource(rawSource);
+    const resolved = await resolveBlueprintSource(rawSource, { projectRoot });
     if (isRcfError(resolved)) {
       if (parsed.values.json) {
         stderr.write(`${JSON.stringify({ refused: true, error: { kind: resolved.kind, message: resolved.message } })}\n`);
@@ -165,12 +188,17 @@ export async function main(argv, deps = {}) {
       }
       return 2;
     }
-    // Feed the resolved absolute path to the applier; keep the original
-    // typed source on the CLI for the supersede hint the conflict
-    // renderer prints, so the operator sees exactly the string they can
-    // copy back into a fresh shell.
+    // Feed the resolved absolute path to the applier. The original
+    // typed source is preserved on the CLI for the conflict renderer's
+    // supersede hint (so the operator sees exactly the string they can
+    // copy back into a fresh shell). It is ONLY forwarded to the applier
+    // as `displaySource` for library-qualified resolves - spec §5.3
+    // requires the qualified typed ref (`wsd:auth-oauth2`) to be the
+    // record's `source`. For shelf and path resolves the record must
+    // carry the RESOLVED ABSOLUTE PATH, which is the pre-#120 behaviour
+    // that /scope.json and `blueprint list --category` both depend on
+    // to load the shipping source file (integration review d-2026-08-31-046).
     const source = resolved.resolved;
-    const displaySource = resolved.original;
     const resolveDeclarations = parseResolveOptions(parsed.values.resolve, parsed.values.reason);
     if (resolveDeclarations.error) {
       stderr.write(`[error] blueprint add: ${resolveDeclarations.error}\n`);
@@ -178,8 +206,17 @@ export async function main(argv, deps = {}) {
     }
     const result = await applyBlueprint({
       projectRoot, tree, source,
-      displaySource,
       namespaceOverride: parsed.values.namespace,
+      // Library-qualified resolves rewire the applied identity under
+      // the library prefix and forward the library's declared bands
+      // for the apply-time gate (spec §5.3, §8.3). The qualified typed
+      // ref is passed as `displaySource` so the applied record's
+      // `source` field carries it verbatim (spec §5.3).
+      ...(resolved.kind === 'library' ? {
+        displaySource: resolved.original,
+        effectiveSlug: resolved.effectiveSlug,
+        libraryBands: resolved.libraryBands,
+      } : {}),
       resolveDeclarations: resolveDeclarations.value,
       now,
       dryRun: parsed.values['dry-run'] === true,
@@ -246,7 +283,7 @@ export async function main(argv, deps = {}) {
     // source's blueprint.json at list time; a source that no longer
     // resolves surfaces under the `uncategorised` group rather than
     // being dropped.
-    const enriched = await enrichRowsWithCategories(rows);
+    const enriched = await enrichRowsWithCategories(rows, { projectRoot });
     const groups = groupRowsByCategory(enriched);
     let first = true;
     for (const group of groups) {

package/src/cli/guidance.js

@@ -34,7 +34,7 @@ const OPTION_SPEC = {
 
 export const HELP = `Usage: rcf guidance [topic] [options]
 
-Print a guidance-pack document from the installed rcf-build-lite
+Print a guidance-pack document from the installed rcf-lite
 package to stdout. The pack ships with the package and is never copied
 into your project, so this verb is how a CLI-only agent reads the
 method. MCP-wired harnesses can use the rcf://docs/<slug> resources and

package/src/cli/help.js

@@ -36,6 +36,7 @@ import { HELP as DESIGN_HELP } from './design.js';
 import { HELP as BROWSER_VERIFY_HELP } from './browser-verify.js';
 import { HELP as UPDATE_HELP } from './update.js';
 import { HELP as VALIDATE_HELP } from './validate.js';
+import { HELP as VERSION_HELP } from './version.js';
 import { HELP as VIEW_HELP } from './view.js';
 import { HELP as REQ_CLASSIFY_HELP } from './req-classify.js';
 import { HELP as REQ_BASELINE_HELP } from './req-baseline.js';
@@ -64,6 +65,8 @@ core         Platform plumbing that predates any RCF stage.
   doctor                   Diagnose and repair init-hygiene drift.
   guidance [topic]         Print a method document from the installed pack.
   mcp                      Serve the project over MCP (local stdio).
+  version [--check]        Print installed version; --check compares
+                           against the release feed.
   help [group] [verb]      Print help for a group or a verb.
 
 discover     Learn what is already true for this project.
@@ -126,6 +129,24 @@ Run 'rcf help <group>' for group help; 'rcf help <group> <verb>' for
 per-verb help.
 `;
 
+const CORE_GROUP_HELP = `Usage: rcf <core-verb> [options]
+
+Platform plumbing that predates any RCF stage. Core verbs dispatch at
+the top level (they are invoked as \`rcf <verb>\`, not \`rcf core <verb>\`);
+this group is a documentation grouping for \`rcf help\`.
+
+Verbs:
+  init                     Scaffold a new RCF project in this directory.
+  doctor                   Diagnose and repair init-hygiene drift.
+  guidance [topic]         Print a method document from the installed pack.
+  mcp                      Serve the project over MCP (local stdio).
+  version [--check]        Print installed version; --check compares
+                           against the release feed.
+  help [group] [verb]      Print help for a group or a verb.
+
+Run 'rcf help <verb>' for per-verb help.
+`;
+
 const DISCOVER_HELP = `Usage: rcf discover <verb> [options]
 
 Learn what is already true for this project: classify supplied
@@ -223,6 +244,7 @@ Run 'rcf help audit <verb>' for per-verb help.
 `;
 
 export const GROUP_HELP = {
+  core: CORE_GROUP_HELP,
   discover: DISCOVER_HELP,
   define: DEFINE_HELP,
   build: BUILD_GROUP_HELP,
@@ -286,6 +308,7 @@ export const CORE_HELP = {
   doctor: DOCTOR_HELP,
   guidance: GUIDANCE_HELP,
   mcp: MCP_HELP,
+  version: VERSION_HELP,
 };
 
 /**
@@ -319,7 +342,10 @@ export async function main(argv, deps = {}) {
       stdout.write(GROUP_HELP[first]);
       return 0;
     }
-    const body = HELP_MAP[first][verb];
+    // `core` is a documentation grouping - core verbs dispatch at the
+    // top level, so `rcf help core <verb>` delegates to the same
+    // per-verb block that `rcf help <verb>` prints.
+    const body = first === 'core' ? CORE_HELP[verb] : HELP_MAP[first][verb];
     if (!body) {
       stderr.write(`[error] usage no help topic '${first} ${verb}'\n`);
       stdout.write(GROUP_HELP[first]);