rcf-lite 0.20.0 → 0.22.0

package/src/cli/blueprint.js

@@ -184,6 +184,20 @@ const OPTION_SPEC = {
   // Companion-suggestion mechanism (core-companions spec section 2).
   companion: { type: 'string', multiple: true },
   'no-companion-suggestions': { type: 'boolean' },
+  // Capability-declaration mechanism (visual round T-5 spec 5.5.1,
+  // 5.5.2). --allow-no-auth-yet is the override for the
+  // requiresAppliedCapabilities gate. --answer <id>=<value> is
+  // repeatable; --answers <file> reads a JSON object mapping elicit
+  // ids to values. Both feed the elicitation phase in applyBlueprint.
+  'allow-no-auth-yet': { type: 'boolean' },
+  // Infra round 5 T-2 (spec 5.2, Baz decision 6): object-storage-s3
+  // declares allowSkipFlag "allow-no-secrets-yet" so the override for
+  // its requiresAppliedCapabilities gate stays semantically aligned
+  // with the credential-pair discipline the spec names, rather than
+  // reusing the auth-flavoured flag.
+  'allow-no-secrets-yet': { type: 'boolean' },
+  answer: { type: 'string', multiple: true },
+  answers: { type: 'string' },
 };
 
 /**
@@ -286,9 +300,55 @@ export async function main(argv, deps = {}) {
         }
       }
     }
+    // Capability-declaration mechanism (visual round T-5). Compose
+    // the operator-supplied elicit answers bag from --answers <file>
+    // (JSON object) and --answer <id>=<value> (repeatable). Later
+    // --answer entries override --answers file entries so a shell
+    // one-liner beats a stored default without editing the file.
+    let elicitAnswers = {};
+    if (typeof parsed.values.answers === 'string' && parsed.values.answers.length > 0) {
+      try {
+        const raw = await (await import('node:fs/promises')).readFile(parsed.values.answers, 'utf8');
+        const parsedBag = JSON.parse(raw);
+        if (typeof parsedBag !== 'object' || parsedBag === null || Array.isArray(parsedBag)) {
+          stderr.write(`[error] blueprint add: --answers file must contain a JSON object of id -> value.\n`);
+          return 2;
+        }
+        elicitAnswers = { ...parsedBag };
+      } catch (err) {
+        stderr.write(`[error] blueprint add: --answers file read failed: ${err.message}\n`);
+        return 2;
+      }
+    }
+    if (Array.isArray(parsed.values.answer)) {
+      for (const entry of parsed.values.answer) {
+        const eq = entry.indexOf('=');
+        if (eq < 1) {
+          stderr.write(`[error] blueprint add: --answer expects <id>=<value>; got '${entry}'.\n`);
+          return 2;
+        }
+        elicitAnswers[entry.slice(0, eq)] = entry.slice(eq + 1);
+      }
+    }
+    // Custom-auth capability elicits (visual round T-5 spec 5.5
+    // "Risks"): providesCapability elicits fire pre-refusal. On a
+    // TTY, prompt the operator for any unanswered custom-auth elicits
+    // through readline so a fresh project with no shelf auth can pass
+    // the requiresAppliedCapabilities gate by declaring what its own
+    // auth provides. Non-interactive runs skip the prompt and read
+    // answers from the bag only.
+    const stdin = deps.stdin ?? process.stdin;
+    const isTty = Boolean(stdin && stdin.isTTY);
+    const customAuthReadLine = isTty
+      ? await createCustomAuthReadLine({ stdin, stdout })
+      : null;
     const result = await applyBlueprint({
       projectRoot, tree, source,
       namespaceOverride: parsed.values.namespace,
+      allowNoAuthYet: parsed.values['allow-no-auth-yet'] === true
+        || parsed.values['allow-no-secrets-yet'] === true,
+      elicitAnswers,
+      customAuthReadLine,
       // 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
@@ -321,6 +381,19 @@ export async function main(argv, deps = {}) {
       }
     }
     if (isRcfError(result)) {
+      // Capability-declaration refusal (visual round T-5 spec 5.5.1)
+      // is exit 3, and the message is spec-verbatim (built by
+      // buildRefusalMessage in blueprint/capabilities.js): print it
+      // as-is on stderr, no [error] prefix. Every other rcfError
+      // stays exit 2 with the [error] prefix.
+      if (result.kind === 'requiresAppliedCapabilities') {
+        if (parsed.values.json) {
+          stderr.write(`${JSON.stringify({ refused: true, error: { kind: result.kind, message: result.message } })}\n`);
+        } else {
+          stderr.write(`${result.message}\n`);
+        }
+        return 3;
+      }
       if (parsed.values.json) {
         stderr.write(`${JSON.stringify({ refused: true, error: { kind: result.kind, message: result.message } })}\n`);
       } else {
@@ -759,3 +832,29 @@ function parseResolveOptions(rawList, reason) {
   }
   return { value: out };
 }
+
+/**
+ * Build a readline-backed prompt function for custom-auth capability
+ * elicits (visual round T-5 spec 5.5 "Risks"). Wraps node:readline in
+ * a promise so `runCustomAuthCapabilityElicits` can `await` each line.
+ * Only used when stdin is a TTY; the callback closes the interface on
+ * first shutdown to avoid leaking file descriptors.
+ *
+ * @param {{ stdin: NodeJS.ReadableStream, stdout: NodeJS.WritableStream }} deps
+ * @returns {Promise<(prompt: string) => Promise<string>>}
+ */
+async function createCustomAuthReadLine({ stdin, stdout }) {
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: stdin, output: stdout, terminal: true });
+  let closed = false;
+  return (prompt) => new Promise((resolve) => {
+    if (closed) return resolve('');
+    rl.question(prompt, (answer) => {
+      if (!closed) {
+        try { rl.close(); } catch { /* fine */ }
+        closed = true;
+      }
+      resolve(answer);
+    });
+  });
+}

