@yemi33/minions 0.1.2197 → 0.1.2198

package/engine/pr-fix-target-store.js

@@ -0,0 +1,123 @@
+// engine/pr-fix-target-store.js — SQL-backed remembered execution-target
+// choices, keyed per repo scope.
+//
+// Plan: projectless-pr-actions, Phase 3, item P-ppa10009 — "Remember
+// execution-target choice per repo (optional)". One row per canonical PR scope
+// (github:owner/repo / ado:org/proj/repo) in the pr_fix_target_prefs table
+// (migration 014). When a remembered choice exists, a repeat fix on that repo
+// skips the execution-target prompt and routes straight to the executor
+// (engine/pr-fix-target.js#planPrFix consults getRemembered). Absence of a row
+// still prompts — the safe "never clone silently" default.
+//
+// Mirrors the shape of engine/steering-store.js:
+//   - routes every read/write through getDb() (no JSON sidecar)
+//   - emits emitStateEvent('pr-fix-target-prefs', {repoScope, target}) on every
+//     write/clear so the dashboard's MAX(events.id) cache check fires.
+//
+// Public API:
+//   remember(repoScope, target)  -> { repoScope, target, updatedAt } (upsert)
+//   getRemembered(repoScope)     -> target string | null
+//   getRecord(repoScope)         -> { repoScope, target, updatedAt } | null
+//   clear(repoScope)             -> boolean (true if a row was removed)
+//   list()                       -> [{ repoScope, target, updatedAt }, ...]
+
+function _normScope(repoScope) {
+  return typeof repoScope === 'string' ? repoScope.trim().toLowerCase() : '';
+}
+
+function _isValidTarget(target) {
+  // Validate against the canonical execution-target list. Lazy require avoids a
+  // load-time cycle (pr-fix-target.js requires this store at module top).
+  try {
+    const { isValidExecutionTarget } = require('./pr-fix-target');
+    return isValidExecutionTarget(target);
+  } catch {
+    // If pr-fix-target can't load (shouldn't happen), fall back to a minimal
+    // shape check so we still refuse obvious garbage.
+    return typeof target === 'string' && target.trim().length > 0;
+  }
+}
+
+function _rowToRecord(row) {
+  if (!row) return null;
+  return { repoScope: row.repo_scope, target: row.target, updatedAt: row.updated_at };
+}
+
+function _emitEvent(repoScope, target) {
+  try {
+    const { emitStateEvent } = require('./db-events');
+    emitStateEvent('pr-fix-target-prefs', { repoScope, target: target || null });
+  } catch { /* best-effort */ }
+}
+
+/**
+ * Remember (upsert) the execution-target `target` for `repoScope`. Validates the
+ * target against the canonical execution-target list and throws on an invalid
+ * scope/target so a bad value can never silently route a future clone.
+ */
+function remember(repoScope, target) {
+  const scope = _normScope(repoScope);
+  if (!scope) throw new Error('pr-fix-target-store.remember: repoScope required');
+  const t = typeof target === 'string' ? target.trim().toLowerCase() : '';
+  if (!_isValidTarget(t)) {
+    throw new Error(`pr-fix-target-store.remember: invalid execution target ${JSON.stringify(target)}`);
+  }
+
+  const { getDb } = require('./db');
+  const db = getDb();
+  const now = Date.now();
+  db.prepare(`
+    INSERT INTO pr_fix_target_prefs (repo_scope, target, updated_at)
+    VALUES (?, ?, ?)
+    ON CONFLICT(repo_scope) DO UPDATE SET target = excluded.target, updated_at = excluded.updated_at
+  `).run(scope, t, now);
+
+  _emitEvent(scope, t);
+  return { repoScope: scope, target: t, updatedAt: now };
+}
+
+/** The remembered execution-target id for `repoScope`, or null when none. */
+function getRemembered(repoScope) {
+  const rec = getRecord(repoScope);
+  return rec ? rec.target : null;
+}
+
+/** The full remembered record for `repoScope`, or null when none. */
+function getRecord(repoScope) {
+  const scope = _normScope(repoScope);
+  if (!scope) return null;
+  let db;
+  try { const { getDb } = require('./db'); db = getDb(); }
+  catch { return null; }
+  const row = db.prepare('SELECT * FROM pr_fix_target_prefs WHERE repo_scope = ?').get(scope);
+  return _rowToRecord(row);
+}
+
+/** Forget the remembered choice for `repoScope`. Returns true if a row existed. */
+function clear(repoScope) {
+  const scope = _normScope(repoScope);
+  if (!scope) return false;
+  const { getDb } = require('./db');
+  const db = getDb();
+  const info = db.prepare('DELETE FROM pr_fix_target_prefs WHERE repo_scope = ?').run(scope);
+  const removed = (info && info.changes) > 0;
+  if (removed) _emitEvent(scope, null);
+  return removed;
+}
+
+/** All remembered choices, newest-updated first. */
+function list() {
+  let db;
+  try { const { getDb } = require('./db'); db = getDb(); }
+  catch { return []; }
+  const rows = db.prepare('SELECT * FROM pr_fix_target_prefs ORDER BY updated_at DESC, repo_scope ASC').all();
+  return rows.map(_rowToRecord);
+}
+
+module.exports = {
+  remember,
+  getRemembered,
+  getRecord,
+  clear,
+  list,
+};

