rcf-lite 0.13.0 → 0.15.0

package/src/blueprint/apply.js

@@ -15,6 +15,7 @@ import { readFile } from 'node:fs/promises';
 import { rcfError } from '../core/errors/index.js';
 import { subdirFor } from '#core/store';
 import { detectCrossBlueprintClaims, detectGlobalAdrConflicts } from './conflicts.js';
+import { detectContributionsOutOfBand } from './library-registry.js';
 import { loadBlueprint } from './loader.js';
 import { updateManifest } from './manifest-writer.js';
 import { stampId } from './namespace.js';
@@ -40,6 +41,26 @@ import { nextResolutionId } from './resolutions.js';
  *        string the operator can copy back. Defaults to `source` when omitted (so
  *        existing callers keep today's byte-for-byte behaviour).
  * @param {string} [args.namespaceOverride] - non-default namespace slug
+ * @param {string} [args.effectiveSlug] - override for the blueprint's own slug
+ *        when applied through an external-library qualified reference (spec §5.3):
+ *        `<libraryPrefix>-<blueprintSlug>`. When set, this becomes BOTH the
+ *        stamping namespace (so contributions inherit the library prefix) AND
+ *        the value written into `manifest.blueprints[].slug` on the applied
+ *        record, so `rcf define blueprint remove wsd-auth-oauth2` reads back
+ *        cleanly. `namespaceOverride` still wins over `effectiveSlug` if both
+ *        are set (operator explicitly chose a different namespace).
+ * @param {string} [args.libraryPrefix] - the registered library prefix the
+ *        blueprint was resolved through (spec §5.3, §7.3). When set the applied
+ *        record carries a `libraryPrefix` field so `rcf library remove`'s
+ *        ownership check reads the ownership fact off the record itself
+ *        rather than string-matching `source`. Absent for shelf and path
+ *        applies. Requires @stravica-ai/rcf-schemas 0.5.1 or later
+ *        (`appliedBlueprintRecord.libraryPrefix`, additive optional).
+ * @param {{ ac: { start: number, end: number }, suffixBlocks?: Array<{ kind: string, start: number, end: number }> }} [args.libraryBands]
+ *        Declared bands from the resolved library. When set, every stamped
+ *        contribution is band-gated before write; a contribution whose numeric
+ *        portion falls outside the library's bands refuses at apply-time (spec
+ *        §8.3, open question 9.9 ratified as "add both").
  * @param {Array<{ topic: string, resolvedByAdrId: string }>} [args.resolveDeclarations]
  *        Operator-supplied conflict resolutions declared on the add
  *        itself. One entry per resolved topic. For each, the resolution
@@ -58,25 +79,38 @@ import { nextResolutionId } from './resolutions.js';
  *        prove the rollback runs. Never used in production.
  * @returns {Promise<ApplyResult | import('../core/errors/index.js').RcfError>}
  */
