@yemi33/minions 0.1.2447 → 0.1.2449

package/engine/{cc-api-validation.js → api/cc-api-validation.js}

@@ -2,7 +2,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const shared = require('./shared');
+const shared = require('../core/shared');
 const apiValidation = require('./api-validation');
 
 const CC_API_LIMITS = Object.freeze({

package/engine/api/companion.js

@@ -0,0 +1,560 @@
+/**
+ * engine/api/companion.js — Constellation companion detection (P-e93c85a1).
+ *
+ * Makes Minions HONEST about whether a compatible Constellation companion is
+ * present on this host. It reports; it never repairs.
+ *
+ * NON-GOALS, deliberately and permanently:
+ *   - Minions NEVER downloads Constellation.
+ *   - Minions NEVER executes a Constellation binary or installer.
+ *   - There is no recursion marker, reciprocal bootstrap, or ping-pong
+ *     handshake here. The single optional bootstrap path is Constellation-owned
+ *     and runs in one direction only.
+ * Minions installs and operates INDEPENDENTLY: companion absence is a visible
+ * degraded state, never a takeover trigger and never fatal.
+ *
+ * Detection signal, in order:
+ *   1. The existing cross-repo marker `~/.minions/engine/constellation-bridge.json`
+ *      (written by the Constellation agent — see docs/constellation-bridge.md).
+ *      Its presence IS the presence signal; there is no PATH lookup and no
+ *      directory-name heuristic anywhere in this module.
+ *   2. An OPTIONAL bounded health probe against the companion's declared
+ *      loopback health endpoint, used to resolve a version the marker omitted.
+ *      Loopback-only by construction, so the probe can never reach the network.
+ *
+ * Every path is bounded: the marker read is a single stat+read, and the health
+ * probe always carries an explicit timeout, so a hung companion can never stall
+ * `minions doctor`, `minions bridge health`, `minions init`, `minions update`,
+ * or engine start.
+ *
+ * Zero runtime dependencies: Node built-ins only.
+ */
+
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+
+const shared = require('../core/shared');
+
+const {
+  CONSTELLATION_BRIDGE_MARKER_PATH,
+  CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION,
+  ENGINE_DEFAULTS,
+} = shared;
+
+/** The complete status vocabulary reported by the probe. */
+const COMPANION_STATUS = Object.freeze({
+  OK: 'companion-ok',
+  INCOMPATIBLE: 'companion-incompatible',
+  MISSING: 'companion-missing',
+  UNKNOWN: 'companion-unknown',
+});
+
+// Declared compatibility window for the Constellation companion agent. The
+// marker contract (`schemaVersion: 1`, documented `agentVersion: "0.2.3"`) is
+// the floor; the next major is the ceiling because a major bump is exactly the
+// signal that the shared contract changed.
+const COMPANION_MIN_VERSION = '0.2.0';
+const COMPANION_MAX_VERSION_EXCLUSIVE = '1.0.0';
+const COMPANION_COMPATIBLE_RANGE = `>=${COMPANION_MIN_VERSION} <${COMPANION_MAX_VERSION_EXCLUSIVE}`;
+
+// Documented Constellation distribution surface. These strings are PRINTED for
+// the operator to run — this module never invokes them.
+const COMPANION_DOCS_URL = 'https://icy-water-0224cc51e.2.azurestaticapps.net/';
+const COMPANION_INSTALL_PS1 = 'https://icy-water-0224cc51e.2.azurestaticapps.net/install.ps1';
+const COMPANION_INSTALL_SH = 'https://icy-water-0224cc51e.2.azurestaticapps.net/install.sh';
+
+const HEALTH_PROBE_TIMEOUT_MIN_MS = 250;
+const HEALTH_PROBE_TIMEOUT_MAX_MS = 15000;
+// A health endpoint answers with a tiny JSON body. Cap the read so a
+// misbehaving (or wrong) local endpoint cannot stream unbounded bytes at us.
+const HEALTH_PROBE_MAX_BYTES = 64 * 1024;
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+
+// ── Config resolution ────────────────────────────────────────────────────────
+
+function _companionConfig(config) {
+  const block = config && config.engine && config.engine.constellationCompanion;
+  return block && typeof block === 'object' && !Array.isArray(block) ? block : {};
+}
+
+/**
+ * Documented opt-out for managed deployments. Either seam suppresses the probe
+ * ENTIRELY (no marker read, no health request):
+ *   - `engine.constellationCompanion.probeEnabled: false` in config.json
+ *   - `MINIONS_DISABLE_COMPANION_PROBE=1` in the environment
+ * The env var wins so a fleet image can suppress it without editing config.
+ */
+function isCompanionProbeEnabled(config, env = process.env) {
+  const flag = env && env.MINIONS_DISABLE_COMPANION_PROBE;
+  if (flag === '1' || flag === 'true') return false;
+  const configured = _companionConfig(config).probeEnabled;
+  if (configured === false) return false;
+  if (configured === true) return true;
+  return ENGINE_DEFAULTS.constellationCompanion.probeEnabled !== false;
+}
+
+function resolveCompanionProbeTimeoutMs(config) {
+  const raw = _companionConfig(config).probeTimeoutMs;
+  const fallback = ENGINE_DEFAULTS.constellationCompanion.probeTimeoutMs;
+  const value = Number.isFinite(raw) ? Number(raw) : fallback;
+  return Math.min(HEALTH_PROBE_TIMEOUT_MAX_MS, Math.max(HEALTH_PROBE_TIMEOUT_MIN_MS, value));
+}
+
+/**
+ * Resolve the companion's health endpoint. Config wins over the optional
+ * `healthUrl` the companion declares in its own marker, so an operator can
+ * always override what a third-party file claims.
+ *
+ * Loopback-only by construction. A remote host, a non-HTTP scheme, or an
+ * unparseable URL is REFUSED without being requested — that is what keeps this
+ * probe incapable of any outbound network traffic.
+ */
+function resolveCompanionHealthUrl(config, marker) {
+  const configured = _companionConfig(config).healthUrl;
+  const declared = marker && typeof marker.healthUrl === 'string' ? marker.healthUrl : null;
+  const candidate = (typeof configured === 'string' && configured.trim())
+    ? configured.trim()
+    : (declared && declared.trim() ? declared.trim() : null);
+  if (!candidate) return { url: null, error: null };
+
+  let parsed;
+  try { parsed = new URL(candidate); }
+  catch { return { url: null, error: `unsupported companion health URL: ${candidate}` }; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { url: null, error: `unsupported companion health URL scheme: ${parsed.protocol}` };
+  }
+  const host = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  if (!LOOPBACK_HOSTS.has(host)) {
+    return { url: null, error: `refused non-loopback companion health URL: ${parsed.host}` };
+  }
+  return { url: parsed.toString(), error: null };
+}
+
+// ── Version handling ─────────────────────────────────────────────────────────
+
+/**
+ * Parse a `major.minor.patch[-prerelease][+build]` string. Returns null for
+ * anything else — an unparseable version is "unknown", never "compatible".
+ */
+function parseCompanionVersion(input) {
+  if (typeof input !== 'string') return null;
+  const m = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?\s*$/.exec(input);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    prerelease: m[4] || null,
+    raw: input.trim(),
+  };
+}
+
+/**
+ * Compare on the numeric core only. A prerelease of X is treated as X, so
+ * `1.0.0-beta.1` is judged against the `<1.0.0` ceiling as the next major —
+ * the conservative reading, and the one an operator expects from a
+ * "compatible range" report.
+ */
+function compareCompanionVersions(a, b) {
+  const left = typeof a === 'string' ? parseCompanionVersion(a) : a;
+  const right = typeof b === 'string' ? parseCompanionVersion(b) : b;
+  if (!left || !right) return null;
+  for (const key of ['major', 'minor', 'patch']) {
+    if (left[key] !== right[key]) return left[key] < right[key] ? -1 : 1;
+  }
+  return 0;
+}
+
+function isCompatibleCompanionVersion(version) {
+  const parsed = parseCompanionVersion(version);
+  if (!parsed) return false;
+  const aboveFloor = compareCompanionVersions(parsed, COMPANION_MIN_VERSION);
+  const belowCeiling = compareCompanionVersions(parsed, COMPANION_MAX_VERSION_EXCLUSIVE);
+  if (aboveFloor === null || belowCeiling === null) return false;
+  return aboveFloor >= 0 && belowCeiling < 0;
+}
+
+// ── Marker read ──────────────────────────────────────────────────────────────
+
+/**
+ * Detailed marker read. Deliberately NOT `bridge.readBridgeMarker`, which
+ * collapses "absent" and "malformed" into a single `null` — this probe has to
+ * tell those apart to avoid reporting a broken companion as an absent one.
+ */
+function readCompanionMarker(markerPath = CONSTELLATION_BRIDGE_MARKER_PATH) {
+  let raw;
+  try {
+    raw = fs.readFileSync(markerPath, 'utf8');
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
+      return { present: false, marker: null, reason: 'marker-absent', error: null };
+    }
+    return { present: true, marker: null, reason: 'marker-unreadable', error: err.message };
+  }
+
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch (err) { return { present: true, marker: null, reason: 'marker-unreadable', error: err.message }; }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { present: true, marker: null, reason: 'marker-unreadable', error: 'marker is not a JSON object' };
+  }
+
+  const schemaVersion = typeof parsed.schemaVersion === 'number' ? parsed.schemaVersion : null;
+  if (schemaVersion !== CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION) {
+    return {
+      present: true, marker: null, schemaVersion,
+      reason: 'marker-schema-unsupported',
+      error: `marker schemaVersion ${schemaVersion === null ? '(absent)' : schemaVersion} — this Minions build reads ${CONSTELLATION_BRIDGE_MARKER_SCHEMA_VERSION}`,
+    };
+  }
+  if (typeof parsed.lastSeenAt !== 'string' || !parsed.lastSeenAt) {
+    return {
+      present: true, marker: null, schemaVersion,
+      reason: 'marker-unreadable', error: 'marker is missing lastSeenAt',
+    };
+  }
+
+  return {
+    present: true,
+    schemaVersion,
+    reason: null,
+    error: null,
+    marker: {
+      schemaVersion,
+      lastSeenAt: parsed.lastSeenAt,
+      agentVersion: typeof parsed.agentVersion === 'string' ? parsed.agentVersion : null,
+      source: typeof parsed.source === 'string' ? parsed.source : null,
+      healthUrl: typeof parsed.healthUrl === 'string' ? parsed.healthUrl : null,
+    },
+  };
+}
+
+// ── Bounded loopback health probe ────────────────────────────────────────────
+
+/**
+ * GET a small JSON document from a loopback URL under an explicit timeout.
+ * No redirects are followed and the body is byte-capped, so the worst case is
+ * a bounded read from localhost.
+ */
+function fetchCompanionHealthJson(url, { timeoutMs } = {}) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (err, value) => {
+      if (settled) return;
+      settled = true;
+      if (err) reject(err); else resolve(value);
+    };
+
+    let req;
+    const timer = setTimeout(() => {
+      try { if (req) req.destroy(); } catch { /* already gone */ }
+      finish(Object.assign(new Error(`companion health probe timed out after ${timeoutMs}ms`), { code: 'ETIMEDOUT' }));
+    }, timeoutMs);
+    if (typeof timer.unref === 'function') timer.unref();
+
+    const done = (err, value) => { clearTimeout(timer); finish(err, value); };
+
+    try {
+      const client = url.startsWith('https:') ? https : http;
+      req = client.get(url, { timeout: timeoutMs }, (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          done(new Error(`companion health endpoint returned HTTP ${res.statusCode}`));
+          return;
+        }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          body += chunk;
+          if (body.length > HEALTH_PROBE_MAX_BYTES) {
+            try { res.destroy(); } catch { /* already gone */ }
+            done(new Error('companion health response exceeded the size cap'));
+          }
+        });
+        res.on('end', () => {
+          try { done(null, JSON.parse(body)); }
+          catch (err) { done(new Error(`companion health response was not JSON: ${err.message}`)); }
+        });
+        res.on('error', (err) => done(err));
+      });
+      req.on('timeout', () => { try { req.destroy(); } catch { /* already gone */ } });
+      req.on('error', (err) => done(err));
+    } catch (err) {
+      done(err);
+    }
+  });
+}
+
+function _versionFromHealthPayload(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  for (const key of ['agentVersion', 'version', 'companionVersion']) {
+    if (typeof payload[key] === 'string' && payload[key].trim()) return payload[key].trim();
+  }
+  return null;
+}
+
+// ── Probe ────────────────────────────────────────────────────────────────────
+
+function _skippedResult(markerPath) {
+  return {
+    skipped: true,
+    status: null,
+    reason: 'probe-disabled',
+    fatal: false,
+    version: null,
+    versionSource: null,
+    compatibleRange: COMPANION_COMPATIBLE_RANGE,
+    markerPath,
+    markerPresent: null,
+    markerSchemaVersion: null,
+    lastSeenAt: null,
+    source: null,
+    health: null,
+  };
+}
+
+function _baseResult(markerPath, read) {
+  return {
+    skipped: false,
+    status: null,
+    reason: null,
+    detail: null,
+    fatal: false,
+    version: null,
+    versionSource: null,
+    compatibleRange: COMPANION_COMPATIBLE_RANGE,
+    markerPath,
+    markerPresent: read.present,
+    markerSchemaVersion: read.schemaVersion === undefined ? null : read.schemaVersion,
+    lastSeenAt: read.marker ? read.marker.lastSeenAt : null,
+    source: read.marker ? read.marker.source : null,
+    health: null,
+  };
+}
+
+/**
+ * Classify everything that can be decided from the marker alone. Shared by the
+ * sync and async entry points so both report identically when no health
+ * endpoint is declared (the default).
+ */
+function _classifyFromMarker(markerPath, read) {
+  const result = _baseResult(markerPath, read);
+  if (!read.present) {
+    result.status = COMPANION_STATUS.MISSING;
+    result.reason = 'marker-absent';
+    return result;
+  }
+  if (read.reason === 'marker-schema-unsupported') {
+    // The companion IS here; it just speaks a marker contract this build does
+    // not read. That is an incompatibility, not an absence.
+    result.status = COMPANION_STATUS.INCOMPATIBLE;
+    result.reason = 'marker-schema-unsupported';
+    result.detail = read.error;
+    return result;
+  }
+  if (!read.marker) {
+    result.status = COMPANION_STATUS.UNKNOWN;
+    result.reason = 'marker-unreadable';
+    result.detail = read.error;
+    return result;
+  }
+  if (read.marker.agentVersion) {
+    result.version = read.marker.agentVersion;
+    result.versionSource = 'marker';
+    result.status = isCompatibleCompanionVersion(result.version)
+      ? COMPANION_STATUS.OK
+      : COMPANION_STATUS.INCOMPATIBLE;
+    result.reason = result.status === COMPANION_STATUS.OK ? 'version-in-range' : 'version-out-of-range';
+    return result;
+  }
+  result.status = COMPANION_STATUS.UNKNOWN;
+  result.reason = 'version-unresolved';
+  return result;
+}
+
+/**
+ * Synchronous probe: marker only, no health request. Used where the caller
+ * cannot await (and where a network handle would be inappropriate anyway).
+ * Identical to the async probe whenever no health endpoint is declared.
+ */
+function probeCompanionSync({ config = null, markerPath = CONSTELLATION_BRIDGE_MARKER_PATH, env = process.env } = {}) {
+  if (!isCompanionProbeEnabled(config, env)) return _skippedResult(markerPath);
+  return _classifyFromMarker(markerPath, readCompanionMarker(markerPath));
+}
+
+/**
+ * Full probe. Marker first; then, only when the companion declares (or the
+ * operator configures) a LOOPBACK health endpoint, one bounded GET to resolve a
+ * version the marker omitted. A refused URL, a failed request, or a timeout is
+ * reported as `companion-unknown` — never as `companion-missing`.
+ *
+ * `fetchJson` is injectable for tests; production always uses the built-in
+ * bounded loopback fetch above.
+ */
+async function probeCompanion({
+  config = null,
+  markerPath = CONSTELLATION_BRIDGE_MARKER_PATH,
+  env = process.env,
+  timeoutMs = null,
+  fetchJson = fetchCompanionHealthJson,
+} = {}) {
+  if (!isCompanionProbeEnabled(config, env)) return _skippedResult(markerPath);
+
+  const read = readCompanionMarker(markerPath);
+  const result = _classifyFromMarker(markerPath, read);
+
+  // A health probe only ever ADDS information. Skip it when a version is
+  // already resolved, and when there is nothing to probe: an absent marker with
+  // no operator-configured endpoint means the only detection channel we have
+  // already answered "not here".
+  const operatorHealthUrl = _companionConfig(config).healthUrl;
+  const canProbeHealth = Boolean(read.marker) || Boolean(operatorHealthUrl);
+  if (result.version || !canProbeHealth) return result;
+
+  const resolved = resolveCompanionHealthUrl(config, read.marker);
+  if (!resolved.url) {
+    if (resolved.error) {
+      result.health = { ok: false, url: null, error: resolved.error };
+      result.status = COMPANION_STATUS.UNKNOWN;
+      result.reason = 'health-url-refused';
+    }
+    return result;
+  }
+
+  const budgetMs = Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? timeoutMs
+    : resolveCompanionProbeTimeoutMs(config);
+  try {
+    const payload = await fetchJson(resolved.url, { timeoutMs: budgetMs });
+    const version = _versionFromHealthPayload(payload);
+    result.health = { ok: true, url: resolved.url, error: null };
+    if (version) {
+      result.version = version;
+      result.versionSource = 'health';
+      result.status = isCompatibleCompanionVersion(version)
+        ? COMPANION_STATUS.OK
+        : COMPANION_STATUS.INCOMPATIBLE;
+      result.reason = result.status === COMPANION_STATUS.OK ? 'version-in-range' : 'version-out-of-range';
+    }
+  } catch (err) {
+    result.health = { ok: false, url: resolved.url, error: (err && err.message) || String(err) };
+    result.status = COMPANION_STATUS.UNKNOWN;
+    result.reason = 'health-probe-failed';
+  }
+  return result;
+}
+
+// ── Setup guidance (printed as text — NEVER executed) ────────────────────────
+
+/**
+ * The documented Constellation install command for a platform. Returns data:
+ * callers print it so the OPERATOR can run it. Nothing in this module executes
+ * a shell, and nothing downloads these URLs.
+ */
+function getCompanionInstallCommand(platform = process.platform) {
+  if (platform === 'win32') {
+    return {
+      platform,
+      shell: 'PowerShell',
+      command: `irm ${COMPANION_INSTALL_PS1} | iex`,
+      docsUrl: COMPANION_DOCS_URL,
+    };
+  }
+  return {
+    platform,
+    shell: platform === 'darwin' ? 'Terminal (macOS)' : 'shell',
+    command: `curl -fsSL ${COMPANION_INSTALL_SH} | sh`,
+    docsUrl: COMPANION_DOCS_URL,
+  };
+}
+
+const _REASON_TEXT = {
+  'marker-absent': 'no Constellation companion has registered with this Minions instance',
+  'marker-unreadable': 'the companion marker exists but could not be read',
+  'marker-schema-unsupported': 'the companion marker uses a schema this Minions build does not read',
+  'version-in-range': 'companion version is inside the compatible range',
+  'version-out-of-range': 'companion version is outside the compatible range',
+  'version-unresolved': 'the companion registered but did not declare a version',
+  'health-url-refused': 'the declared companion health endpoint was refused',
+  'health-probe-failed': 'the companion health probe did not answer',
+};
+
+/**
+ * Render the probe result as plain report lines. Returns `[]` for a suppressed
+ * probe so an opted-out deployment prints nothing at all.
+ */
+function formatCompanionLines(result, { platform = process.platform, indent = '  ' } = {}) {
+  if (!result || result.skipped || !result.status) return [];
+  const lines = [];
+  const version = result.version ? result.version : '(unknown)';
+  lines.push(`Constellation companion: ${result.status}`);
+  lines.push(`${indent}version: ${version}   compatible range: ${result.compatibleRange}`);
+  const why = _REASON_TEXT[result.reason];
+  if (why) lines.push(`${indent}${why}`);
+  if (result.detail) lines.push(`${indent}${result.detail}`);
+  if (result.lastSeenAt) lines.push(`${indent}last seen: ${result.lastSeenAt}`);
+  if (result.health && result.health.ok === false) {
+    lines.push(`${indent}health probe: ${result.health.error}`);
+  }
+  if (result.status === COMPANION_STATUS.OK) return lines;
+
+  const install = getCompanionInstallCommand(platform);
+  lines.push(`${indent}Minions runs fine without it — Constellation only mirrors state into its HUD.`);
+  lines.push(`${indent}To install or update the companion, run it yourself (${install.shell}):`);
+  lines.push(`${indent}  ${install.command}`);
+  lines.push(`${indent}Docs: ${install.docsUrl}`);
+  lines.push(`${indent}Minions never runs it for you — this is guidance, not an action.`);
+  return lines;
+}
+
+/**
+ * Render the probe result as a `minions doctor` row. Returns `null` when the
+ * probe was suppressed. NEVER `ok: false`: companion absence or incompatibility
+ * is a degraded state Minions works around, not a critical Minions failure, so
+ * `minions doctor` must not start exiting 1 on hosts without Constellation.
+ */
+function companionDoctorResult(result, { platform = process.platform } = {}) {
+  if (!result || result.skipped || !result.status) return null;
+  const version = result.version ? result.version : 'unknown version';
+  if (result.status === COMPANION_STATUS.OK) {
+    return {
+      name: 'Constellation companion',
+      ok: true,
+      message: `${result.status} — ${version} (compatible range ${result.compatibleRange})`,
+    };
+  }
+  const install = getCompanionInstallCommand(platform);
+  const why = _REASON_TEXT[result.reason] || result.reason || 'unrecognized companion state';
+  return {
+    name: 'Constellation companion',
+    ok: 'warn',
+    message: `${result.status} — ${why} (detected ${version}; compatible range ${result.compatibleRange}). `
+      + `Optional — install it yourself: \`${install.command}\`. `
+      + `Minions never runs it for you (see docs/constellation-bridge.md).`,
+  };
+}
+
+module.exports = {
+  COMPANION_STATUS,
+  COMPANION_COMPATIBLE_RANGE,
+  COMPANION_MIN_VERSION,
+  COMPANION_MAX_VERSION_EXCLUSIVE,
+  COMPANION_DOCS_URL,
+  isCompanionProbeEnabled,
+  resolveCompanionProbeTimeoutMs,
+  resolveCompanionHealthUrl,
+  parseCompanionVersion,
+  compareCompanionVersions,
+  isCompatibleCompanionVersion,
+  readCompanionMarker,
+  probeCompanion,
+  probeCompanionSync,
+  getCompanionInstallCommand,
+  formatCompanionLines,
+  companionDoctorResult,
+  CONSTELLATION_BRIDGE_MARKER_PATH,
+  // exported for testing
+  _fetchCompanionHealthJson: fetchCompanionHealthJson,
+};