package/engine/pr-fix-target.js

@@ -0,0 +1,418 @@
+/**
+ * engine/pr-fix-target.js — Execution-target choice surface for projectless PR
+ * fixes ("never clone silently").
+ *
+ * Plan: projectless-pr-actions, Phase 2, item P-ppa10005. This module is the
+ * DECISION / ROUTING surface + the state machine that PAUSES a one-off fix on an
+ * unconfigured repo until the user explicitly picks an execution target. It does
+ * NOT execute anything — the executors land in:
+ *   - temp-clone   → P-ppa10006 (ephemeral clone, fix, push, discard) [DEFAULT]
+ *                    — IMPLEMENTED in engine/pr-temp-clone.js
+ *   - clone-keep   → P-ppa10007 (auto-clone + persistent project registration)
+ *                    — IMPLEMENTED in engine/pr-clone-keep.js
+ *   - remote-patch → P-ppa10008 (GitHub Contents API, trivial single-file, NO test run)
+ *                    — IMPLEMENTED in engine/pr-remote-patch.js
+ *   - devbox       → P-ppa10011 (ephemeral clone+fix+push ON A DEVBOX, zero local
+ *                    footprint) — IMPLEMENTED in engine/pr-devbox.js. Never default,
+ *                    never auto-selected; explicit consent only.
+ *
+ * Load-bearing invariant (read before extending): "never clone silently". A fix
+ * on a repo that is NOT already a configured project MUST surface the
+ * clone-vs-temp-vs-remote-patch choice and pause — no clone, no worktree, no
+ * spawn happens here. This module therefore imports ZERO clone/worktree/spawn
+ * primitive on purpose; a test source-inspection guard enforces that. If the
+ * repo IS already a configured project, the choice is skipped and the plan
+ * routes straight to the existing project fix path.
+ *
+ * State machine (`planPrFix` → `resolvePrFixTarget`):
+ *   project-ready          — repo matches a configured project; skip the prompt,
+ *                            use the existing project worktree/fix path.
+ *   awaiting-target-choice — repo is unconfigured; the user must choose a target
+ *                            before any clone. Carries CC prompt + dashboard modal.
+ *   routed                 — a valid target was chosen; carries the routing intent
+ *                            to the matching executor (implemented:false until the
+ *                            P-ppa10006/7/8 executors land).
+ */
+
+const shared = require('./shared');
+const prResolve = require('./pr-resolve');
+const { PrActionError } = require('./pr-action');
+const prFixTargetStore = require('./pr-fix-target-store');
+
+// ── Execution targets ─────────────────────────────────────────────────────────
+
+// The three explicit execution targets a user can pick when a fix is requested
+// on an unconfigured repo. Order is the presentation order (CC + dashboard).
+// `validates` flags whether the target runs the build/tests before pushing —
+// remote-patch deliberately does NOT (it is labeled "no validation").
+const EXECUTION_TARGETS = Object.freeze([
+  Object.freeze({
+    id: 'clone-keep',
+    label: 'Clone & keep',
+    description: 'Auto-clone the repo and register it as a persistent project so ongoing tracking/auto-fix works. Disk-resident.',
+    isDefault: false,
+    executorItem: 'P-ppa10007',
+    executorModule: 'pr-clone-keep',
+    implemented: true,
+    trivialOnly: false,
+    validates: true,
+  }),
+  Object.freeze({
+    id: 'temp-clone',
+    label: 'Temp clone',
+    description: 'Ephemeral clone on D:, fix + run tests, push to the PR branch, then discard. Nothing persists.',
+    isDefault: true,
+    executorItem: 'P-ppa10006',
+    executorModule: 'pr-temp-clone',
+    implemented: true,
+    trivialOnly: false,
+    validates: true,
+  }),
+  Object.freeze({
+    id: 'remote-patch',
+    label: 'Remote patch (no validation)',
+    description: 'Trivial single-file edits only via the GitHub Contents API — no clone and NO test run. Never use for non-trivial changes.',
+    isDefault: false,
+    executorItem: 'P-ppa10008',
+    executorModule: 'pr-remote-patch',
+    implemented: true,
+    trivialOnly: true,
+    validates: false,
+  }),
+  Object.freeze({
+    id: 'devbox',
+    label: 'DevBox (never touches your machine)',
+    description: 'Clone ephemerally ON A DEVBOX, run the fix + tests there, push from the DevBox, then discard. Zero local footprint — the answer for high PR volume. Never auto-selected.',
+    isDefault: false,
+    executorItem: 'P-ppa10011',
+    executorModule: 'pr-devbox',
+    implemented: true,
+    trivialOnly: false,
+    validates: true,
+  }),
+]);
+
+const EXECUTION_TARGET_IDS = Object.freeze(EXECUTION_TARGETS.map((t) => t.id));
+
+// Default execution target when the user does not specify one. Temp clone is the
+// safest "do the work, leave no trace" option, so it is the plan's default.
+const DEFAULT_EXECUTION_TARGET = (EXECUTION_TARGETS.find((t) => t.isDefault) || EXECUTION_TARGETS[1]).id;
+
+function isValidExecutionTarget(target) {
+  return typeof target === 'string' && EXECUTION_TARGET_IDS.includes(target);
+}
+
+function _targetById(id) {
+  return EXECUTION_TARGETS.find((t) => t.id === id) || null;
+}
+
+/**
+ * Build the `{ status:'routed', … }` routing intent for a planned fix + a chosen
+ * target. Shared by `resolvePrFixTarget` (explicit choice) and `planPrFix` (when
+ * a remembered per-repo choice short-circuits the prompt). Still does NOT clone
+ * or spawn — selection only routes.
+ */
+function _routedRecord(plan, target, extra = {}) {
+  const desc = _targetById(target);
+  return {
+    status: 'routed',
+    ref: plan.ref,
+    prId: plan.prId,
+    prUrl: plan.prUrl,
+    target,
+    executor: {
+      target,
+      item: desc.executorItem,
+      module: desc.executorModule || null,
+      validates: desc.validates,
+      trivialOnly: desc.trivialOnly,
+      // temp-clone's executor landed in P-ppa10006 (engine/pr-temp-clone.js),
+      // clone-keep's in P-ppa10007 (engine/pr-clone-keep.js), and remote-patch's
+      // in P-ppa10008 (engine/pr-remote-patch.js). `implemented` reflects whether
+      // a real executor backs the choice.
+      implemented: !!desc.implemented,
+    },
+    ...extra,
+  };
+}
+
+// ── PR ref resolution ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve `{ url }` (raw PR URL / canonical id) OR an already-normalized ref into
+ * a normalized PR ref. Throws `PrActionError` (400) on missing/unrecognized input
+ * so the dashboard handler reflects it as a 400 (matching the read-only path).
+ */
+function _resolveRef(input) {
+  if (input && typeof input === 'object' && input.host && input.slug && input.number) {
+    return input; // already normalized
+  }
+  if (input && typeof input === 'object' && input.ref && input.ref.host) {
+    return input.ref; // a plan/handle carrying a ref
+  }
+  const rawUrl = input && typeof input === 'object'
+    ? (typeof input.url === 'string' ? input.url.trim() : '')
+    : (typeof input === 'string' ? input.trim() : '');
+  if (!rawUrl) throw new PrActionError('url required');
+  const ref = prResolve.normalizePrRef(rawUrl);
+  if (!ref) throw new PrActionError(`unrecognized PR reference: ${JSON.stringify(rawUrl.slice(0, 120))}`);
+  return ref;
+}
+
+// ── Configured-project detection ──────────────────────────────────────────────
+
+/** Canonical `host:slug` scope for a normalized ref (lowercased), or ''. */
+function _refScope(ref) {
+  if (!ref) return '';
+  if (ref.scope) return String(ref.scope).toLowerCase();
+  if (ref.host && ref.slug) return `${ref.host}:${ref.slug}`.toLowerCase();
+  return '';
+}
+
+/**
+ * Find the configured project whose repo matches the PR `ref`, or null when the
+ * repo is NOT already a configured project. Match is by canonical PR scope
+ * (`github:owner/repo` / `ado:org/proj/repo`); for ADO it also accepts the
+ * repositoryId (GUID) form via `shared.isAdoPrScopeCompatible`.
+ *
+ * Importantly, a project with no derivable scope NEVER matches — we must not
+ * treat "scope unknown" as "compatible", or an unconfigured repo could slip past
+ * the choice surface and clone silently.
+ */
+function findConfiguredProjectForRef(ref, config) {
+  const refScope = _refScope(ref);
+  if (!refScope) return null;
+  const projects = shared.getProjects(config) || [];
+  for (const project of projects) {
+    const projectScope = shared.getProjectPrScope(project);
+    if (projectScope && projectScope.toLowerCase() === refScope) return project;
+    if (ref && ref.host === 'ado' && shared.isAdoPrScopeCompatible(refScope, project)) return project;
+  }
+  return null;
+}
+
+// ── Remembered execution-target choice (per repo) ─────────────────────────────
+//
+// P-ppa10009: optionally remember the user's execution-target pick keyed by repo
+// scope so a repeat fix on the same repo doesn't re-prompt. Persisted SQL-first
+// via engine/pr-fix-target-store.js. Absence of a remembered choice still
+// prompts — the safe "never clone silently" default is preserved.
+
+/** The remembered execution-target id for a ref's repo scope, or null. */
+function getRememberedTargetForRef(ref) {
+  const scope = _refScope(ref);
+  if (!scope) return null;
+  let target;
+  try { target = prFixTargetStore.getRemembered(scope); }
+  catch { return null; }
+  // A stale/invalid remembered value must never route a clone — ignore it.
+  return isValidExecutionTarget(target) ? target : null;
+}
+
+/** Remember `target` for a ref's repo scope. Throws on invalid scope/target. */
+function rememberTargetForRef(ref, target) {
+  const scope = _refScope(ref);
+  if (!scope) throw new PrActionError('cannot remember choice: PR ref has no resolvable repo scope');
+  if (!isValidExecutionTarget(target)) {
+    throw new PrActionError(
+      `unknown execution target: ${JSON.stringify(target)}. Valid targets: ${EXECUTION_TARGET_IDS.join(', ')}`,
+    );
+  }
+  return prFixTargetStore.remember(scope, target);
+}
+
+/** Forget the remembered choice for a ref's repo scope. Returns true if cleared. */
+function clearRememberedTargetForRef(ref) {
+  const scope = _refScope(ref);
+  if (!scope) return false;
+  try { return prFixTargetStore.clear(scope); }
+  catch { return false; }
+}
+
+// ── Choice surfaces (CC prompt + dashboard modal) ─────────────────────────────
+
+/** Plain target descriptors for a UI to render (id/label/description/default/...). */
+function _targetOptions() {
+  return EXECUTION_TARGETS.map((t) => ({
+    id: t.id,
+    label: t.label,
+    description: t.description,
+    isDefault: t.id === DEFAULT_EXECUTION_TARGET,
+    trivialOnly: t.trivialOnly,
+    validates: t.validates,
+  }));
+}
+
+/**
+ * The Command Center text presenting the execution-target choice. CC shows this
+ * verbatim so the user picks a target before any clone happens.
+ */
+function buildPrFixTargetPrompt(plan) {
+  const prId = (plan && (plan.prId || (plan.ref && plan.ref.id))) || 'this pull request';
+  const lines = [
+    `Fixing ${prId} needs a checkout, but its repo is not a configured project.`,
+    'Choose an execution target before anything is cloned (nothing is cloned until you pick):',
+    '',
+  ];
+  for (const t of EXECUTION_TARGETS) {
+    const tag = t.id === DEFAULT_EXECUTION_TARGET ? ' [default]' : (t.trivialOnly ? ' [trivial only]' : '');
+    lines.push(`- ${t.label}${tag} — ${t.description}`);
+  }
+  lines.push('');
+  lines.push(`Reply with one of: ${EXECUTION_TARGET_IDS.join(', ')} (default: ${DEFAULT_EXECUTION_TARGET}).`);
+  return lines.join('\n');
+}
+
+/**
+ * A dashboard modal descriptor for the execution-target choice. Shape kept thin
+ * and serializable so the dashboard renders it without bespoke parsing.
+ */
+function buildPrFixTargetModal(plan) {
+  return {
+    kind: 'pr-fix-target-choice',
+    title: 'Choose execution target',
+    prId: (plan && plan.prId) || (plan && plan.ref && plan.ref.id) || null,
+    prUrl: (plan && plan.prUrl) || null,
+    message: 'This PR’s repo is not a configured project. Pick how to run the fix — nothing is cloned until you choose.',
+    options: _targetOptions(),
+    default: DEFAULT_EXECUTION_TARGET,
+  };
+}
+
+// ── State machine ─────────────────────────────────────────────────────────────
+
+/**
+ * Plan a one-off fix for a PR. The decision/routing entry point.
+ *
+ * `input` — `{ url }` (raw PR URL / canonical id) or an already-normalized ref.
+ * `opts.config` — full config (for configured-project detection).
+ * `opts.prUrl` — original user-supplied URL (preferred in the surfaces).
+ *
+ * Returns one of:
+ *   - `{ status:'project-ready', ref, prId, project, projectName, target:'project' }`
+ *     when the repo IS already a configured project — skip the prompt, use the
+ *     existing project fix path. No clone needed (the project already has a
+ *     worktree/checkout path).
+ *   - `{ status:'routed', ref, prId, prUrl, target, executor, fromRemembered:true,
+ *        rememberedTarget }` when the repo is unconfigured BUT the user has a
+ *     remembered per-repo choice (P-ppa10009) — skip the prompt and route
+ *     straight to the executor. Still NOTHING is cloned here; the caller invokes
+ *     the executor. Pass `opts.ignoreRemembered:true` to force the prompt anyway
+ *     (override path).
+ *   - `{ status:'awaiting-target-choice', ref, prId, prUrl, options, default,
+ *        prompt, modal }` when the repo is unconfigured and no remembered choice
+ *     applies — PAUSE for the user. NOTHING is cloned here; that is the whole
+ *     point of this item.
+ *
+ * Throws `PrActionError` (400) on bad input.
+ */
+function planPrFix(input = {}, opts = {}) {
+  const ref = _resolveRef(input);
+  const prUrl = opts.prUrl || (input && typeof input === 'object' ? input.url : undefined) || null;
+  const prId = ref.id || (ref.host && ref.slug && ref.number ? `${ref.host}:${ref.slug}#${ref.number}` : null);
+
+  const project = findConfiguredProjectForRef(ref, opts.config);
+  if (project) {
+    return {
+      status: 'project-ready',
+      ref,
+      prId,
+      prUrl,
+      target: 'project',
+      project,
+      projectName: project.name || null,
+    };
+  }
+
+  const plan = { status: 'awaiting-target-choice', ref, prId, prUrl };
+
+  // P-ppa10009: a remembered per-repo choice skips the prompt on subsequent
+  // fixes for that repo. Absence of one still prompts (the safe default) — and an
+  // explicit override can force the prompt via opts.ignoreRemembered.
+  if (!opts.ignoreRemembered) {
+    const remembered = getRememberedTargetForRef(ref);
+    if (remembered) {
+      return _routedRecord(plan, remembered, { fromRemembered: true, rememberedTarget: remembered });
+    }
+  }
+
+  return {
+    ...plan,
+    options: _targetOptions(),
+    default: DEFAULT_EXECUTION_TARGET,
+    prompt: buildPrFixTargetPrompt(plan),
+    modal: buildPrFixTargetModal(plan),
+  };
+}
+
+/**
+ * Resolve an execution-target choice for a planned fix. The second half of the
+ * state machine: takes a plan (or raw `{ url }`) plus the user's `choice` and
+ * returns the routing intent to the matching executor.
+ *
+ * IMPORTANT: this still does NOT clone or spawn — selection only routes. The
+ * returned `routed` record carries `executor.implemented` (true once a real
+ * executor backs the choice: temp-clone → engine/pr-temp-clone.js; clone-keep →
+ * engine/pr-clone-keep.js; remote-patch → engine/pr-remote-patch.js). The caller is
+ * responsible for invoking the executor; this surface never clones, keeping
+ * "never clone silently" absolute.
+ *
+ * `planOrInput` — a plan from `planPrFix`, an already-normalized ref, or `{ url }`.
+ * `choice` — one of EXECUTION_TARGET_IDS.
+ * `opts.config` — full config (re-checks configured-project so a stale plan can't
+ *   force a clone choice on a repo that is actually a project).
+ * `opts.remember` — when true, persist this choice for the repo scope so future
+ *   fixes skip the prompt (P-ppa10009). No-op for a configured project (moot).
+ *
+ * Returns:
+ *   - `{ status:'project-ready', ... }` — repo is a configured project; the
+ *     target choice is moot, route to the existing project fix path.
+ *   - `{ status:'routed', ref, prId, prUrl, target, executor, remembered? }` —
+ *     valid choice. `remembered:true` when opts.remember persisted the choice.
+ *
+ * Throws `PrActionError` (400) on missing/invalid choice or bad input.
+ */
+function resolvePrFixTarget(planOrInput = {}, choice, opts = {}) {
+  // Re-derive the plan from current config so a stale awaiting-choice plan can't
+  // route a clone for a repo that has since become a configured project. Ignore
+  // any remembered choice here — the caller is supplying an explicit one.
+  const refInput = planOrInput && planOrInput.ref ? planOrInput.ref : planOrInput;
+  const plan = planPrFix(refInput, {
+    config: opts.config,
+    prUrl: (planOrInput && planOrInput.prUrl) || opts.prUrl,
+    ignoreRemembered: true,
+  });
+
+  if (plan.status === 'project-ready') return plan; // choice is moot — use project path
+
+  const target = typeof choice === 'string' ? choice.trim().toLowerCase() : '';
+  if (!target) throw new PrActionError('execution target required');
+  if (!isValidExecutionTarget(target)) {
+    throw new PrActionError(
+      `unknown execution target: ${JSON.stringify(choice)}. Valid targets: ${EXECUTION_TARGET_IDS.join(', ')}`,
+    );
+  }
+
+  let remembered = false;
+  if (opts.remember) {
+    try { rememberTargetForRef(plan.ref, target); remembered = true; }
+    catch { /* persistence is best-effort — never block the fix on a store error */ }
+  }
+
+  return _routedRecord(plan, target, remembered ? { remembered: true } : {});
+}
+
+module.exports = {
+  EXECUTION_TARGETS,
+  EXECUTION_TARGET_IDS,
+  DEFAULT_EXECUTION_TARGET,
+  isValidExecutionTarget,
+  findConfiguredProjectForRef,
+  planPrFix,
+  resolvePrFixTarget,
+  buildPrFixTargetPrompt,
+  buildPrFixTargetModal,
+  getRememberedTargetForRef,
+  rememberTargetForRef,
+  clearRememberedTargetForRef,
+};