@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/{qa-from-prd.js → qa/from-prd.js}

@@ -6,11 +6,11 @@
  * orchestration (SETUP → DRAFT → EXECUTE) can be re-used verbatim.
  *
  * This module is deliberately PURE in the same sense validateSpec is pure:
- * the only I/O it performs is reading the PRD JSON (under prd/ with an
- * archive fallback) and, optionally, a guide markdown file under
- * prd/guides/. No git, no network, no dispatch — every live target/worktree
- * decision is deferred to the SETUP phase. That keeps it trivially
- * unit-testable against fixture PRDs in an isolated MINIONS_TEST_DIR.
+ * the only I/O it performs is reading the PRD (from the SQL PRD store, with a
+ * legacy prd/ + prd/archive/ filesystem fallback) and, optionally, a guide
+ * markdown file under prd/guides/. No git, no network, no dispatch — every
+ * live target/worktree decision is deferred to the SETUP phase. That keeps it
+ * trivially unit-testable against fixture PRDs in an isolated MINIONS_TEST_DIR.
  *
  * Public API:
  *   buildQaSessionSpecFromPrd(prdInput, opts) -> { spec, warnings, provenance }
@@ -27,8 +27,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
-const qaSessions = require('./qa-sessions');
+const shared = require('../core/shared');
+const qaSessions = require('./sessions');
 
 const { LIMITS, VALID_MODES, validateSpec } = qaSessions;
 
@@ -68,6 +68,19 @@ class QaFromPrdError extends Error {
   }
 }
 
+/**
+ * Classify a caught error as a builder rejection WITHOUT `instanceof`.
+ *
+ * This module is deliberately re-required per isolated MINIONS_TEST_DIR (see
+ * test/_helpers.js ISOLATED_MODULES) because it captures `shared`, so two live
+ * copies of the class can exist at once. An `instanceof` check across that
+ * boundary silently downgrades a typed 400 into a 500, which is exactly the
+ * bug this predicate exists to prevent. Callers in other modules MUST use it.
+ */
+function isQaFromPrdError(err) {
+  return !!err && err.name === 'QaFromPrdError' && typeof err.reason === 'string';
+}
+
 function _isNonEmptyString(v) {
   return typeof v === 'string' && v.trim().length > 0;
 }
@@ -95,9 +108,17 @@ function _guidesDir() {
 }
 
 /**
- * Resolve prdInput to { prd, prdFile }. When given a string, read the JSON
- * from prd/<file> (then prd/archive/<file>). When given an object, use it
- * verbatim (prdFile stays null → no guide lookup is possible).
+ * Resolve prdInput to { prd, prdFile }. When given a string, read the PRD from
+ * the authoritative SQL store (live bucket, then the archive bucket), falling
+ * back to legacy on-disk prd/<file> / prd/archive/<file> JSON. When given an
+ * object, use it verbatim (prdFile stays null → no guide lookup is possible).
+ *
+ * The SQL read is FIRST because migration 018 made `engine/state.db` the sole
+ * PRD authority — `prd/*.json` files no longer exist on a migrated install, so
+ * a filesystem-only lookup answered `prd-not-found` for every real PRD and made
+ * the guide-preferring flow priority (which needs the PRD *filename*)
+ * unreachable. The filesystem read is kept as a fallback for legacy installs
+ * and fixture-seeded test dirs.
  *
  * @throws {QaFromPrdError} prd-invalid-input / prd-not-found / prd-invalid-json
  */
