@yemi33/minions 0.1.2197 → 0.1.2199

package/engine/pr-remote-patch.js

@@ -0,0 +1,384 @@
+/**
+ * engine/pr-remote-patch.js — Remote patch fast path (the "no validation"
+ * execution target for a projectless one-off PR fix).
+ *
+ * Plan: projectless-pr-actions, Phase 2, item P-ppa10008. The execution-target
+ * choice surface (engine/pr-fix-target.js) routes `remote-patch` here once the
+ * user has EXPLICITLY picked it (the "never clone silently" invariant lives
+ * upstream — by the time we run, the user has consented to a no-clone push).
+ *
+ * Contract (from the choice surface's description): "Trivial single-file edits
+ * only via the GitHub Contents API — no clone and NO test run. Never use for
+ * non-trivial changes." This is the deliberately fast, deliberately unsafe path:
+ * it applies ONE file edit straight through the GitHub Contents API and pushes a
+ * commit to the PR's source branch without ever cloning or running tests. Every
+ * terminal record is stamped `noValidation:true` + a human label so the UI can
+ * make the lack of validation unmistakable.
+ *
+ *   planRemotePatch(input, opts)    — resolve the PR ref + its source branch and
+ *                                     normalize/validate the single-file patch.
+ *                                     PLANNING ONLY: no network mutation.
+ *   executeRemotePatch(plan, opts)  — GET the file's current blob sha, then PUT
+ *                                     the new content via the Contents API. No
+ *                                     clone, no worktree, no tests, no cleanup.
+ *
+ * Load-bearing invariants (read before extending):
+ *  - GITHUB-ONLY: ADO has no equivalent simple "edit one file" Contents API path
+ *    without a clone, so the fast path refuses ADO refs at plan time with a clear
+ *    error (documented unsupported — use temp-clone / clone-keep for ADO).
+ *  - TRIVIAL SINGLE-FILE ONLY: the patch MUST resolve to exactly one file. A
+ *    multi-file / non-trivial patch is refused at plan time (the whole guardrail
+ *    of this target) — it never reaches the network.
+ *  - NO VALIDATION: there is no clone and no test run by design. Records carry
+ *    `validated:false`, `noValidation:true`, and `label` so the result is clearly
+ *    labeled "no validation" everywhere it surfaces.
+ *  - NO CLONE, NO CLEANUP: nothing is written to disk, so unlike temp-clone there
+ *    is no ephemeral dir to discard.
+ *  - All git/network steps are injectable seams so unit tests never hit a real
+ *    repo; the defaults are real (shellSafeGh + fetchPrBranches).
+ */
+
+const shared = require('./shared');
+const prResolve = require('./pr-resolve');
+const ghToken = require('./gh-token');
+const { PrActionError } = require('./pr-action');
+
+const GH_API_TIMEOUT_MS = 30000;
+const GH_MAX_BUFFER = 20 * 1024 * 1024; // a file blob can be large
+
+// Stamped onto every terminal record so the "no validation" nature of this path
+// is unmistakable in CC, the dashboard, and any downstream log.
+const REMOTE_PATCH_NO_VALIDATION_LABEL =
+  'no validation — applied via the GitHub Contents API with no clone and no test run';
+
+// ── Ref resolution ────────────────────────────────────────────────────────────
+
+/**
+ * Resolve `{ url }` (raw PR URL / canonical id), an already-normalized ref, or a
+ * routed plan (carrying `.ref`) into a normalized PR ref. Throws
+ * `PrActionError` (400) on missing/unrecognized input — mirrors the read-only,
+ * choice-surface, and temp-clone paths so the dashboard reflects a 400, not 500.
+ */
+function _resolveRef(input) {
+  if (input && typeof input === 'object') {
+    if (input.host && input.slug && input.number) return input; // already normalized
+    if (input.ref && input.ref.host) return input.ref;          // 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;
+}
+
+function _prId(ref) {
+  if (!ref) return null;
+  return ref.id || (ref.host && ref.slug && ref.number ? `${ref.host}:${ref.slug}#${ref.number}` : null);
+}
+
+// ── Patch normalization (the trivial-single-file guardrail) ───────────────────
+
+/**
+ * Validate a repo-relative file path for the Contents API. Rejects absolute
+ * paths, parent traversal, backslashes, and argument-injection (leading dash) so
+ * a poisoned path can neither escape the repo nor reach `gh` as a flag. Returns
+ * the normalized forward-slash path. Throws `PrActionError` (400).
+ */
+function _validateFilePath(p) {
+  const raw = typeof p === 'string' ? p.trim() : '';
+  if (!raw) throw new PrActionError('remote-patch requires a file path');
+  const norm = raw.replace(/\\/g, '/');
+  if (norm.startsWith('/')) throw new PrActionError(`remote-patch file path must be repo-relative: ${JSON.stringify(p)}`);
+  if (norm.startsWith('-')) throw new PrActionError(`invalid remote-patch file path: ${JSON.stringify(p)}`);
+  const segs = norm.split('/');
+  for (const seg of segs) {
+    if (seg === '' || seg === '.' || seg === '..') {
+      throw new PrActionError(`invalid remote-patch file path: ${JSON.stringify(p)}`);
+    }
+  }
+  return norm;
+}
+
+/**
+ * Normalize the caller-supplied patch into a single `{ path, content }` edit,
+ * enforcing the "trivial single-file only" guardrail. Accepts:
+ *   - `{ path, content }` / `{ file, content }`
+ *   - `{ files: [{ path, content }] }` (must contain exactly one)
+ *   - `[{ path, content }]` (must contain exactly one)
+ * A multi-file patch — or one missing a path/content — is REFUSED here, before
+ * any network call. `content` must be a string (the file's full new contents).
+ * Throws `PrActionError` (400).
+ */
+function _normalizePatch(patch) {
+  if (patch == null) {
+    throw new PrActionError('remote-patch requires a single-file patch (opts.patch { path, content })');
+  }
+  // Collapse the accepted shapes into a list of file edits.
+  let files;
+  if (Array.isArray(patch)) {
+    files = patch;
+  } else if (Array.isArray(patch.files)) {
+    files = patch.files;
+  } else if (typeof patch === 'object') {
+    files = [patch];
+  } else {
+    throw new PrActionError('remote-patch requires a single-file patch (opts.patch { path, content })');
+  }
+
+  if (files.length === 0) {
+    throw new PrActionError('remote-patch requires a single-file patch (opts.patch { path, content })');
+  }
+  if (files.length > 1) {
+    throw new PrActionError(
+      `remote-patch is single-file only (got ${files.length} files). Use temp-clone or clone-keep for multi-file changes.`,
+    );
+  }
+
+  const file = files[0] || {};
+  const path = _validateFilePath(file.path != null ? file.path : file.file);
+  if (typeof file.content !== 'string') {
+    throw new PrActionError('remote-patch file requires string `content` (the full new file contents)');
+  }
+  return { path, content: file.content };
+}
+
+// ── Planning ──────────────────────────────────────────────────────────────────
+
+/**
+ * Plan a remote-patch fix: resolve the PR ref (GitHub only), resolve its source
+ * branch, and normalize/validate the single-file patch. NOTHING is mutated here.
+ *
+ * `input` — `{ url }`, a normalized ref, or a routed plan from
+ *   engine/pr-fix-target.js#resolvePrFixTarget.
+ * `opts.patch` — REQUIRED single-file patch (see `_normalizePatch`).
+ * `opts.fetchPrBranches` — override the branch fetch (test seam).
+ * `opts.prUrl` — original user URL (preferred for surfacing).
+ * `opts.message` — optional commit message override.
+ *
+ * Returns `{ status:'remote-patch-planned', target:'remote-patch', ref, prId,
+ *   prUrl, host:'github', slug, sourceBranch, file:{ path, content }, message,
+ *   validates:false, noValidation:true, label }`.
+ * Throws `PrActionError` (400) on bad input / ADO host / multi-file patch.
+ */
+async function planRemotePatch(input = {}, opts = {}) {
+  const ref = _resolveRef(input);
+  const prUrl = opts.prUrl || (input && typeof input === 'object' ? input.url : undefined) || null;
+  const prId = _prId(ref);
+
+  // GITHUB-ONLY guardrail. ADO has no simple Contents-API edit-one-file path
+  // without a clone, so the fast path is explicitly unsupported there.
+  if (ref.host !== 'github') {
+    throw new PrActionError(
+      `remote-patch fast path is GitHub-only — ${ref.host} has no equivalent no-clone Contents API. ` +
+      'Use temp-clone or clone-keep for this PR.',
+    );
+  }
+
+  // Validate the single-file patch BEFORE any network — the trivial-only guardrail.
+  const file = _normalizePatch(opts.patch);
+
+  const slug = shared.validateGhSlug(ref.slug);
+
+  const fetchBranches = opts.fetchPrBranches || prResolve.fetchPrBranches;
+  const branches = await fetchBranches(ref, opts);
+  const sourceBranch = branches && branches.sourceBranch;
+  if (!sourceBranch) throw new PrActionError(`could not resolve source branch for ${prId || 'PR'}`, 502);
+  // Defensive re-validation (fetchPrBranches already validates, but a custom seam
+  // might not) — a poisoned ref name must never reach the Contents API.
+  shared.validateGitRef(sourceBranch);
+
+  const message = (typeof opts.message === 'string' && opts.message.trim())
+    ? opts.message.trim()
+    : `Fix ${prId || sourceBranch}: ${file.path}`;
+
+  return {
+    status: 'remote-patch-planned',
+    target: 'remote-patch',
+    ref,
+    prId,
+    prUrl,
+    host: 'github',
+    slug,
+    sourceBranch,
+    file,
+    message,
+    validates: false,
+    noValidation: true,
+    label: REMOTE_PATCH_NO_VALIDATION_LABEL,
+  };
+}
+
+// ── Default GitHub seams (real implementations; tests inject their own) ─────────
+
+/** Resolve a GitHub PAT for the PR's slug (per-slug routing; never gh auth switch). */
+function _resolveToken(plan, opts = {}) {
+  if (opts.token) return opts.token;
+  const resolve = opts._resolveTokenForSlug || ghToken.resolveTokenForSlug;
+  return resolve(plan.slug || plan.ref.slug) || null;
+}
+
+function _ghOpts(token) {
+  const env = token ? { ...process.env, GH_TOKEN: token } : process.env;
+  return { env, timeout: GH_API_TIMEOUT_MS, maxBuffer: GH_MAX_BUFFER };
+}
+
+/**
+ * Fetch the current blob sha for the file on the PR's source branch, or null if
+ * the file does not exist yet (a new-file create). Re-throws on any other error
+ * so a transient API failure is not silently treated as "create".
+ */
+async function _defaultGetFileSha(plan, token, opts = {}) {
+  const runGh = opts._shellSafeGh || shared.shellSafeGh;
+  try {
+    const raw = await runGh(
+      ['api', `repos/${plan.slug}/contents/${plan.file.path}`, '-f', `ref=${plan.sourceBranch}`],
+      _ghOpts(token),
+    );
+    const parsed = JSON.parse(raw);
+    return parsed && parsed.sha ? String(parsed.sha) : null;
+  } catch (e) {
+    // 404 → the file does not exist on the branch yet; treat as a create.
+    if (/404|Not Found|No such file/i.test(e?.message || '')) return null;
+    throw e;
+  }
+}
+
+/**
+ * Apply the single-file edit via the Contents API (PUT). Passing `sha` updates an
+ * existing file; omitting it creates a new one. Returns `{ commitSha, htmlUrl }`.
+ */
+async function _defaultPutFile(plan, token, sha, opts = {}) {
+  const runGh = opts._shellSafeGh || shared.shellSafeGh;
+  const contentB64 = Buffer.from(plan.file.content, 'utf8').toString('base64');
+  const args = [
+    'api', '--method', 'PUT', `repos/${plan.slug}/contents/${plan.file.path}`,
+    '-f', `message=${plan.message}`,
+    '-f', `content=${contentB64}`,
+    '-f', `branch=${plan.sourceBranch}`,
+  ];
+  if (sha) args.push('-f', `sha=${sha}`);
+  const raw = await runGh(args, _ghOpts(token));
+  let parsed = null;
+  try { parsed = JSON.parse(raw); } catch { /* gh returned non-JSON; tolerate */ }
+  return {
+    commitSha: parsed?.commit?.sha || null,
+    htmlUrl: parsed?.commit?.html_url || parsed?.content?.html_url || null,
+  };
+}
+
+// ── Execution ─────────────────────────────────────────────────────────────────
+
+function _record(plan, fields) {
+  return {
+    status: 'failed',
+    target: 'remote-patch',
+    ref: plan.ref,
+    prId: plan.prId,
+    prUrl: plan.prUrl,
+    sourceBranch: plan.sourceBranch || null,
+    file: plan.file ? { path: plan.file.path } : null,
+    changed: false,
+    validated: false,      // remote-patch NEVER validates
+    validationOk: null,
+    noValidation: true,
+    label: REMOTE_PATCH_NO_VALIDATION_LABEL,
+    pushed: false,
+    created: false,
+    commit: null,
+    output: '',
+    failure_class: null,
+    retryable: false,
+    error: null,
+    ...fields,
+  };
+}
+
+/**
+ * Execute the remote-patch fast path for a planned (or raw) PR fix: resolve a
+ * GitHub token, fetch the file's current blob sha, then PUT the new content to
+ * the PR's source branch via the Contents API. NO clone, NO worktree, NO tests.
+ *
+ * `planOrInput` — a plan from `planRemotePatch`, a routed plan from
+ *   pr-fix-target.js, a normalized ref, or `{ url }` (the patch must then come
+ *   via `opts.patch`).
+ * `opts`:
+ *   - `patch` — REQUIRED when `planOrInput` is not already a built plan.
+ *   - test seams: `getFileSha`, `putFile`, `fetchPrBranches`,
+ *     `token`/`_resolveTokenForSlug`, `_shellSafeGh`.
+ *
+ * Returns a terminal record stamped `noValidation:true` + `label`. Throws
+ * `PrActionError` (400) only for bad input / ADO host / multi-file patch; every
+ * downstream (token/network) failure is captured in a `failed` record.
+ */
+async function executeRemotePatch(planOrInput = {}, opts = {}) {
+  // Accept an already-built plan, else plan now (resolves branch + validates the
+  // single-file patch). PrActionError(400) on bad input / ADO host / multi-file
+  // propagates so the endpoint reflects a 400.
+  let plan;
+  if (planOrInput && planOrInput.status === 'remote-patch-planned' && planOrInput.file) {
+    plan = planOrInput;
+  } else {
+    plan = await planRemotePatch(planOrInput, opts);
+  }
+
+  const getFileSha = opts.getFileSha || ((p, token) => _defaultGetFileSha(p, token, opts));
+  const putFile = opts.putFile || ((p, token, sha) => _defaultPutFile(p, token, sha, opts));
+
+  const rec = _record(plan, {});
+
+  // 1) Resolve the push token for the target repo.
+  const token = _resolveToken(plan, opts);
+  if (!token) {
+    rec.failure_class = shared.FAILURE_CLASS.AUTH;
+    rec.retryable = false;
+    rec.error = `no GitHub token resolved for ${plan.slug}`;
+    return rec;
+  }
+
+  // 2) Look up the file's current blob sha (null → new-file create).
+  let sha;
+  try {
+    sha = await getFileSha(plan, token);
+  } catch (e) {
+    rec.failure_class = shared.FAILURE_CLASS.NETWORK_ERROR;
+    rec.retryable = true;
+    rec.error = `contents lookup failed: ${e?.message || e}`;
+    return rec;
+  }
+  rec.created = !sha;
+
+  // 3) Apply the single-file edit via the Contents API.
+  let result;
+  try {
+    result = await putFile(plan, token, sha);
+  } catch (e) {
+    // A 4xx (perms/branch protection) reads as auth; other failures as network.
+    const auth = /403|401|Permission|protected branch|Resource not accessible/i.test(e?.message || '');
+    rec.failure_class = auth ? shared.FAILURE_CLASS.AUTH : shared.FAILURE_CLASS.NETWORK_ERROR;
+    rec.retryable = !auth;
+    rec.error = `remote patch failed: ${e?.message || e}`;
+    return rec;
+  }
+
+  rec.status = 'done';
+  rec.changed = true;
+  rec.pushed = true;
+  rec.commit = result || null;
+  rec.failure_class = null;
+  rec.retryable = false;
+  rec.error = null;
+  rec.output = `Applied single-file patch to ${plan.file.path} on ${plan.sourceBranch} (${REMOTE_PATCH_NO_VALIDATION_LABEL}).`;
+  return rec;
+}
+
+module.exports = {
+  REMOTE_PATCH_NO_VALIDATION_LABEL,
+  planRemotePatch,
+  executeRemotePatch,
+  // Exported for testing.
+  _resolveRef,
+  _validateFilePath,
+  _normalizePatch,
+};