rcf-lite 0.0.1 → 0.7.1

package/src/preflight/design-shapes.js

@@ -0,0 +1,185 @@
+// Design-shape questions catalogue for `rcf preflight`
+// (verification-integrity-cluster-spec ADDENDUM §A).
+//
+// The v1 catalogue carries exactly ONE question — `auth.htmlLoginPage` —
+// per the plan-committed Baz-approved scope. Additional questions land
+// in v2 only on the evidence-gated triggers named in §A.3 (three
+// separate projects that would have benefited, OR a case-study defect
+// the existing surface cannot express). Broadening speculatively
+// re-introduces the elicitation surface bloat this addendum exists to
+// avoid.
+//
+// Two exports:
+// - CATALOGUE_V1: the versioned question set, one entry per question.
+// - selectApplicableQuestions(reqs): given a list of REQs, decide which
+//   questions to pose. Deterministic; the interactive session drives it,
+//   the non-interactive path reads the same catalogue when validating a
+//   pre-filled input file.
+//
+// The catalogue is data, not logic. Downstream consumers own the
+// side-effects (writing designShapeAnswers into the preFlightConfig
+// record; the Track B / Track C+D field composition documented in
+// ADDENDUM §A.2 and §A.5).
+
+import { matchReqShapeSignals } from '#core/patterns/req-shapes';
+
+/**
+ * @typedef {'reqScoped'} DesignShapeQuestionScope
+ */
+
+/**
+ * @typedef {object} DesignShapeAnswerChoice
+ * @property {string} value           the answer id written into designShapeAnswers[]
+ * @property {string} display         operator-facing label
+ * @property {boolean} triggersOptOut whether choosing this writes into baselineAcOptOuts[]
+ * @property {string} [uiBaselineWritePath]  dot path into uiBaseline.defaults when known
+ * @property {boolean|string} [uiBaselineWriteValue] value to write at that path
+ */
+
+/**
+ * @typedef {object} DesignShapeQuestion
+ * @property {string} id              catalogue id (for example, auth.htmlLoginPage)
+ * @property {DesignShapeQuestionScope} scope
+ * @property {(reqDoc: object) => boolean} trigger  returns true when the REQ should be asked this question
+ * @property {string} prompt          canonical prompt text
+ * @property {DesignShapeAnswerChoice[]} choices
+ * @property {number} reasonMinLength minimum reason length when the answer triggers a ledger write; matches Track C+D floor
+ * @property {string} baselineKey     Track C+D baseline key this question backs, for opt-out ledger writes
+ */
+
+/**
+ * True when a REQ carries the `auth` shape. Reads
+ * `req.shapeClassification.shapes[]` when the classifier has run (Track
+ * C+D populates this); falls back to a live `matchReqShapeSignals` pass
+ * over the REQ's title, description and rationale when the field is
+ * absent (Track C+D classifier not yet run on this repo).
+ *
+ * @param {object} reqDoc
+ * @returns {boolean}
+ */
+function reqCarriesAuthShape(reqDoc) {
+  const classified = reqDoc?.shapeClassification?.shapes;
+  if (Array.isArray(classified) && classified.length > 0) {
+    return classified.includes('auth');
+  }
+  const parts = [reqDoc?.title, reqDoc?.description, reqDoc?.rationale]
+    .filter((s) => typeof s === 'string' && s.length > 0);
+  for (const text of parts) {
+    for (const m of matchReqShapeSignals(text)) {
+      if (m.shape === 'auth') return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Deep-freeze helper. Object.freeze is shallow, so a caller could mutate
+ * a nested field even on an outwardly frozen object. Review N-6
+ * (non-blocking): the catalogue is a spec-committed data surface and
+ * must not drift in memory. This helper recurses through plain objects
+ * and arrays, freezing every reachable value, and returns the input
+ * for chaining. Functions (used as `trigger`) are frozen at the field
+ * level (Object.freeze on the containing object) but not descended
+ * into.
+ *
+ * @template T
+ * @param {T} value
+ * @returns {Readonly<T>}
+ */
+function deepFreeze(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const key of Reflect.ownKeys(value)) {
+    const nested = /** @type {any} */ (value)[key];
+    if (nested !== null && typeof nested === 'object' && !Object.isFrozen(nested)) {
+      deepFreeze(nested);
+    }
+  }
+  return value;
+}
+
+/**
+ * Ratified catalogue. Editing this array in-place is a spec change;
+ * adding a question requires evidence per §A.3. Deep-frozen so the
+ * shape cannot drift in memory even at nested field level (review
+ * N-6).
+ *
+ * @type {Readonly<DesignShapeQuestion[]>}
+ */
+export const CATALOGUE_V1 = deepFreeze([
+  {
+    id: 'auth.htmlLoginPage',
+    scope: 'reqScoped',
+    trigger: reqCarriesAuthShape,
+    prompt: 'HTML login page or API-only?',
+    choices: [
+      {
+        value: 'htmlLoginPage',
+        display: 'HTML login page',
+        triggersOptOut: false,
+        uiBaselineWritePath: 'defaults.authFlow.htmlLoginPageRequired',
+        uiBaselineWriteValue: true,
+      },
+      {
+        value: 'apiOnly',
+        display: 'API-only',
+        triggersOptOut: true,
+        uiBaselineWritePath: 'defaults.authFlow.htmlLoginPageRequired',
+        uiBaselineWriteValue: false,
+      },
+    ],
+    reasonMinLength: 20,
+    baselineKey: 'auth.htmlLoginPage',
+  },
+]);
+
+/**
+ * Given the REQs in scope, decide which questions to pose against each
+ * REQ. Returns one entry per (question, req) pair whose trigger fires;
+ * the interactive session iterates in the returned order.
+ *
+ * @param {object[]} reqs
+ * @param {Readonly<DesignShapeQuestion[]>} [catalogue]
+ * @returns {Array<{ question: DesignShapeQuestion, reqId: string }>}
+ */
+export function selectApplicableQuestions(reqs, catalogue = CATALOGUE_V1) {
+  /** @type {Array<{ question: DesignShapeQuestion, reqId: string }>} */
+  const out = [];
+  for (const req of reqs ?? []) {
+    if (!req?.reqId) continue;
+    for (const question of catalogue) {
+      if (question.scope !== 'reqScoped') continue;
+      if (question.trigger(req)) {
+        out.push({ question, reqId: req.reqId });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Validate a design-shape answer against the catalogue. Returns null on
+ * a valid answer, or a string message describing the problem.
+ *
+ * @param {object} args
+ * @param {string} args.questionId
+ * @param {string} args.answer
+ * @param {string} [args.reason]
+ * @returns {string|null}
+ */
+export function validateDesignShapeAnswer({ questionId, answer, reason }) {
+  const question = CATALOGUE_V1.find((q) => q.id === questionId);
+  if (!question) return `unknown design-shape question '${questionId}'`;
+  const choice = question.choices.find((c) => c.value === answer);
+  if (!choice) {
+    const values = question.choices.map((c) => c.value).join(' | ');
+    return `unknown answer '${answer}' for question '${questionId}' (expected ${values})`;
+  }
+  if (choice.triggersOptOut) {
+    if (typeof reason !== 'string' || reason.length < question.reasonMinLength) {
+      return `answer '${answer}' for question '${questionId}' writes a baseline opt-out; reason must be at least ${question.reasonMinLength} characters`;
+    }
+  }
+  return null;
+}

package/src/preflight/index.js

@@ -0,0 +1,90 @@
+// Barrel: pre-flight surface for verification-integrity-cluster-spec §4.
+//
+// Consumers reach the pre-flight surface through this barrel so the
+// internal file layout (secrets side-file, scanner, session, design
+// shapes, manifest writer) can evolve without churning callers. The
+// gitignore aggregator seam is the sole exception: `managed-gitignore.js`
+// imports `preflightEntry` directly from `./secrets.js` to keep the
+// aggregator's own import list flat, one entry per module (0.6.0 spec
+// §4.1 D-4 pattern).
+
+import {
+  CATALOGUE_V1,
+} from './design-shapes.js';
+import {
+  composeOptOutRecord,
+} from './manifest-writer.js';
+
+export {
+  preflightEntry,
+  preflightSecretsPath,
+  loadPreflightSecretsFile,
+  recordPreflightSecret,
+} from './secrets.js';
+
+export {
+  scanForServiceCandidates,
+  CATEGORY_DISPLAY_NAMES,
+} from './scanner.js';
+
+export {
+  CATALOGUE_V1,
+  selectApplicableQuestions,
+  validateDesignShapeAnswer,
+} from './design-shapes.js';
+
+export {
+  composePreflightRecord,
+  composeOptOutRecord,
+  nextPreflightId,
+  nextOptOutId,
+  writePreflightRecord,
+} from './manifest-writer.js';
+
+export {
+  runInteractiveSession,
+  normaliseNonInteractiveInput,
+} from './session.js';
+
+/**
+ * Compose the baselineAcOptOuts entries triggered by design-shape
+ * answers on a preflight record. Called by the CLI handler after
+ * `composePreflightRecord` so the `linkedPreFlightConfigRef` can point
+ * at the composed record's id.
+ *
+ * @param {object} args
+ * @param {object|null} args.manifest
+ * @param {object} args.preflightRecord   the composed record (id already allocated)
+ * @param {import('./manifest-writer.js').PreflightDesignShapeAnswer[]} args.designShapeAnswers
+ * @param {Date} [args.now]
+ * @returns {object[]}
+ */
+export function composeDesignShapeOptOuts({ manifest, preflightRecord, designShapeAnswers, now = new Date() }) {
+  const optOuts = [];
+  let dateCursor = now;
+  for (const answer of designShapeAnswers) {
+    const question = CATALOGUE_V1.find((q) => q.id === answer.questionId);
+    if (!question) continue;
+    const choice = question.choices.find((c) => c.value === answer.answer);
+    if (!choice || !choice.triggersOptOut) continue;
+    // Compose one opt-out at a time so the id monotonic counter walks
+    // forward correctly on a single-session batch. We synthesise a
+    // provisional manifest snapshot per compose so `nextOptOutId` sees
+    // any records the previous compose calls in this loop added.
+    const provisional = {
+      ...(manifest ?? {}),
+      baselineAcOptOuts: [...(manifest?.baselineAcOptOuts ?? []), ...optOuts],
+    };
+    const linkedPreFlightConfigRef = `${preflightRecord.id}#designShapeAnswers.${answer.questionId}`;
+    const record = composeOptOutRecord({
+      manifest: provisional,
+      baselineKey: question.baselineKey,
+      reason: answer.reason ?? '',
+      reqId: answer.reqId,
+      linkedPreFlightConfigRef,
+      now: dateCursor,
+    });
+    optOuts.push(record);
+  }
+  return optOuts;
+}

package/src/preflight/manifest-writer.js

@@ -0,0 +1,264 @@
+// Pre-flight manifest writer
+// (verification-integrity-cluster-spec §3.3, ADDENDUM §A.2).
+//
+// Composes and persists `preFlightConfig[]` records on the project
+// manifest. The record shape is defined by the 0.4.0 manifest schema
+// (`$defs/preFlightConfigRecord`); this module owns id allocation,
+// timestamping, per-service entry composition, design-shape answer
+// composition, and the `baselineAcOptOuts[]` fold that happens when a
+// design-shape answer triggers a ledger write per §A.2.
+//
+// The writer takes an already-loaded walker tree and a session summary,
+// runs the composition, and calls the core store's `updateDocument`
+// against the manifest. All secrets discipline is upstream: this module
+// never sees a credential value; the session's per-service records carry
+// only booleans (`credentialSupplied`, `sandboxProvisioned`) and the
+// env-var NAME (side-file, not chain).
+
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { rcfError } from '#core/errors';
+import { validateDocument } from '#core/store';
+
+/**
+ * @typedef {object} PreflightServiceRuling
+ * @property {string} id
+ * @property {string} displayName
+ * @property {string[]} sourceRefs
+ * @property {'live'|'sandboxed'|'mocked'|'declaredMockOnly'|'notShipped'} attestationMode
+ * @property {boolean} credentialSupplied
+ * @property {boolean} sandboxProvisioned
+ * @property {string} [operatorReason]
+ * @property {string[]} [affectedFbsIds]
+ */
+
+/**
+ * @typedef {object} PreflightDesignShapeAnswer
+ * @property {string} questionId
+ * @property {string} [reqId]
+ * @property {string} answer
+ * @property {string} [reason]
+ */
+
+/**
+ * @typedef {object} BaselineOptOutWrite
+ * @property {string} baselineKey
+ * @property {'req'|'project'} scope
+ * @property {string} reason
+ * @property {string} [reqId]
+ * @property {string} linkedPreFlightConfigRef
+ */
+
+/**
+ * Compute the next preFlightConfig id for today: monotonic
+ * `pfc-YYYY-MM-DD-NNN`. Reads the manifest's existing preFlightConfig
+ * to find the highest suffix for the given date.
+ *
+ * @param {object|null} manifest
+ * @param {Date} now
+ * @returns {string}
+ */
+export function nextPreflightId(manifest, now) {
+  const y = now.getUTCFullYear().toString().padStart(4, '0');
+  const m = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+  const d = now.getUTCDate().toString().padStart(2, '0');
+  const prefix = `pfc-${y}-${m}-${d}-`;
+  const existing = Array.isArray(manifest?.preFlightConfig) ? manifest.preFlightConfig : [];
+  let maxN = 0;
+  for (const rec of existing) {
+    if (typeof rec?.id !== 'string' || !rec.id.startsWith(prefix)) continue;
+    const suffix = rec.id.slice(prefix.length);
+    const n = Number.parseInt(suffix, 10);
+    if (Number.isFinite(n) && n > maxN) maxN = n;
+  }
+  const next = (maxN + 1).toString().padStart(3, '0');
+  return `${prefix}${next}`;
+}
+
+/**
+ * Compute the next baselineAcOptOuts id: monotonic `boo-YYYY-MM-DD-NNN`.
+ *
+ * @param {object|null} manifest
+ * @param {Date} now
+ * @returns {string}
+ */
+export function nextOptOutId(manifest, now) {
+  const y = now.getUTCFullYear().toString().padStart(4, '0');
+  const m = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+  const d = now.getUTCDate().toString().padStart(2, '0');
+  const prefix = `boo-${y}-${m}-${d}-`;
+  const existing = Array.isArray(manifest?.baselineAcOptOuts) ? manifest.baselineAcOptOuts : [];
+  let maxN = 0;
+  for (const rec of existing) {
+    if (typeof rec?.id !== 'string' || !rec.id.startsWith(prefix)) continue;
+    const n = Number.parseInt(rec.id.slice(prefix.length), 10);
+    if (Number.isFinite(n) && n > maxN) maxN = n;
+  }
+  return `${prefix}${(maxN + 1).toString().padStart(3, '0')}`;
+}
+
+/**
+ * Compose one preFlightConfig record from a session. The record's
+ * `id` is monotonic per date; `createdAt` and `operatorAckAt` are the
+ * same instant for a completed session.
+ *
+ * @param {object} args
+ * @param {object|null} args.manifest
+ * @param {string} args.prdId
+ * @param {PreflightServiceRuling[]} args.services
+ * @param {PreflightDesignShapeAnswer[]} [args.designShapeAnswers]
+ * @param {Date} [args.now]
+ * @returns {object}
+ */
+export function composePreflightRecord({
+  manifest, prdId, services, designShapeAnswers = [], now = new Date(),
+}) {
+  const isoNow = now.toISOString();
+  const id = nextPreflightId(manifest, now);
+  const servicesInScope = services.map((s) => {
+    const entry = {
+      id: s.id,
+      displayName: s.displayName,
+      sourceRefs: Array.isArray(s.sourceRefs) ? [...s.sourceRefs] : [],
+      attestationMode: s.attestationMode,
+      credentialSupplied: Boolean(s.credentialSupplied),
+      sandboxProvisioned: Boolean(s.sandboxProvisioned),
+    };
+    if (typeof s.operatorReason === 'string' && s.operatorReason.length > 0) {
+      entry.operatorReason = s.operatorReason;
+    }
+    if (Array.isArray(s.affectedFbsIds) && s.affectedFbsIds.length > 0) {
+      entry.affectedFbsIds = [...s.affectedFbsIds];
+    }
+    return entry;
+  });
+  const record = {
+    id,
+    createdAt: isoNow,
+    prdId,
+    servicesInScope,
+    operatorAckAt: isoNow,
+  };
+  if (Array.isArray(designShapeAnswers) && designShapeAnswers.length > 0) {
+    record.designShapeAnswers = designShapeAnswers.map((a) => {
+      const entry = { questionId: a.questionId, answer: a.answer, answeredAt: isoNow };
+      if (typeof a.reqId === 'string' && a.reqId.length > 0) entry.reqId = a.reqId;
+      if (typeof a.reason === 'string' && a.reason.length > 0) entry.reason = a.reason;
+      return entry;
+    });
+  }
+  return record;
+}
+
+/**
+ * Compose a baselineAcOptOuts entry for a design-shape answer that
+ * triggers a ledger write (ADDENDUM §A.2). The record is REQ-scoped
+ * when the answer is REQ-scoped; project scope requires an explicit
+ * upstream ruling.
+ *
+ * @param {object} args
+ * @param {object|null} args.manifest
+ * @param {string} args.baselineKey
+ * @param {string} args.reason
+ * @param {string} [args.reqId]
+ * @param {string} args.linkedPreFlightConfigRef
+ * @param {Date} [args.now]
+ * @returns {object}
+ */
+export function composeOptOutRecord({
+  manifest, baselineKey, reason, reqId, linkedPreFlightConfigRef, now = new Date(),
+}) {
+  const isoNow = now.toISOString();
+  const id = nextOptOutId(manifest, now);
+  const record = {
+    id,
+    createdAt: isoNow,
+    baselineKey,
+    scope: reqId ? 'req' : 'project',
+    reason,
+    operatorAckAt: isoNow,
+    linkedPreFlightConfigRef,
+  };
+  if (reqId) record.reqId = reqId;
+  return record;
+}
+
+/**
+ * Persist a preflight session: append the composed record onto the
+ * manifest's `preFlightConfig[]` and any triggered opt-out records onto
+ * `baselineAcOptOuts[]`. Validates the composed manifest against the
+ * schema BEFORE writing; on validation failure the on-disk manifest is
+ * untouched. Atomic write via a `.tmp` rename so a partial write cannot
+ * leave the manifest half-composed.
+ *
+ * The store's `updateDocument` verb accepts child-doc and root-doc ids
+ * (PRD / TAD / BS) via `pathForId`, but the manifest sits outside that
+ * id space; every other manifest mutation the codebase performs also
+ * goes direct-to-disk (see `initProject` in `core/store/init.js`), which
+ * this helper mirrors.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {object} args.record         the composed preFlightConfig record
+ * @param {object[]} [args.optOuts]    composed baselineAcOptOuts entries
+ * @param {object} [args.uiBaselineWrites]  optional deep-set writes for uiBaseline.defaults (Track B fenced-TODO)
+ * @param {object} [args.options]
+ * @returns {Promise<{ record: object, optOutIds: string[], skippedUiBaseline: boolean } | import('#core/errors').RcfError>}
+ */
+export async function writePreflightRecord({
+  projectRoot, tree, record, optOuts = [], options = {},
+}) {
+  const manifest = tree.manifest ?? {};
+  const nextManifest = { ...manifest };
+
+  const existingPfc = Array.isArray(nextManifest.preFlightConfig) ? nextManifest.preFlightConfig : [];
+  nextManifest.preFlightConfig = [...existingPfc, record];
+
+  if (optOuts.length > 0) {
+    const existingOptOuts = Array.isArray(nextManifest.baselineAcOptOuts) ? nextManifest.baselineAcOptOuts : [];
+    nextManifest.baselineAcOptOuts = [...existingOptOuts, ...optOuts];
+  }
+
+  const relPath = 'rcf/manifest.json';
+  const validation = validateDocument({ doc: nextManifest, kind: 'manifest', filePath: relPath });
+  if (validation) return validation;
+
+  const absPath = join(projectRoot, 'rcf', 'manifest.json');
+  if (options.dryRun) {
+    return { record, optOutIds: optOuts.map((o) => o.id), skippedUiBaseline: true, dryRun: true };
+  }
+  try {
+    await mkdir(dirname(absPath), { recursive: true });
+    const tmp = `${absPath}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
+    try {
+      await rename(tmp, absPath);
+    } catch (err) {
+      try { await unlink(tmp); } catch { /* ignore */ }
+      throw err;
+    }
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `preflight: manifest write failed: ${err.message}`,
+      filePath: relPath,
+      stack: err.stack,
+    });
+  }
+  return {
+    record,
+    optOutIds: optOuts.map((o) => o.id),
+    // Track A does NOT build the uiBaseline init machinery (that's
+    // Track B). When a design-shape answer would write into
+    // `uiBaseline.defaults.authFlow.htmlLoginPageRequired` and no
+    // `uiBaseline` record exists yet, the answer stays in
+    // designShapeAnswers[] and (when the answer is API-only) in the
+    // baselineAcOptOuts[] ledger, exactly as ADDENDUM §A.2 specifies.
+    // The uiBaseline write itself is fenced pending Track B — the
+    // linkedPreFlightConfigRef on the opt-out record is the seam
+    // Track B reads.
+    skippedUiBaseline: true,
+  };
+}