@@ -112,16 +133,24 @@ function _resolvePrd(prdInput) {
   if (!_isSafePrdFileName(file)) {
     throw new QaFromPrdError(`invalid PRD filename: ${file}`);
   }
+
+  for (const archived of [false, true]) {
+    let stored = null;
+    try { stored = require('../planning/prd-store').readPrd(file, { archived }); }
+    catch { stored = null; /* no DB / unreadable row → fall through to disk */ }
+    if (stored && typeof stored === 'object' && !Array.isArray(stored)) {
+      return { prd: stored, prdFile: file };
+    }
+  }
+
   const candidates = [
     path.join(_prdDir(), file),
     path.join(_prdDir(), 'archive', file),
   ];
   let raw = null;
-  let found = null;
   for (const p of candidates) {
     try {
       raw = fs.readFileSync(p, 'utf8');
-      found = p;
       break;
     } catch { /* try next */ }
   }
@@ -421,6 +450,7 @@ function buildQaSessionSpecFromPrd(prdInput, opts = {}) {
 module.exports = {
   buildQaSessionSpecFromPrd,
   QaFromPrdError,
+  isQaFromPrdError,
   // Constants + internals exposed for tests.
   QA_READY_STATUSES,
   QA_PRD_FILENAME_MAX,

package/engine/qa/prd-session.js

@@ -0,0 +1,240 @@
+/**
+ * engine/qa/prd-session.js — the ONE PRD → QA-Session orchestration path.
+ *
+ * `POST /api/qa/from-prd` (dashboard.js#handleQaFromPrdCreate) and the
+ * post-verify auto-QA hook (engine/qa/auto-prd-qa.js) must create *identical*
+ * sessions: same spec builder, same project canonicalization, same
+ * createSession + queueSetup ordering, same provenance shape. Before this
+ * module the orchestration lived inline in the HTTP handler, so the only way
+ * for the engine to launch a PRD-driven session was to fork it — and a fork
+ * drifts. Everything that is genuinely HTTP-specific (body validation, header
+ * identity, status-code mapping, the non-blocking runner hint) stays in the
+ * handler; everything that defines *what a PRD-driven QA session is* lives
+ * here.
+ *
+ * The only injected seam is `resolveTargets`. Project resolution differs by
+ * caller on purpose: the dashboard runs each name through its HTTP-input
+ * validator so a bad project is a 400 with an `ApiInputError` path, while the
+ * engine resolves names that came out of the PRD itself against the live
+ * config. Injecting it keeps those two contracts intact without duplicating
+ * the orchestration around them.
+ */
+
+const shared = require('../core/shared');
+const qaSessions = require('./sessions');
+const qaFromPrd = require('./from-prd');
+
+/**
+ * Thrown when the resolver rejects a project. Carries `.reason` so callers can
+ * surface the same 400 body the inline implementation produced.
+ */
+class QaPrdSessionError extends Error {
+  constructor(reason, extra = {}) {
+    super(reason);
+    this.name = 'QaPrdSessionError';
+    this.reason = reason;
+    if (extra && typeof extra === 'object') {
+      for (const [k, v] of Object.entries(extra)) {
+        if (k !== 'reason' && k !== 'name') this[k] = v;
+      }
+    }
+  }
+}
+
+/**
+ * Name-based classifier, for the same reason `from-prd.js#isQaFromPrdError`
+ * exists: this module is re-required per isolated test root, so `instanceof`
+ * across a module boundary is not a reliable way to recognise the error.
+ */
+function isQaPrdSessionError(err) {
+  return !!err && err.name === 'QaPrdSessionError' && typeof err.reason === 'string';
+}
+
+/**
+ * Rewrite the spec's project field(s) to the CANONICAL names the resolver
+ * produced, preserving the single-string vs array shape validateSpec expects.
+ * Extracted verbatim from dashboard.js#_qaCanonicalizeResolvedProjects.
+ *
+ * W-msb9kgs402813a97-a — `primaryProject` and the `projectTargets` keys name
+ * projects too, so they are canonicalized through the SAME resolver output.
+ * Without this, a spec that named `"Web"` would end up with
+ * `projects: ["web"]` but `primaryProject: "Web"`, and validateSpec would
+ * reject a spec the caller wrote correctly.
+ */
+function canonicalizeResolvedProjects(spec, resolution) {
+  const normalized = { ...spec };
+  const targets = Array.isArray(resolution && resolution.targets) ? resolution.targets : [];
+  // Both resolvers stamp `requested` (the name the caller wrote) next to the
+  // canonical `project`, so the mapping survives de-duplication and the
+  // primary-first reordering below. The case-insensitive fallback covers
+  // callers that hand back bare `{ project, scope }` targets.
+  const byRequested = new Map();
+  const byLowerCanonical = new Map();
+  for (const target of targets) {
+    if (!target || !target.project) continue;
+    if (typeof target.requested === 'string' && target.requested) {
+      byRequested.set(target.requested, target.project);
+    }
+    byLowerCanonical.set(String(target.project).toLowerCase(), target.project);
+  }
+  const canonical = (name) => byRequested.get(name)
+    || byLowerCanonical.get(String(name).trim().toLowerCase())
+    || name;
+
+  if (Array.isArray(normalized.projects) && normalized.projects.length > 0) {
+    normalized.projects = targets.map(target => target.project);
+  } else if (targets.length === 1 && targets[0].project) {
+    normalized.project = targets[0].project;
+  }
+  if (typeof normalized.primaryProject === 'string' && normalized.primaryProject) {
+    normalized.primaryProject = canonical(normalized.primaryProject);
+  }
+  if (normalized.projectTargets && typeof normalized.projectTargets === 'object'
+      && !Array.isArray(normalized.projectTargets)) {
+    const rekeyed = {};
+    for (const [name, target] of Object.entries(normalized.projectTargets)) {
+      rekeyed[canonical(name)] = target;
+    }
+    normalized.projectTargets = rekeyed;
+  }
+  return normalized;
+}
+
+/**
+ * Move the target that hosts `spec.primaryProject` to the front and stamp a
+ * `primary` boolean on every entry. Shared by both resolvers so the HTTP and
+ * engine paths hand `queueSetup` an identically-ordered list.
+ *
+ * A `primaryProject` naming a project that was not resolved is left alone —
+ * `qaSessions.validateSpec` owns that rejection and produces the actionable
+ * error; silently reordering around an unknown name would hide it.
+ */
+function orderTargetsByPrimary(spec, targets) {
+  const requestedPrimary = spec && typeof spec.primaryProject === 'string' ? spec.primaryProject : '';
+  const ordered = targets.slice();
+  if (requestedPrimary) {
+    const lower = requestedPrimary.trim().toLowerCase();
+    const index = ordered.findIndex(t => t
+      && (t.requested === requestedPrimary || String(t.project || '').toLowerCase() === lower));
+    if (index > 0) ordered.unshift(ordered.splice(index, 1)[0]);
+  }
+  return ordered.map((target, index) => ({ ...target, primary: index === 0 }));
+}
+
+/**
+ * Engine-side project resolver — the non-HTTP counterpart to the dashboard's
+ * `_qaSessionsResolveTargets`. Walks the same `shared.resolveProjectSource`
+ * seam `resolveWorkItemsCreateTarget` uses (including `defaultWhenSingle`, so a
+ * single-project install still binds a project when the PRD names none) and
+ * returns `{ targets }` or `{ error }`.
+ *
+ * Duplicates are DROPPED rather than rejected: unlike an operator-authored HTTP
+ * body, a PRD's project list is derived from its items, so a repeat is expected
+ * shape rather than a caller bug.
+ */
+function resolveTargetsFromConfig(spec, config) {
+  const projects = shared.getProjects(config);
+  const list = Array.isArray(spec && spec.projects) && spec.projects.length > 0
+    ? spec.projects.slice()
+    : [spec && spec.project ? spec.project : ''];
+  const targets = [];
+  const seen = new Set();
+  for (const name of list) {
+    const resolved = shared.resolveProjectSource(name, projects, {
+      defaultWhenSingle: true,
+      minionsDir: shared.MINIONS_DIR,
+    });
+    if (resolved.error) return { error: `project "${name || '(central)'}": ${resolved.error}` };
+    const projectName = resolved.project ? resolved.project.name : null;
+    const key = projectName || '__central__';
+    if (seen.has(key)) continue;
+    seen.add(key);
+    targets.push({ scope: resolved.scope, project: projectName, requested: name });
+  }
+  return { targets: orderTargetsByPrimary(spec, targets) };
+}
+
+/**
+ * Build a QA Session from a PRD and queue its SETUP phase.
+ *
+ * @param {string|object} prdInput  PRD filename (under prd/) or parsed PRD object.
+ * @param {object} opts
+ * @param {string}   [opts.mode]              'confirm' (default) | 'auto'
+ * @param {string}   [opts.runner]            explicit kebab-case runner
+ * @param {string}   [opts.createdBy]         audit identity stamped on the session
+ * @param {object}   [opts.provenanceExtra]   merged into the builder's provenance
+ * @param {Function} opts.resolveTargets      (spec) => { targets } | { error }
+ * @returns {{ session, sessionId, setupWorkItemId, resolution, spec, warnings, provenance, flowSource }}
+ * @throws {qaFromPrd.QaFromPrdError} unreadable/malformed/non-QA-ready PRD, bad runner
+ * @throws {QaPrdSessionError}        project resolution rejected the spec
+ * @throws {Error}                    createSession/queueSetup rejection (`.sessionId`
+ *                                    is stamped when the session already exists)
+ */
+function createQaSessionFromPrd(prdInput, opts = {}) {
+  const options = opts && typeof opts === 'object' ? opts : {};
+  if (typeof options.resolveTargets !== 'function') {
+    throw new TypeError('qa/prd-session: createQaSessionFromPrd requires opts.resolveTargets');
+  }
+
+  const built = qaFromPrd.buildQaSessionSpecFromPrd(prdInput, {
+    mode: options.mode,
+    runner: options.runner,
+  });
+  const { spec, warnings, provenance } = built;
+
+  let createSpec = { ...spec };
+  if (typeof options.createdBy === 'string' && options.createdBy) {
+    createSpec.createdBy = options.createdBy;
+  }
+  // Provenance rides alongside the spec → persisted on the session record by
+  // createSession (P-c5a2f8b7). Not part of the validateSpec contract.
+  createSpec.provenance = options.provenanceExtra && typeof options.provenanceExtra === 'object'
+    ? { ...provenance, ...options.provenanceExtra }
+    : provenance;
+
+  // Resolve EACH project BEFORE persisting — one bad project rejects the whole
+  // submit rather than stranding a half-created session.
+  const resolution = options.resolveTargets(createSpec);
+  if (resolution && resolution.error) {
+    throw new QaPrdSessionError(resolution.error, { kind: 'project' });
+  }
+  if (!resolution || !Array.isArray(resolution.targets) || resolution.targets.length === 0) {
+    throw new QaPrdSessionError('QA project resolution produced no targets', { kind: 'project' });
+  }
+  createSpec = canonicalizeResolvedProjects(createSpec, resolution);
+
+  const session = qaSessions.createSession(createSpec);
+
+  let setupWorkItemId = null;
+  try {
+    setupWorkItemId = qaSessions.queueSetup(session.id, {
+      resolvedTargets: resolution.targets.map(t => ({ project: t.project, scope: t.scope })),
+    });
+  } catch (e) {
+    // The session exists but has no SETUP WI. Surface the id so the caller can
+    // report/inspect it instead of leaking an orphan.
+    e.sessionId = session.id;
+    e.kind = 'queue';
+    throw e;
+  }
+
+  return {
+    session,
+    sessionId: session.id,
+    setupWorkItemId,
+    resolution,
+    spec: createSpec,
+    warnings: Array.isArray(warnings) ? warnings : [],
+    provenance: createSpec.provenance,
+    flowSource: (createSpec.provenance && createSpec.provenance.flowSource) || null,
+  };
+}
+
+module.exports = {
+  createQaSessionFromPrd,
+  canonicalizeResolvedProjects,
+  orderTargetsByPrimary,
+  resolveTargetsFromConfig,
+  QaPrdSessionError,
+  isQaPrdSessionError,
+};

package/engine/{qa-process-validation.js → qa/process-validation.js}

@@ -1,12 +1,12 @@
 'use strict';
 
-const apiValidation = require('./api-validation');
-const keepProcesses = require('./keep-process-sweep');
-const qaFromPrd = require('./qa-from-prd');
-const qaRunbooks = require('./qa-runbooks');
-const qaRuns = require('./qa-runs');
-const qaSessions = require('./qa-sessions');
-const shared = require('./shared');
+const apiValidation = require('../api/api-validation');
+const keepProcesses = require('../processes/keep-process-sweep');
+const qaFromPrd = require('./from-prd');
+const qaRunbooks = require('./runbooks');
+const qaRuns = require('./runs');
+const qaSessions = require('./sessions');
+const shared = require('../core/shared');
 
 const {
   ApiInputError,
@@ -112,7 +112,7 @@ function validateObjectFields(value, allowedFields, pathName = 'body') {
 
 function validateKnownRunner(runner, pathName) {
   if (runner === undefined || runner === null || runner === '') return runner;
-  const qaRunners = require('./qa-runners');
+  const qaRunners = require('../qa-runners');
   if (!qaRunners.getRunner(runner)) {
     throw new ApiInputError(`Unknown QA runner: ${runner}`, {
       code: 'unknown-qa-runner',
@@ -163,6 +163,11 @@ function validateQaSessionRequest(body, options = {}) {
     'runner',
     'project',
     'projects',
+    // W-msb9kgs402813a97-a — explicit multi-project contract. The allowlist
+    // rejects unknown body fields, so omitting these would 400 a spec that
+    // qaSessions.validateSpec accepts.
+    'primaryProject',
+    'projectTargets',
     'createdBy',
   ]);
   const result = qaSessions.validateSpec(body);
@@ -414,7 +419,7 @@ function validateRunbookId(value, pathName = 'path.id') {
 }
 
 function validateManagedSpecName(value, pathName) {
-  const result = require('./managed-spawn').validateManagedSpecName(value);
+  const result = require('../processes/managed-spawn').validateManagedSpecName(value);
   if (!result.ok) {
     throw new ApiInputError('Invalid managed process name', {
       code: 'invalid-managed-process-name',

package/engine/{qa-runbooks.js → qa/runbooks.js}

@@ -17,7 +17,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 
 const RUNBOOKS_DIR = 'runbooks';