-export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, resolveDeclarations, now = new Date(), dryRun = false, _copyFileForTest }) {
+export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, effectiveSlug, libraryPrefix, libraryBands, resolveDeclarations, now = new Date(), dryRun = false, _copyFileForTest }) {
   const hintSource = typeof displaySource === 'string' && displaySource.length > 0 ? displaySource : source;
   const blueprint = await loadBlueprint(source);
   if (blueprint.kind) return blueprint; // RcfError
-  const namespace = namespaceOverride ?? blueprint.slug;
+  // Effective slug rewires the blueprint's identity under a library
+  // prefix (spec §5.3). It becomes both the stamping namespace and the
+  // slug written into `manifest.blueprints[].slug`. `namespaceOverride`
+  // still wins over `effectiveSlug` (operator's explicit --namespace on
+  // the CLI). When neither is set the blueprint's own slug applies.
+  const appliedSlug = typeof effectiveSlug === 'string' && effectiveSlug.length > 0
+    ? effectiveSlug
+    : blueprint.slug;
+  const namespace = namespaceOverride ?? appliedSlug;
 
   const applied = tree.manifest?.blueprints ?? [];
-  const existing = applied.find((b) => b.slug === blueprint.slug);
+  const existing = applied.find((b) => b.slug === appliedSlug);
   const stamped = stampContributions(blueprint.contributions, namespace);
   if (stamped.error) {
     return rcfError({ kind: 'validation', message: stamped.error });
   }
+  // Apply-time band gate for external-library blueprints.
+  if (libraryBands) {
+    const bandErr = detectContributionsOutOfBand(stamped.contributions, libraryBands);
+    if (bandErr) return bandErr;
+  }
 
   // Pre-detection: fold operator-supplied --resolve declarations into a
   // WORKING COPY of the manifest so the detector honours them on this
   // run. The final manifest write later composes the same resolution
   // records into the persisted manifest, so the in-memory copy and the
   // on-disk write agree.
-  const incomingForConflicts = { slug: blueprint.slug, contributions: stamped.contributions };
+  const incomingForConflicts = { slug: appliedSlug, contributions: stamped.contributions };
   const declResult = composeDeclaredResolutions({
     manifest: tree.manifest,
     applied,
@@ -109,7 +143,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     ...detectCrossBlueprintClaims(applied, incomingForConflicts),
   ];
   if (conflicts.length > 0) {
-    return { applied: false, slug: blueprint.slug, version: blueprint.version, contributions: [], conflicts };
+    return { applied: false, slug: appliedSlug, version: blueprint.version, contributions: [], conflicts };
   }
 
   // Ownership set for the overwrite guard below. On a re-apply, the
@@ -122,7 +156,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
   if (existing && existing.version === blueprint.version) {
     return {
       applied: false, alreadyApplied: true,
-      slug: blueprint.slug, version: blueprint.version,
+      slug: appliedSlug, version: blueprint.version,
       contributions: stamped.contributions,
       ...(duplicateResolveTopics.length > 0 ? { warnings: [{ kind: 'duplicateResolveTopic', topics: duplicateResolveTopics }] } : {}),
     };
@@ -151,7 +185,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
       writtenContributions.push(preserveScope({ id: c.id, kind: c.kind, path: relDest }, c));
     }
   } else {
-    const tmpSuffix = `.rcf-tmp-${blueprint.slug}-${now.getTime()}`;
+    const tmpSuffix = `.rcf-tmp-${appliedSlug}-${now.getTime()}`;
     const stagedWrites = []; // { tmpAbs, absDest, relDest, id, kind, c }
     const rollback = async (err) => {
       for (const w of stagedWrites) {
@@ -184,7 +218,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
           for (const w of stagedWrites) await unlink(w.tmpAbs).catch(() => {});
           return rcfError({
             kind: 'duplicateId',
-            message: `blueprint apply: contribution ${c.id} would overwrite an existing file at ${relDest} that is not recorded as owned by blueprint '${blueprint.slug}'.`,
+            message: `blueprint apply: contribution ${c.id} would overwrite an existing file at ${relDest} that is not recorded as owned by blueprint '${appliedSlug}'.`,
             filePath: relDest,
           });
         }
@@ -225,13 +259,26 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     }
   }
 
-  // Update manifest.blueprints[].
+  // Update manifest.blueprints[]. The applied record's `source` field
+  // carries the qualified typed ref for library-resolved blueprints
+  // (`wsd:auth-oauth2`) so `rcf define blueprint upgrade` reads back
+  // cleanly (spec §5.3); local-path applies carry the absolute path as
+  // today. When the apply resolved through a registered external
+  // library the record additionally carries `libraryPrefix`: the
+  // ownership fact for the library-registered ownership check in
+  // `rcf library remove`, so the registry may be edited (renamed,
+  // re-pointed, unregistered) without orphaning previously applied
+  // records. Shelf and path applies carry no `libraryPrefix`.
+  const recordSource = typeof displaySource === 'string' && displaySource.length > 0 && displaySource !== source
+    ? displaySource
+    : source;
   const nextEntry = {
-    slug: blueprint.slug,
+    slug: appliedSlug,
     version: blueprint.version,
     appliedAt: now.toISOString(),
-    source,
+    source: recordSource,
     ...(namespaceOverride ? { namespace: namespaceOverride } : {}),
+    ...(typeof libraryPrefix === 'string' && libraryPrefix.length > 0 ? { libraryPrefix } : {}),
     ...(writtenContributions.length > 0 ? { contributions: writtenContributions } : {}),
   };
   const manifestResult = await updateManifest({
@@ -239,7 +286,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     manifest: tree.manifest,
     mutate: (next) => {
       const list = Array.isArray(next.blueprints) ? next.blueprints : [];
-      const filtered = list.filter((b) => b.slug !== blueprint.slug);
+      const filtered = list.filter((b) => b.slug !== appliedSlug);
       filtered.push(nextEntry);
       next.blueprints = filtered;
       // Fold any --resolve declarations recorded on this add into the
@@ -257,7 +304,7 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
 
   return {
     applied: true,
-    slug: blueprint.slug,
+    slug: appliedSlug,
     version: blueprint.version,
     contributions: writtenContributions,
     ...(duplicateResolveTopics.length > 0 ? { warnings: [{ kind: 'duplicateResolveTopic', topics: duplicateResolveTopics }] } : {}),

package/src/blueprint/index.js

@@ -11,3 +11,15 @@ export { nextResolutionId, matchingResolution } from './resolutions.js';
 export { supersedeBlueprintTopic } from './supersede.js';
 export { diffBlueprintTopic, renderDiff } from './diff.js';
 export { resolveBlueprintSource, knownShelfSlugs, packagedShelfPath } from './shelf-resolver.js';
+export { loadLibrary } from './library-loader.js';
+export {
+  REGISTRY_PATH,
+  REGISTRY_VERSION,
+  readLibraryRegistry,
+  writeLibraryRegistry,
+  findLibrary,
+  loadCoreBandReservations,
+  detectBandOverlap,
+  detectContributionsOutOfBand,
+  detectPrefixCollision,
+} from './library-registry.js';

package/src/blueprint/library-loader.js

@@ -0,0 +1,292 @@
+// External-library manifest loader. Reads and validates `library.json` at
+// a library root, then walks the declared blueprints[] entries to confirm
+// each names a directory whose own `blueprint.json` validates against the
+// phase-1 blueprint loader.
+//
+// See external-blueprint-libraries-spec-2026-08-31.md sections 3 and 3.1
+// for the manifest shape and field contract.
+//
+// Phase 2b covers local-path libraries (a directory the operator already
+// has on disk). Network fetchers (git, tarball) are a Phase 2c concern
+// and are NOT implemented here; the loader is happy to work against any
+// directory that carries a valid `library.json`.
+
+import { readFile, stat } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import { rcfError } from '../core/errors/index.js';
+import { loadBlueprint } from './loader.js';
+
+const KEBAB_SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const KNOWN_SUFFIX_BLOCK_KINDS = new Set(['adr', 'tac']);
+const LIBRARY_VERSION_KNOWN = 1;
+
+/**
+ * @typedef {object} LibraryBandAc
+ * @property {number} start
+ * @property {number} end
+ */
+
+/**
+ * @typedef {object} LibrarySuffixBlock
+ * @property {'adr' | 'tac'} kind
+ * @property {number} start
+ * @property {number} end
+ */
+
+/**
+ * @typedef {object} LibraryBands
+ * @property {LibraryBandAc} ac
+ * @property {LibrarySuffixBlock[]} [suffixBlocks]
+ */
+
+/**
+ * @typedef {object} LibraryBlueprintEntry
+ * @property {string} slug
+ * @property {string} path
+ * @property {string[]} [globalTopics]  scope:global ADR topics this
+ *   blueprint contributes. Populated only when the loader ran with
+ *   `validateBlueprints: true` (the review-on-add path); resolver-time
+ *   loads that skip per-blueprint validation leave the field absent.
+ *   Callers use it to render the section 8.1 "Global topics these
+ *   blueprints claim" line during library-add review.
+ */
+
+/**
+ * @typedef {object} LibraryPublisher
+ * @property {string} id
+ * @property {string} displayName
+ * @property {string} [contact]
+ */
+
+/**
+ * @typedef {object} LoadedLibrary
+ * @property {number} libraryVersion
+ * @property {string} libraryPrefix
+ * @property {string} displayName
+ * @property {LibraryPublisher} publisher
+ * @property {string} libraryRef
+ * @property {LibraryBands} bands
+ * @property {LibraryBlueprintEntry[]} blueprints
+ * @property {string} [notes]
+ * @property {string} root              absolute path to the library root
+ */
+
+/**
+ * Load and validate a library from a directory that carries a
+ * `library.json` at its root plus a `blueprints/` subtree.
+ *
+ * @param {string} libraryRoot - absolute or relative path
+ * @param {object} [opts]
+ * @param {boolean} [opts.validateBlueprints=true] - when false, skips the
+ *   per-blueprint validation walk. Add-time review-on-add sets this to
+ *   true so the operator sees a real refusal on a broken shelf; a
+ *   registry read at resolver-time can set false to keep the hot path
+ *   cheap.
+ * @returns {Promise<LoadedLibrary | import('../core/errors/index.js').RcfError>}
+ */
+export async function loadLibrary(libraryRoot, opts = {}) {
+  const root = resolve(libraryRoot);
+  const metaPath = join(root, 'library.json');
+  try {
+    await stat(metaPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return rcfError({
+        kind: 'usage',
+        message: `library: no library.json found at ${metaPath}`,
+        filePath: metaPath,
+      });
+    }
+    return rcfError({ kind: 'ioFailure', message: `library: ${err.message}`, filePath: metaPath });
+  }
+  let raw;
+  try {
+    raw = await readFile(metaPath, 'utf8');
+  } catch (err) {
+    return rcfError({ kind: 'ioFailure', message: `library: read failed: ${err.message}`, filePath: metaPath });
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch (err) {
+    return rcfError({ kind: 'parseFailure', message: `library: JSON parse failed: ${err.message}`, filePath: metaPath });
+  }
+  const shapeError = validateManifestShape(doc, metaPath);
+  if (shapeError) return shapeError;
+
+  const loaded = {
+    libraryVersion: doc.libraryVersion,
+    libraryPrefix: doc.libraryPrefix,
+    displayName: doc.displayName,
+    publisher: {
+      id: doc.publisher.id,
+      displayName: doc.publisher.displayName,
+      ...(typeof doc.publisher.contact === 'string' ? { contact: doc.publisher.contact } : {}),
+    },
+    libraryRef: doc.libraryRef,
+    bands: normaliseBands(doc.bands),
+    blueprints: doc.blueprints.map((b) => ({ slug: b.slug, path: b.path })),
+    ...(typeof doc.notes === 'string' ? { notes: doc.notes } : {}),
+    root,
+  };
+
+  if (opts.validateBlueprints !== false) {
+    const walkErr = await validateDeclaredBlueprints(loaded);
+    if (walkErr) return walkErr;
+  }
+  return loaded;
+}
+
+function validateManifestShape(doc, metaPath) {
+  if (typeof doc !== 'object' || doc === null) {
+    return rcfError({ kind: 'validation', message: 'library.json must be a JSON object', filePath: metaPath });
+  }
+  if (!Number.isInteger(doc.libraryVersion) || doc.libraryVersion < 1) {
+    return rcfError({ kind: 'validation', message: `library.json: libraryVersion must be a positive integer, got ${JSON.stringify(doc.libraryVersion)}`, filePath: metaPath });
+  }
+  if (doc.libraryVersion > LIBRARY_VERSION_KNOWN) {
+    return rcfError({
+      kind: 'validation',
+      message: `library.json: libraryVersion ${doc.libraryVersion} is newer than this CLI understands (max ${LIBRARY_VERSION_KNOWN}); upgrade rcf-lite.`,
+      filePath: metaPath,
+    });
+  }
+  if (typeof doc.libraryPrefix !== 'string' || !KEBAB_SLUG.test(doc.libraryPrefix)) {
+    return rcfError({ kind: 'validation', message: `library.json: libraryPrefix '${doc.libraryPrefix}' is not a valid kebab slug`, filePath: metaPath });
+  }
+  if (typeof doc.displayName !== 'string' || doc.displayName.length === 0) {
+    return rcfError({ kind: 'validation', message: 'library.json: displayName is required (non-empty string)', filePath: metaPath });
+  }
+  if (typeof doc.publisher !== 'object' || doc.publisher === null) {
+    return rcfError({ kind: 'validation', message: 'library.json: publisher object is required', filePath: metaPath });
+  }
+  if (typeof doc.publisher.id !== 'string' || !KEBAB_SLUG.test(doc.publisher.id)) {
+    return rcfError({ kind: 'validation', message: `library.json: publisher.id '${doc.publisher.id}' is not a valid short slug`, filePath: metaPath });
+  }
+  if (typeof doc.publisher.displayName !== 'string' || doc.publisher.displayName.length === 0) {
+    return rcfError({ kind: 'validation', message: 'library.json: publisher.displayName is required', filePath: metaPath });
+  }
+  if (doc.publisher.contact !== undefined && typeof doc.publisher.contact !== 'string') {
+    return rcfError({ kind: 'validation', message: 'library.json: publisher.contact must be a string when present', filePath: metaPath });
+  }
+  if (typeof doc.libraryRef !== 'string' || doc.libraryRef.length === 0) {
+    return rcfError({ kind: 'validation', message: 'library.json: libraryRef is required (non-empty string)', filePath: metaPath });
+  }
+  const bandsError = validateBands(doc.bands, metaPath);
+  if (bandsError) return bandsError;
+  if (!Array.isArray(doc.blueprints) || doc.blueprints.length === 0) {
+    return rcfError({ kind: 'validation', message: 'library.json: blueprints[] is required and must not be empty', filePath: metaPath });
+  }
+  const seenSlugs = new Set();
+  for (const [i, entry] of doc.blueprints.entries()) {
+    if (typeof entry !== 'object' || entry === null) {
+      return rcfError({ kind: 'validation', message: `library.json: blueprints[${i}] must be an object`, filePath: metaPath });
+    }
+    if (typeof entry.slug !== 'string' || !KEBAB_SLUG.test(entry.slug)) {
+      return rcfError({ kind: 'validation', message: `library.json: blueprints[${i}].slug '${entry.slug}' is not a valid kebab slug`, filePath: metaPath });
+    }
+    if (seenSlugs.has(entry.slug)) {
+      return rcfError({ kind: 'validation', message: `library.json: blueprints[${i}].slug '${entry.slug}' is declared more than once`, filePath: metaPath });
+    }
+    seenSlugs.add(entry.slug);
+    if (typeof entry.path !== 'string' || entry.path.length === 0) {
+      return rcfError({ kind: 'validation', message: `library.json: blueprints[${i}].path is required (non-empty string)`, filePath: metaPath });
+    }
+    if (isAbsolute(entry.path)) {
+      return rcfError({ kind: 'validation', message: `library.json: blueprints[${i}].path '${entry.path}' must be relative to the library root`, filePath: metaPath });
+    }
+    if (entry.path.split(/[\\/]/).some((s) => s === '..')) {
+      return rcfError({ kind: 'validation', message: `library.json: blueprints[${i}].path '${entry.path}' contains a '..' segment (parent-directory traversal is refused)`, filePath: metaPath });
+    }
+  }
+  if (doc.notes !== undefined && typeof doc.notes !== 'string') {
+    return rcfError({ kind: 'validation', message: 'library.json: notes must be a string when present', filePath: metaPath });
+  }
+  return null;
+}
+
+function validateBands(bands, metaPath) {
+  if (typeof bands !== 'object' || bands === null) {
+    return rcfError({ kind: 'validation', message: 'library.json: bands object is required', filePath: metaPath });
+  }
+  if (typeof bands.ac !== 'object' || bands.ac === null) {
+    return rcfError({ kind: 'validation', message: 'library.json: bands.ac object is required with { start, end }', filePath: metaPath });
+  }
+  const err = validateBandRange('bands.ac', bands.ac, metaPath);
+  if (err) return err;
+  if (bands.suffixBlocks !== undefined) {
+    if (!Array.isArray(bands.suffixBlocks)) {
+      return rcfError({ kind: 'validation', message: 'library.json: bands.suffixBlocks must be an array when present', filePath: metaPath });
+    }
+    for (const [i, block] of bands.suffixBlocks.entries()) {
+      if (typeof block !== 'object' || block === null) {
+        return rcfError({ kind: 'validation', message: `library.json: bands.suffixBlocks[${i}] must be an object`, filePath: metaPath });
+      }
+      if (typeof block.kind !== 'string' || !KNOWN_SUFFIX_BLOCK_KINDS.has(block.kind)) {
+        return rcfError({ kind: 'validation', message: `library.json: bands.suffixBlocks[${i}].kind '${block.kind}' must be one of ${[...KNOWN_SUFFIX_BLOCK_KINDS].join(', ')}`, filePath: metaPath });
+      }
+      const subErr = validateBandRange(`bands.suffixBlocks[${i}]`, block, metaPath);
+      if (subErr) return subErr;
+    }
+  }
+  return null;
+}
+
+function validateBandRange(label, range, metaPath) {
+  if (!Number.isInteger(range.start) || !Number.isInteger(range.end)) {
+    return rcfError({ kind: 'validation', message: `library.json: ${label}.start and ${label}.end must be integers`, filePath: metaPath });
+  }
+  if (range.start < 1 || range.end > 99999) {
+    return rcfError({ kind: 'validation', message: `library.json: ${label} out of allowed 1..99999 range (got ${range.start}..${range.end})`, filePath: metaPath });
+  }
+  if (range.start > range.end) {
+    return rcfError({ kind: 'validation', message: `library.json: ${label}.start (${range.start}) must be <= ${label}.end (${range.end})`, filePath: metaPath });
+  }
+  return null;
+}
+
+function normaliseBands(bands) {
+  const out = { ac: { start: bands.ac.start, end: bands.ac.end } };
+  if (Array.isArray(bands.suffixBlocks)) {
+    out.suffixBlocks = bands.suffixBlocks.map((b) => ({ kind: b.kind, start: b.start, end: b.end }));
+  }
+  return out;
+}
+
+async function validateDeclaredBlueprints(library) {
+  for (const entry of library.blueprints) {
+    const bpRoot = join(library.root, entry.path);
+    const loaded = await loadBlueprint(bpRoot);
+    if (loaded.kind) {
+      return rcfError({
+        kind: 'validation',
+        message: `library.json: blueprint '${entry.slug}' at '${entry.path}' failed to load: ${loaded.message}`,
+        filePath: bpRoot,
+      });
+    }
+    if (loaded.slug !== entry.slug) {
+      return rcfError({
+        kind: 'validation',
+        message: `library.json: blueprint '${entry.slug}' at '${entry.path}' declares its own slug '${loaded.slug}' on disk (library manifest and blueprint.json must agree)`,
+        filePath: bpRoot,
+      });
+    }
+    // Attach the scope:global ADR topics this blueprint claims so the
+    // review-on-add printer can render the spec §8.1 "Global topics
+    // these blueprints claim" line without re-walking every blueprint.
+    // Order is contribution-declaration order; duplicates within one
+    // blueprint (an author mistake caught by phase-1 conflict logic)
+    // are de-duplicated here to keep the render terse.
+    const seen = new Set();
+    const topics = [];
+    for (const c of loaded.contributions ?? []) {
+      if (c.scope === 'global' && typeof c.topic === 'string' && !seen.has(c.topic)) {
+        seen.add(c.topic);
+        topics.push(c.topic);
+      }
+    }
+    entry.globalTopics = topics;
+  }
+  return null;
+}