package/src/cli/browser-verify.js

@@ -18,13 +18,18 @@
 
 import { parseArgs } from 'node:util';
 import process from 'node:process';
+import { isAbsolute, resolve } from 'node:path';
 
 import { walkTree } from '#core/store';
 import { writeUnexpectedFailure, rcfError } from '#core/errors';
 
 import { findProjectRoot } from '../view/index.js';
 import {
+  bootIfNeeded,
   composeOperatorSessionRecord,
+  createPackBrowser,
+  loadProbePacks,
+  pickBootFromPacks,
   runAgentScreenshotCritique,
   stubBrowserDriver,
   writeBrowserVerificationAck,
@@ -40,6 +45,9 @@ const OPTION_SPEC = {
   quiet: { type: 'boolean' },
   ack: { type: 'boolean' },
   notes: { type: 'string' },
+  'probe-pack': { type: 'string' },
+  'no-boot': { type: 'boolean' },
+  'no-browser': { type: 'boolean' },
   help: { type: 'boolean' },
 };
 
@@ -61,6 +69,22 @@ Options:
   --quiet                   Suppress non-error confirmations.
   --ack                     Mark operatorAckAt on the latest record for
                             this FBS (used to clear a warn verdict).
+  --probe-pack <name>       Restrict this run to one blueprint-shipped
+                            probe pack by packName. When omitted, every
+                            discovered pack whose appliesTo() matches
+                            this FBS runs. Refuses (exit 2) when the
+                            name resolves to no discovered pack.
+  --no-browser              Skip the real headless browser (probe packs
+                            that call browser.* will see browser=null).
+                            Default: provision a headless browser via
+                            the pinned Playwright MCP so packs can drive
+                            real DOM interactions.
+  --no-boot                 Do not run a pack's declared bootCommand
+                            when the runtime URL is unreachable. Default:
+                            when any pack declares a boot block and the
+                            runtime is not answering, spawn bootCommand
+                            from the project root, wait for waitForUrl
+                            then waitForSelector, then run packs.
   --help                    Print this help.
 
 Exit codes:
@@ -163,13 +187,77 @@ export async function main(argv, deps = {}) {
         stderr.write('[error] usage browser-verify: no fetch available in the runtime; supply deps.fetch\n');
         return 2;
       }
-      record = await runAgentScreenshotCritique({
-        tree, fbs, runtimeUrl, runtimeProfile: profile,
-        browserDriver, fetch: fetchFn,
-        artefactDir: `.rcf/artefacts/${fbsId.toLowerCase()}`,
-        critiqueNotes: flags.notes,
-        now,
-      });
+      // Probe-pack discovery: gather packs from every applied blueprint
+      // on the manifest, then apply --probe-pack filter if any.
+      const appliedBlueprints = readAppliedBlueprints({ manifest: tree.manifest, projectRoot });
+      const { packs, errors: packErrors } = await loadProbePacks({ appliedBlueprints, projectRoot });
+      if (packErrors.length > 0) {
+        for (const e of packErrors) stderr.write(`[error] usage browser-verify: probe-pack loader refused ${e.packAbsPath}: ${e.message}\n`);
+        return 2;
+      }
+      const packNameFilter = typeof flags['probe-pack'] === 'string' && flags['probe-pack'].length > 0
+        ? flags['probe-pack']
+        : undefined;
+      if (packNameFilter && !packs.some((p) => p.packName === packNameFilter)) {
+        const discovered = packs.map((p) => p.packName).sort();
+        stderr.write(`[error] usage browser-verify: --probe-pack '${packNameFilter}' resolves to no discovered pack. Discovered packs: ${discovered.length === 0 ? '(none)' : discovered.join(', ')}.\n`);
+        return 2;
+      }
+
+      const filteredPacks = packNameFilter
+        ? packs.filter((p) => p.packName === packNameFilter)
+        : packs;
+      const provisionBrowser = deps.createPackBrowser ?? createPackBrowser;
+      const bootProbe = deps.bootIfNeeded ?? bootIfNeeded;
+
+      let packBrowser = deps.packBrowser ?? null;
+      const cleanups = [];
+      try {
+        if (packBrowser === null && filteredPacks.length > 0 && !flags['no-browser']) {
+          packBrowser = await provisionBrowser({
+            projectRoot,
+            logger: (line) => { if (!flags.quiet) stderr.write(`${line}\n`); },
+          });
+          cleanups.push(async () => { try { await packBrowser.close(); } catch { /* fine */ } });
+        }
+
+        if (!flags['no-boot'] && filteredPacks.length > 0) {
+          const boot = pickBootFromPacks(filteredPacks);
+          if (boot) {
+            const bootOutcome = await bootProbe({
+              boot,
+              runtimeUrl,
+              projectRoot,
+              fetch: fetchFn,
+              browser: packBrowser,
+              logger: (line) => { if (!flags.quiet) stderr.write(`${line}\n`); },
+            });
+            for (const n of bootOutcome.notes) if (!flags.quiet) stderr.write(`[boot] ${n}\n`);
+            if (bootOutcome.started) {
+              cleanups.push(async () => { try { await bootOutcome.stop(); } catch { /* fine */ } });
+            }
+          }
+        }
+
+        record = await runAgentScreenshotCritique({
+          tree, fbs, runtimeUrl, runtimeProfile: profile,
+          browserDriver, fetch: fetchFn,
+          artefactDir: `.rcf/artefacts/${fbsId.toLowerCase()}`,
+          critiqueNotes: flags.notes,
+          probePacks: packs,
+          packBrowser,
+          packNameFilter,
+          projectRoot,
+          now,
+        });
+      } finally {
+        // LIFO cleanup: close browser before stopping the server so a
+        // page.close talking to a killed server never hangs the CLI.
+        while (cleanups.length > 0) {
+          const step = cleanups.pop();
+          try { await step(); } catch { /* fine */ }
+        }
+      }
     }
   } catch (err) {
     writeUnexpectedFailure(
@@ -203,6 +291,41 @@ export async function main(argv, deps = {}) {
   return record.verdict === 'pass' ? 0 : 4;
 }
 
+/**
+ * Read applied blueprints off the manifest as an array of
+ * `{ slug, absPath }` suitable for `loadProbePacks`.
+ *
+ * The applied-blueprint record carries a `source` field (see
+ * `src/blueprint/apply.js`). For a shelf apply the source is the
+ * shelf-relative slug; for a local-path apply it is an absolute
+ * path; for a library apply it is `<library>:<slug>`. We resolve
+ * to the shelf path shipped alongside the CLI package or, in the
+ * monorepo, the repo-root shelf. Missing directories are skipped
+ * without error (the CLI later checks discovered vs. requested).
+ */
+function readAppliedBlueprints({ manifest, projectRoot }) {
+  const list = Array.isArray(manifest?.blueprints) ? manifest.blueprints : [];
+  const out = [];
+  for (const entry of list) {
+    if (!entry || typeof entry.slug !== 'string' || entry.slug.length === 0) continue;
+    const absPath = resolveBlueprintAbsPath({ entry, projectRoot });
+    if (absPath) out.push({ slug: entry.slug, absPath });
+  }
+  return out;
+}
+
+function resolveBlueprintAbsPath({ entry, projectRoot }) {
+  const { slug, source } = entry;
+  if (typeof source === 'string' && source.length > 0) {
+    if (isAbsolute(source)) return source;
+    if (source.startsWith('./') || source.startsWith('../')) {
+      return resolve(projectRoot, source);
+    }
+  }
+  const cwd = resolve(projectRoot, 'blueprints', slug);
+  return cwd;
+}
+
 function defaultUrlForProfile(profile) {
   if (profile === 'ci') return 'http://127.0.0.1:3000';
   if (profile === 'deployed') return '';
@@ -227,5 +350,22 @@ function renderSummary({ stdout, record }) {
       stdout.write(`    [${c.verdict}] ${c.check} (status=${c.status ?? 'n/a'})${detail}\n`);
     }
   }
+  if (Array.isArray(record.probePacks) && record.probePacks.length > 0) {
+    stdout.write('  probe packs:\n');
+    for (const p of record.probePacks) {
+      if (p.applicable === false) {
+        stdout.write(`    [skip] ${p.packName} (${p.blueprintSlug}): ${p.detail ?? 'not applicable to this FBS'}\n`);
+        continue;
+      }
+      for (const pc of p.preChecks ?? []) {
+        const detail = pc.detail ? ` - ${pc.detail}` : '';
+        stdout.write(`    [${pc.verdict}] ${p.packName} pre-check ${pc.id}${detail}\n`);
+      }
+      for (const c of p.checks ?? []) {
+        const detail = c.detail ? ` - ${c.detail}` : '';
+        stdout.write(`    [${c.verdict}] ${p.packName} ${c.id}${detail}\n`);
+      }
+    }
+  }
   stdout.write(`  verdict: ${record.verdict}\n\n`);
 }

package/src/core/errors/index.js

@@ -42,6 +42,13 @@ const VALID_KINDS = new Set([
   // individually schema-clean) and from `brokenReference` (nothing
   // dangles; the graph is over-connected, not under-connected).
   'duplicateId',
+  // Visual round T-5 (spec section 5.5.1): a consumer blueprint whose
+  // requiresAppliedCapabilities gate refuses because no applied
+  // blueprint declares any of the required capabilities AND the CLI
+  // did not pass the allow-skip flag. The apply verb returns this kind
+  // with the spec-verbatim refusal message; the CLI translates it to
+  // exit 3 (not exit 2) with the message printed as-is on stderr.
+  'requiresAppliedCapabilities',
 ]);
 
 /**