package/engine/{content-api-validation.js → api/content-api-validation.js}

@@ -2,8 +2,8 @@
 
 const path = require('path');
 const api = require('./api-validation');
-const shared = require('./shared');
-const memoryStore = require('./memory-store');
+const shared = require('../core/shared');
+const memoryStore = require('../memory/memory-store');
 
 const LIMITS = Object.freeze({
   title: 200,

package/engine/{pr-issue-validation.js → api/pr-issue-validation.js}

@@ -2,11 +2,11 @@
 
 const path = require('path');
 const apiValidation = require('./api-validation');
-const issues = require('./issues');
-const prAction = require('./pr-action');
-const prFixTarget = require('./pr-fix-target');
-const prResolve = require('./pr-resolve');
-const shared = require('./shared');
+const issues = require('../planning/issues');
+const prAction = require('../providers/pr-action');
+const prFixTarget = require('../providers/pr-fix-target');
+const prResolve = require('../providers/pr-resolve');
+const shared = require('../core/shared');
 
 const MAX_PR_REFERENCE_LENGTH = 2048;
 const MAX_CONTEXT_LENGTH = 16 * 1024;
@@ -455,7 +455,7 @@ function validateCreatePrRequest(body, options = {}) {
   return result;
 }
 
-function validatePrObserveRequest(body) {
+function validatePrMutationTarget(body) {
   validateBody(body);
   const host = requiredString(body.host, 'host', { maxLength: 16 }).toLowerCase();
   apiValidation.validateEnum(host, {
@@ -473,6 +473,11 @@ function validatePrObserveRequest(body) {
       rejectedValue: slug,
     });
   }
+  return ref;
+}
+
+function validatePrObserveRequest(body) {
+  const ref = validatePrMutationTarget(body);
   const hasContextOnly = hasOwn(body, 'contextOnly') && body.contextOnly !== undefined;
   const hasObserve = hasOwn(body, 'observe') && body.observe !== undefined;
   const contextOnly = hasContextOnly
@@ -501,6 +506,27 @@ function validatePrObserveRequest(body) {
   };
 }
 
+function validatePrAutomationRequest(body) {
+  const ref = validatePrMutationTarget(body);
+  const automation = requiredString(body.automation, 'automation', { maxLength: 16 }).toLowerCase();
+  apiValidation.validateEnum(automation, {
+    field: 'automation',
+    values: ['fix', 'review'],
+    message: 'automation must be "fix" or "review"',
+  });
+  const enabled = apiValidation.validateBoolean(body.enabled, {
+    field: 'enabled',
+    message: 'enabled must be a boolean',
+  });
+  return {
+    host: ref.host,
+    slug: ref.slug,
+    number: ref.number,
+    automation,
+    enabled,
+  };
+}
+
 function validatePrDeleteRequest(body, options = {}) {
   validateBody(body);
   const rawId = requiredString(body.id, 'id', { maxLength: MAX_PR_REFERENCE_LENGTH });
@@ -645,6 +671,7 @@ module.exports = {
   validatePrLinkRequest,
   validateCreatePrRequest,
   validatePrObserveRequest,
+  validatePrAutomationRequest,
   validatePrDeleteRequest,
   validatePauseClearRequest,
   validateNoInputRequest,