@yemi33/minions 0.1.2447 → 0.1.2449

package/watch-plugins/gh-author-prs.js

@@ -0,0 +1,375 @@
+/**
+ * watch-plugins/gh-author-prs.js — Watch a GitHub repo for open PRs by author
+ *
+ * Use case: surface an external collaborator's PRs for context-only tracking
+ * and review dispatch without adding them to the engine's PR sync loops.
+ *
+ * ── Target syntax ───────────────────────────────────────────────────────────
+ *   target: 'owner/repo:author'
+ *     → bare colon-delimited string. Authentication resolves from
+ *       config.engine.ghAccounts for the repository owner.
+ *
+ *   target: { slug: 'owner/repo', author: 'login', ghAccount?: 'account' }
+ *     → explicit form; ghAccount optionally overrides configured account
+ *       resolution for this watch.
+ *
+ * ── Conditions ──────────────────────────────────────────────────────────────
+ *   new-pr — fires once per newly-observed open PR number. Drafts are
+ *            ignored (they aren't "new-PR-ready"). The watch state retains
+ *            an all-time-seen set, so closing + reopening the same PR does
+ *            NOT re-fire — manually re-review reopens.
+ *
+ * Burst handling: when N new PRs land between ticks, the plugin advances
+ * its seen-set by exactly ONE per evaluation. The watch fires once per
+ * tick until the backlog drains — zero PRs are lost when several arrive in
+ * the same interval. Costs one watch tick per PR to drain.
+ *
+ * ── Templating vars exposed to actions ──────────────────────────────────────
+ *   {{prNumber}}, {{prTitle}}, {{prUrl}}, {{prBranch}}, {{prAuthor}},
+ *   {{prHeadSha}}, {{prCreatedAt}}, {{prIsDraft}}, {{repoSlug}},
+ *   {{ghAccount}}
+ * Plus standard watch vars (target, condition, watchId, message, …).
+ *
+ * ── Fetch model ─────────────────────────────────────────────────────────────
+ * The engine's checkWatches loop is synchronous and runs inside a
+ * mutateJsonFileLocked callback, so this plugin maintains its own
+ * background-fetch cache. `fetchEntity` is sync: it returns the cached
+ * entity and, when the cached value is older than 60s (or absent), kicks
+ * off a background `gh pr list` refresh. First tick after a watch is
+ * created therefore returns null (no entity yet); second tick captures
+ * the baseline; subsequent ticks detect new PRs.
+ *
+ * Tests can short-circuit this entirely by passing a pre-populated map at
+ * `state.ghAuthorPrs[targetKey]` (see `_targetKey`) — the plugin uses
+ * that shape directly, no shell-out required. Tests can also override
+ * the underlying lister via `setLister(fn)` to drive the cache path.
+ *
+ * Auth: engine/providers/gh-token.js resolves the configured account. Token acquisition
+ * stays asynchronous and is cached in-process. NEVER `gh auth switch` — that
+ * races with engine pollers.
+ *
+ * Security: token is passed to `gh pr list` via the child process `env`
+ * map only — it never appears on argv, never in logs, never written to
+ * disk. Plugin trust level matches playbooks (user-trusted).
+ */
+
+const { spawn } = require('child_process');
+const ghToken = require('../engine/providers/gh-token');
+
+function ts() { return new Date().toISOString(); }
+function _warn(msg) { try { console.warn(`[${ts()}] [warn] ${msg}`); } catch {} }
+function _info(msg) { try { console.log(`[${ts()}] [info] ${msg}`); } catch {} }
+
+const CACHE_FRESHNESS_MS = 60 * 1000;
+const TOKEN_TTL_MS = 25 * 60 * 1000;
+const GH_TIMEOUT_MS = 15 * 1000;
+const SEEN_NUMBERS_CAP = 500; // bound state growth per watch
+
+// Module-level caches. Survives across ticks; reset on engine restart.
+const _entityCache = new Map();         // key -> { prs, fetchedAt, error? }
+const _inFlight = new Set();
+const _tokenCache = new Map();          // account -> { token, expiresAt }
+
+// Override-able lister — default uses real `gh` CLI. Tests inject mocks.
+let _lister = _defaultGhPrList;
+function setLister(fn) { _lister = typeof fn === 'function' ? fn : _defaultGhPrList; }
+function _resetCache() { _entityCache.clear(); _inFlight.clear(); _tokenCache.clear(); }
+
+function _resolveCfg(target) {
+  if (typeof target === 'string' && target.includes(':')) {
+    const idx = target.lastIndexOf(':');
+    const slug = target.slice(0, idx).trim();
+    const author = target.slice(idx + 1).trim();
+    if (!slug || !author || !slug.includes('/')) return null;
+    return { slug, author, ghAccount: null };
+  }
+  if (target && typeof target === 'object'
+      && typeof target.slug === 'string' && target.slug.includes('/')
+      && typeof target.author === 'string' && target.author) {
+    return {
+      slug: target.slug.trim(),
+      author: target.author.trim(),
+      ghAccount: typeof target.ghAccount === 'string' && target.ghAccount
+        ? target.ghAccount.trim()
+        : null,
+    };
+  }
+  return null;
+}
+
+function _validateTarget(target) {
+  const cfg = _resolveCfg(target);
+  if (!cfg
+      || !/^[^/\s]+\/[^/\s]+$/.test(cfg.slug)
+      || !cfg.author) {
+    return 'target must be "owner/repo:author" or an object with slug and author';
+  }
+  if (target && typeof target === 'object'
+      && target.ghAccount !== undefined
+      && (typeof target.ghAccount !== 'string' || !target.ghAccount.trim())) {
+    return 'target.ghAccount must be a non-empty string';
+  }
+  return null;
+}
+
+function _targetKey(target) {
+  const cfg = _resolveCfg(target);
+  if (!cfg) return typeof target === 'string' ? target : JSON.stringify(target);
+  return `${cfg.slug}::${cfg.author}::${cfg.ghAccount || 'configured'}`;
+}
+
+/**
+ * Run a gh subcommand with a per-invocation env, no shell, captured stdout.
+ * Always returns { code, stdout, stderr } — never throws on non-zero exit.
+ */
+function _runGh(args, env, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn('gh', args, {
+      env: { ...process.env, ...env },
+      windowsHide: true,
+      shell: false,
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try { child.kill('SIGTERM'); } catch {}
+      resolve({ code: -1, stdout, stderr: stderr + `\n[gh-author-prs] timeout after ${timeoutMs}ms` });
+    }, timeoutMs);
+    child.stdout.on('data', (b) => { stdout += b.toString('utf8'); });
+    child.stderr.on('data', (b) => { stderr += b.toString('utf8'); });
+    child.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code: -1, stdout, stderr: stderr + `\n[gh-author-prs] spawn error: ${err.message}` });
+    });
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code: code == null ? -1 : code, stdout, stderr });
+    });
+  });
+}
+
+async function _resolveToken(cfg) {
+  const account = cfg.ghAccount || ghToken.resolveAccountForSlug(cfg.slug);
+  if (!account) return { account: null, token: null };
+  const cached = _tokenCache.get(account);
+  if (cached && cached.expiresAt > Date.now()) return { account, token: cached.token };
+  const res = await _runGh(
+    ['auth', 'token', '--user', account, '--hostname', 'github.com'],
+    {},
+    GH_TIMEOUT_MS,
+  );
+  if (res.code !== 0) {
+    _warn(`gh-author-prs: token fetch failed for configured account "${account}": ${res.stderr.trim() || `exit ${res.code}`}`);
+    return { account, token: null };
+  }
+  const token = res.stdout.trim();
+  if (!token) {
+    _warn(`gh-author-prs: empty token for configured account "${account}"`);
+    return { account, token: null };
+  }
+  _tokenCache.set(account, { token, expiresAt: Date.now() + TOKEN_TTL_MS });
+  return { account, token };
+}
+
+async function _defaultGhPrList(cfg) {
+  const { account, token } = await _resolveToken(cfg);
+  if (!token) {
+    return {
+      prs: [],
+      error: account
+        ? `no gh token for configured account "${account}"`
+        : `no configured gh account/token for repository "${cfg.slug}"`,
+      fetchedAt: ts(),
+    };
+  }
+  const args = [
+    'pr', 'list',
+    '--repo', cfg.slug,
+    '--author', cfg.author,
+    '--state', 'open',
+    '--limit', '100',
+    '--json', 'number,title,headRefName,url,createdAt,headRefOid,isDraft',
+  ];
+  const res = await _runGh(args, { GH_TOKEN: token }, GH_TIMEOUT_MS);
+  if (res.code !== 0) {
+    return {
+      prs: [],
+      error: `gh pr list exit ${res.code}: ${res.stderr.trim().slice(0, 500)}`,
+      fetchedAt: ts(),
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.stdout || '[]');
+  } catch (e) {
+    return {
+      prs: [],
+      error: `gh pr list JSON parse failed: ${e.message}`,
+      fetchedAt: ts(),
+    };
+  }
+  if (!Array.isArray(parsed)) {
+    return { prs: [], error: 'gh pr list returned non-array JSON', fetchedAt: ts() };
+  }
+  const prs = parsed
+    .filter((p) => p && typeof p.number === 'number')
+    .map((p) => ({
+      number: p.number,
+      title: String(p.title || ''),
+      branch: String(p.headRefName || ''),
+      url: String(p.url || ''),
+      createdAt: String(p.createdAt || ''),
+      headSha: String(p.headRefOid || ''),
+      isDraft: Boolean(p.isDraft),
+    }));
+  return { prs, fetchedAt: ts() };
+}
+
+function _scheduleRefresh(target, key) {
+  if (_inFlight.has(key)) return;
+  const cfg = _resolveCfg(target);
+  if (!cfg) return;
+  _inFlight.add(key);
+  Promise.resolve()
+    .then(() => _lister(cfg))
+    .then((entity) => {
+      _entityCache.set(key, entity);
+    })
+    .catch((e) => {
+      _entityCache.set(key, {
+        prs: [],
+        error: e && e.message ? e.message : String(e),
+        fetchedAt: ts(),
+      });
+    })
+    .then(() => { _inFlight.delete(key); });
+}
+
+function fetchEntity(target, state) {
+  const key = _targetKey(target);
+  // Test/external override path.
+  if (state && state.ghAuthorPrs && Object.prototype.hasOwnProperty.call(state.ghAuthorPrs, key)) {
+    const inj = state.ghAuthorPrs[key];
+    return inj ? { ...inj, _target: target } : null;
+  }
+  const cached = _entityCache.get(key);
+  const cachedAge = cached && cached.fetchedAt
+    ? Date.now() - new Date(cached.fetchedAt).getTime()
+    : Infinity;
+  if (!cached || cachedAge > CACHE_FRESHNESS_MS) {
+    _scheduleRefresh(target, key);
+  }
+  return cached ? { ...cached, _target: target } : null;
+}
+
+/**
+ * State shape: { numbers: number[], lastFetchedAt?: string, lastError?: string }
+ * `numbers` is the all-time-seen set (sorted, capped at SEEN_NUMBERS_CAP).
+ *
+ * captureState advances by AT MOST ONE new number per tick so bursts drain
+ * lossnessly across consecutive checks (in concert with evaluate).
+ */
+function captureState(entity, prevState) {
+  const prevNumbers = Array.isArray(prevState && prevState.numbers) ? prevState.numbers : [];
+  if (!entity) return { numbers: prevNumbers };
+  const seen = new Set(prevNumbers);
+  const currentReady = (entity.prs || [])
+    .filter((p) => !p.isDraft)
+    .map((p) => p.number)
+    .sort((a, b) => a - b);
+  const newOnes = currentReady.filter((n) => !seen.has(n));
+  let next;
+  if (newOnes.length === 0) {
+    next = prevNumbers.slice();
+  } else {
+    next = [...seen, newOnes[0]].sort((a, b) => a - b);
+  }
+  if (next.length > SEEN_NUMBERS_CAP) {
+    next = next.slice(next.length - SEEN_NUMBERS_CAP);
+  }
+  return {
+    numbers: next,
+    lastFetchedAt: entity.fetchedAt || null,
+    lastError: entity.error || null,
+  };
+}
+
+function _firstUnseenReadyPr(entity, prevState) {
+  if (!entity) return null;
+  const prevNumbers = Array.isArray(prevState && prevState.numbers) ? prevState.numbers : [];
+  const seen = new Set(prevNumbers);
+  const candidates = (entity.prs || [])
+    .filter((p) => !p.isDraft && !seen.has(p.number))
+    .sort((a, b) => a.number - b.number);
+  return candidates[0] || null;
+}
+
+function evaluate(condition, entity, prevState, target) {
+  if (condition !== 'new-pr') {
+    return { triggered: false, message: '' };
+  }
+  // Baseline tick: prevState is empty AND we have no entity yet, or entity is
+  // empty/errored. The engine's checkWatches initializes _lastState by calling
+  // captureState first when _lastState is empty — so by the time evaluate runs
+  // on tick 1, prevState already contains the current `numbers`. New PRs only
+  // appear from tick 2 onward, which is the desired no-backfill behavior.
+  if (!entity) return { triggered: false, message: '' };
+  if (entity.error) {
+    // Errors don't fire — surfaced via _lastState.lastError for the dashboard.
+    return { triggered: false, message: '' };
+  }
+  const newPr = _firstUnseenReadyPr(entity, prevState);
+  if (!newPr) return { triggered: false, message: '' };
+  const cfg = _resolveCfg(target);
+  const slug = cfg ? cfg.slug : '<unknown>';
+  return {
+    triggered: true,
+    message: `New PR on ${slug} #${newPr.number}: ${newPr.title}`,
+  };
+}
+
+function contextVars(entity, prevState, _newState) {
+  const newPr = _firstUnseenReadyPr(entity, prevState);
+  if (!newPr) return {};
+  const cfg = _resolveCfg(entity && entity._target);
+  return {
+    prNumber: newPr.number,
+    prTitle: newPr.title,
+    prUrl: newPr.url,
+    prBranch: newPr.branch,
+    prAuthor: cfg ? cfg.author : '',
+    prHeadSha: newPr.headSha,
+    prCreatedAt: newPr.createdAt,
+    prIsDraft: false,
+    repoSlug: cfg ? cfg.slug : '',
+    ghAccount: cfg ? (cfg.ghAccount || ghToken.resolveAccountForSlug(cfg.slug) || '') : '',
+  };
+}
+
+module.exports = {
+  name: 'gh-author-prs',
+  spec: {
+    label: 'GitHub PRs by Author',
+    description: 'Poll a GitHub repo for non-draft open PRs by a specific author. Fires once per newly-observed PR number.',
+    conditions: ['new-pr'],
+    absoluteConditions: [],
+    validateTarget: _validateTarget,
+    fetchEntity,
+    captureState,
+    evaluate,
+    contextVars,
+  },
+  // Exported for tests
+  _resolveCfg,
+  _targetKey,
+  _firstUnseenReadyPr,
+  setLister,
+  _resetCache,
+};